MCP开发-05.从0开发一个MCP

目标与环境

从 0 做一个能被 LLM 调用的 MCP，可以概括成三件事：

用 SDK 写一个 Server，至少暴露一个 Tool。
在本地或服务器上 按需或常驻 启动该进程（传输见 03 部署与调用）。
在 MCP Host（Cursor、Claude Desktop 等）里写入配置，让 Client 发现并调用工具。

环境与依赖

项	说明
Python	建议 3.10+，以 python-sdk 当前要求为准。
安装 SDK	`pip install "mcp[cli]"` 或 `uv add "mcp[cli]"`。
虚拟环境	单独 `.venv`；Host 里 `command` 指向该环境 Python 绝对路径。

心智模型（排错时有用）： 一块是 协议与进程（如何被拉起、stdio/HTTP、消息收发）；一块是 业务逻辑（参数、算法、读写文件与 API）。先跑通 stdio + 单 Tool，再考虑远程与工程化。

用 uv 初始化（推荐）

1 2	uv init sum-mcp-demo && cd sum-mcp-demo uv add "mcp[cli]"

将下面示例保存为 server.py，用 uv run python server.py 本地试跑（stdio 模式下通常由 Host 拉起，而非手动运行）。

步骤一最小代码

下面用 FastMCP（官方 SDK）暴露一个工具：两整数相加。函数名避免使用 sum，以免遮蔽 Python 内置函数。

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("sum_int_tool")


@mcp.tool()
def add_ints(a: int, b: int) -> int:
    """两整数相加。

    Args:
        a: 整数 a
        b: 整数 b

    Returns:
        两数之和
    """
    return a + b


if __name__ == "__main__":
    # stdio：由 Host 以子进程启动，经 stdin/stdout 通信
    mcp.run(transport="stdio")

Docstring 与 类型注解 会参与工具元数据，影响模型何时、如何传参。
mcp.run(...) 会阻塞；日志请写 stderr，不要用 stdout 打印「启动成功」。
不同版本 import 可能存在差异。

步骤二 stdio 配置

配置示例

stdio 模式写「可执行文件 + 参数」，由 Host 拉起子进程。字段名、是否嵌套 mcpServers 因产品而异。

{
  "mcpServers": {
    "sum_int_tool": {
      "command": "/abs/path/to/sum-mcp-demo/.venv/bin/python",
      "args": ["/abs/path/to/sum-mcp-demo/server.py"],
      "autoApprove": []
    }
  }
}

路径：脚本与 Python 均用绝对路径；Windows 下注意 JSON 转义或使用正斜杠。
解释器：勿用裸 python，须指向已安装 mcp 的 .venv。
安全：autoApprove 含义因 Client 而异；生产或敏感环境先了解再改。

配置成功后，在工具/插件面板中应能看到服务已连接。

配置示例

试用

在对话中明确要求使用 MCP 工具计算两数之和，确认调用了 sum_int_tool。

调用示例

步骤三 HTTP（可选）

远程部署概念见 03 部署方式与调用配置。

stdio：本机、Host 拉起，IDE/桌面端最常见。
Streamable HTTP：需要独立 URL、多机或网关；远程标准传输。

入口里只保留一种 mcp.run：

1
2
3

if __name__ == "__main__":
    # mcp.run(transport="stdio")
    mcp.run(transport="streamable-http")

Client 侧改为填写 URL（例如 http://127.0.0.1:8000/mcp，以 SDK 默认与日志为准），而不是 command + args。

Serverless 或多副本 部署时，查阅 SDK 的 stateless_http、json_response 等参数；新部署建议优先无状态模式（与 01 §8 2026 演进一致）。

用 Inspector 自测 HTTP 服务

1	npx -y @modelcontextprotocol/inspector

在 Inspector 界面填入 MCP 端点 URL，测试连接与工具调用。

排错与调试思路

现象	可检查项
Host 显示未连接	`command` / `args` 路径；JSON 语法；该 venv 是否已 `pip install mcp`。
模型不调工具	提示词是否明确要求；工具名与描述是否清晰；Client 是否需手动授权工具。
HTTP 不通	防火墙、端口、URL 路径；是否误用 stdio 配置格式。
HTTP 404 session	多实例无粘性负载；Serverless 用了有 session 模式 → 改 `stateless_http`。
HTTP 403	Origin 校验失败；检查 Host 与 Server 的 Origin / 绑定地址。
Tasks 无响应	Host 是否支持 Tasks；是否需 FastMCP 2.14+ 或降级为三 Tool 模式（见 04）。

调试顺序：进程有没有被拉起 → initialize 是否成功 → tools/list 是否有工具 → 单次 tools/call 参数与返回值。

小结与延伸

阶段	要点
开发	`FastMCP` + `@mcp.tool()`，docstring 与类型写清楚
本地 stdio	`transport="stdio"` + Host 子进程绝对路径
远程	`streamable-http` + URL；生产加 TLS 与认证
进阶	Resources / Prompts / Tasks → 06 进阶示例

延伸阅读： MCP Python SDK · 协议官网

目标与环境

环境与依赖

用 uv 初始化（推荐）

步骤一 最小代码

步骤二 stdio 配置

配置示例

试用

步骤三 HTTP（可选）

用 Inspector 自测 HTTP 服务

排错与调试思路

小结与延伸

步骤一最小代码