第一个 MCP 服务端:启动、列出工具、add(2,3) 与缺参恢复

第一个 MCP 服务端:启动、列出工具、add(2,3) 与缺参恢复

这是你第一次搭建 MCP 服务端时最短的一条路:一个只有 add 工具的 stdio 服务端,两种独立的方式验证它真的在工作——一个二十行的客户端脚本,以及官方 Inspector 的命令行模式。全程只跑在你自己的机器上,不需要密钥、数据库或大模型。

服务端代码与全部输出已于 2026-11-20 实跑:Python 3.12.16、SDK mcp==2.3.0(含 mcp-types 2.3.0)、Inspector 2.15.0、macOS x86_64、stdio 传输。同一 SDK 版本的 stdio 场景此前也通过过工单实践页的端到端验证。

你会得到什么

读者问题本页答案
服务端最小代码长什么样12 行:MCPServer + 一个 @mcp.tool() 装饰的函数
怎么确认它在工作客户端脚本与 Inspector CLI 各自列出工具、调 add(2,3) 得 5
参数缺了会发生什么服务端校验拒绝、返回 isError: true、会话不中断,补参重试即恢复
下一步去哪更多工具、资源、HTTP 传输、以及工具设计的深入页

1. 环境

SDK 要求 Python 3.10+。新建虚拟环境并安装固定版本:

python3 -m venv .venv && source .venv/bin/activate
pip install mcp==2.3.0

如果你从 SDK 1.x 的教程过来:2.x 里 FastMCP 已改名为 MCPServer,导入路径是 from mcp.server.mcpserver import MCPServer,导入 1.x 的 mcp.server.fastmcp 会得到一条指路的报错。官方迁移指南见 https://py.sdk.modelcontextprotocol.io/v2/migration/#fastmcp-renamed-to-mcpserver。

2. 写服务端

新建 server.py,全部代码就这些:

"""First MCP server: one tool, stdio transport (mcp SDK 2.3.0)."""
from mcp.server.mcpserver import MCPServer

mcp = MCPServer("Demo")


@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b


if __name__ == "__main__":
    mcp.run()  # stdio by default

三件事值得注意:

  • 函数签名就是契约。 参数类型注解 a: int, b: int 会被 SDK 转成 JSON Schema 随 tools/list 发布;返回类型注解让 2.3.0 自动生成结构化输出(outputSchema)。
  • docstring 就是工具描述。 客户端和大模型靠它判断什么时候该用这个工具。
  • mcp.run() 默认走 stdio。 服务端在自己的进程里读标准输入、写标准输出——这就是宿主应用(Claude Desktop、IDE 插件、Inspector)启动它的方式。直接 python server.py 它会安静地等在stdin上,这是正常的。

3. 验证一:最小客户端

新建 client_check.py。它把服务端作为子进程拉起,完成初始化握手,然后做四件事:列出工具、正确调用、缺参调用、补参重试。

"""Reader-side check: list tools, call add, miss a parameter, recover."""
import asyncio
import json
import sys

from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client


async def main() -> int:
    params = StdioServerParameters(command=sys.executable, args=["server.py"])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            tools = await session.list_tools()
            for t in tools.tools:
                print(f"tool: {t.name} — {t.description}")
                print(f"      schema: {json.dumps(t.input_schema['properties'], sort_keys=True)}")

            ok = await session.call_tool("add", {"a": 2, "b": 3})
            print(f"add(2,3) -> is_error={ok.is_error} content={ok.content[0].text}")

            miss = await session.call_tool("add", {"a": 2})
            print(f"add(a=2)  -> is_error={miss.is_error} content={miss.content[0].text}")

            retry = await session.call_tool("add", {"a": 2, "b": 3})
            print(f"retry     -> is_error={retry.is_error} content={retry.content[0].text}")
    return 0


if __name__ == "__main__":
    sys.exit(asyncio.run(main()))

运行 python client_check.py,实际输出:

tool: add — Add two numbers.
      schema: {"a": {"title": "A", "type": "integer"}, "b": {"title": "B", "type": "integer"}}
add(2,3) -> is_error=False content=5
add(a=2)  -> is_error=True content=Error executing tool add: 1 validation error for addArguments
b
  Field required [type=missing, input_value={'a': 2}, input_type=dict]
    For further information visit https://errors.pydantic.dev/2.14/v/missing
retry     -> is_error=False content=5

四个结果逐条对上:工具被列出来了;add(2,3) 返回 5;只给 a 时服务端返回 is_error=True;同一个会话里补上参数重试,又拿到 5——服务端没有崩溃,连接没有断。服务端那侧的 stderr 也会记一笔拒绝原因:

Tool 'add' rejected arguments: ['b']

4. 验证二:Inspector 命令行

不写代码也可以验证。Inspector 是 MCP 官方调试工具,--cli 模式下三条命令覆盖同样的路径。前置条件是装有 Node.js 与随附 npm 的 npx(实测 Node v22.23.4、npm 10.9.9;npx -y 按需拉取包,无需全局安装):

npx -y @modelcontextprotocol/[email protected] --cli python server.py --method tools/list

实际输出的节选——省略了 SDK 自动生成的 outputSchema(addOutput 声明结构化结果字段 result),其余字段原样:

{
  "tools": [
    {
      "name": "add",
      "description": "Add two numbers.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "a": { "title": "A", "type": "integer" },
          "b": { "title": "B", "type": "integer" }
        },
        "required": ["a", "b"],
        "title": "addArguments"
      }
    }
  ]
}

调用成功(注意 structuredContent——2.3.0 对注解了返回类型的工具自动附带结构化结果):

npx -y @modelcontextprotocol/[email protected] --cli python server.py \
  --method tools/call --tool-name add --tool-arg a=2 --tool-arg b=3
{
  "content": [
    {
      "type": "text",
      "text": "5"
    }
  ],
  "structuredContent": {
    "result": 5
  },
  "isError": false
}

缺参调用——返回体是 isError: true 加校验错误全文,进程退出码是 5:

npx -y @modelcontextprotocol/[email protected] --cli python server.py \
  --method tools/call --tool-name add --tool-arg a=2
{
  "content": [
    {
      "type": "text",
      "text": "Error executing tool add: 1 validation error for addArguments\nb\n  Field required [type=missing, input_value={'a': 2}, input_type=dict]\n    For further information visit https://errors.pydantic.dev/2.14/v/missing"
    }
  ],
  "isError": true
}

5. 缺参时到底发生了什么

把三个视角拼起来,缺参恢复的机制就完整了:

  1. 服务端拒绝在参数层。 SDK 在进入你的函数体之前用 addArguments 模型(由类型注解生成)校验入参,b 缺失直接抛校验错误——你的代码从未执行,所以不存在"算了一半"的脏状态。
  2. 错误作为正常结果返回。 tools/call 的响应本身是成功的 JSON-RPC 响应,工具失败体现在 isError: true 与错误文本里;会话、后续调用、其他工具都不受影响。
  3. 恢复就是重发。 客户端补上 b 重新 call_tool 即可;Inspector 的退出码 5 对应"工具报告了错误",把参数补全再跑一次就回到 0。

这组语义(校验前置、错误内聚、会话存活)是 MCP 工具调用失败处理的地基;写出有效的工具在此基础上讨论更上层的错误设计。

6. 下一步

版本与验证说明

实测环境:macOS x86_64(Darwin 21.6)、Python 3.12.16、mcp==2.3.0 与 mcp-types==2.3.0(传递依赖锁定记录:pydantic 2.14.4、uvicorn 0.54.0、cryptography 44.0.3——最后者为运行环境兼容所选,mcp 本身不依赖其特定版本)、Inspector @modelcontextprotocol/[email protected](Node v22.23.4、npm 10.9.9,经 npx 拉取)、stdio 传输、本机回环。本文 console 输出与两份 tools/call JSON 为当日实际运行结果、原样呈现;tools/list JSON 为已标注的节选(省略 outputSchema,其余字段原样)。API 事实(MCPServer 命名、input_schema/is_error 字段、mcp.run() 传输默认值)以所装 2.3.0 包内源码与官方迁移指南为准。

未覆盖:streamable-http 等远程传输与 401/403 授权路径、Windows 环境、把服务端接入 Claude Desktop 等宿主的配置步骤、以及并发调用下的行为。这些沿上表"下一步"各页的实测边界为准。