译文:什么是 MCP?如何使用 Python 构建自定义 MCP 服务器?

原文地址：https://medium.com/data-science-collective/what-is-mcp-build-a-custom-mcp-server-in-python-91ba71830d6a

原文作者： Anubhav

昨天我删掉了三个 Python 文件。它们的名字几乎一模一样——slack_search_for_claude.py、slack_search_for_cursor.py、slack_search_for_chatgpt.py——做的事情也完全相同：调用 Slack API，解析响应，返回匹配的消息。每个文件相隔数月写成，因为每个 AI 工具都需要自己特定形态的封装层。

我用一个 Python 文件替代了这三个：一个 MCP server。Slack 逻辑完全相同，但现在 Claude Code、Cursor 和 ChatGPT 都可以直接读取它。下次 Slack 改动某个字段，我只需修改一处。

Model Context Protocol（MCP）就是让这一切成为可能的标准。本文的其余部分将介绍它究竟是什么，以及如何在一个下午内自己动手构建一个。

MCP，90 秒速览

MCP 简单到可以用三条消息描述清楚。

client 连接到 server 并询问："你能做什么？"

server 回复一个列表，包含模型可以调用的 tool、host 可以拉取的数据，以及用户可以选择的 prompt。然后 client 带着参数调用其中一个 tool，server 执行并回复。这就是整个协议的全部内容。

真正有价值的不是传输格式——而是那份约定。每个现代 AI client 都遵循同一套握手规范：Claude Code、Cursor、ChatGPT（通过网络）、VS Code 的 Copilot 等等。你今天写的 Python 文件，明天可以接入它们中的任何一个。

server 可以暴露三种东西。Tools 是模型按名称决定调用的函数——搜索这个数据库、部署这个分支、总结这条日志。Resources 是 host 随时可拉取的只读数据——配置文件、schema、最近 10 次 commit。Prompts 是用户可选择的可复用模板——Claude Code 中的 slash command，Claude Desktop 中的菜单选项。实际上你主要会交付 tool；resource 和 prompt 有用，但属于二线功能。如果三者只能学一个，学 tool。

消息如何传输是一个只有在开始构建时才需要关心的细节，认证也是如此，只有当 server 面向网络时才会涉及。这些我们之后都会讲到。现在只需记住一件事：一个 server，多个 client，三种可暴露的东西。

为什么以前每次 AI 集成都要付出三倍成本

在 MCP 出现之前，将 AI 工具与后端集成看起来是这样的：编写一个封装层，在你的后端形态和特定 AI client 所需的 tool-calling 形态之间做转换。Claude 需要 Anthropic 的 tools JSON schema，Cursor 有自己的格式，ChatGPT 需要 OpenAI 的 function-calling 格式。底层是同一个 Slack 搜索，外面包裹着三套不同的支撑层。

这道数学题很快就会变得难看。三个 AI client 乘以两个后端（在我的案例中是 Slack 和 GitHub）就是 6 个封装层需要维护。再加一个 AI 工具就变成 8 个，再加一个后端就是 12 个。每个封装层都有各自的 auth 处理、各自的重试逻辑、各自的细微 bug。

MCP 将这一切压缩了。client 和后端不再直接对话，它们都通过协议通信。你的团队下次采用新的 AI client，代价只是一个配置文件，而不是一次全新的集成。

这套机制在设计上是非对称的。client 决定一切——加载哪些 server、何时调用 tool、如何渲染结果。server 的职责要小得多：声明自己有哪些 tool，被调用时响应。正是这种非对称性使协议足够精简，以至于每个主流 AI client 都能在规范发布后一年内完成实现。

用一个文件构建 Standup 助手

standup 助手是工程师反复重写的经典内部工具。它需要读取本地 git log，并总结开发者昨天的工作内容。我们将在一个 Python 文件中把它作为 tool、resource 和 prompt 一并暴露出来。

你需要独立的 FastMCP 包——它是大多数 MCP server（无论什么语言）所依赖的高层 Python 封装。

pip install fastmcp

创建一个名为 standup_server.py 的文件，先导入 SDK 并定义 tool。

# standup_server.pyimport subprocessfrom typing import TypedDictfrom fastmcp import FastMCPmcp = FastMCP("standup-helper")class StandupSummary(TypedDict):    branch: str    since: str    commit_count: int    commits: list[str]@mcp.tool()def summarize_standup(    branch: str = "main",    since: str = "yesterday",) -> StandupSummary:    """Summarize recent git activity for a standup.    Reads the local git log on the given branch since the    given time window. Returns commit count and one-line    subjects for each commit. Used by AI clients via MCP.    """    try:        result = subprocess.run(            [                "git", "log",                f"--since={since}",                "--pretty=format:%h %s",                branch,            ],            capture_output=True,            text=True,            timeout=5,            check=True,        )    except (subprocess.CalledProcessError,            subprocess.TimeoutExpired) as exc:        return {            "branch": branch,            "since": since,            "commit_count": 0,            "commits": [f"git error: {exc}"],        }    lines = [        line for line in result.stdout.splitlines() if line    ]    return {        "branch": branch,        "since": since,        "commit_count": len(lines),        "commits": lines,    }# resource 和 prompt 接下来添加

在幕后，装饰器做了四件事：读取类型注解生成 JSON schema，将 docstring 作为面向 LLM 的描述，在 server 的 capabilities 列表（server 在初始握手期间声明的 tool、resource 和 prompt 列表）中注册该 tool，并将传入的 JSON-RPC 调用路由到这个函数。

subprocess 调用设置了严格的五秒 timeout。如果一条 git 命令无限期挂起，会导致正在等待 tool 响应的 host 应用程序也挂起。对外部调用必须始终设置 timeout。异常处理块返回与成功路径完全相同的字典结构。

一个真实的 standup tool 可能还会调用 GitHub CLI 来拉取待处理的 pull request，只需再添加一次对 gh pr list 的 subprocess 调用并将结果追加到字典中即可。

现在添加 resource 和 prompt，使文件完整。

# standup_server.py（续）@mcp.resource("recent_commits://main")def recent_commits_main() -> str:    """Last 10 commits on the main branch, plain text.    Resources are pulled by the host opportunistically.    They are not invoked by the model the way tools are.    """    result = subprocess.run(        [            "git", "log",            "-n", "10",            "--pretty=format:%h %ad %s",            "--date=short",            "main",        ],        capture_output=True,        text=True,        timeout=5,    )    return result.stdout or "(no commits found)"@mcp.prompt("standup_template")def standup_template(focus: str = "shipping work") -> str:    """Reusable standup question exposed as a prompt    template. Surfaces as a slash command in clients that    expose prompts (e.g. /standup_template in Claude Code).    """    return (        f"Summarize what I worked on yesterday, focusing on "        f"{focus}. Use the summarize_standup tool to get the "        f"git log, then write a one-paragraph standup note."    )if __name__ == "__main__":    mcp.run()

resource 的 URI 只是一个字符串，对 URI 格式没有严格的 schema 约束，但标准约定是 scheme 加路径。如果你想动态传递参数，FastMCP 也支持 URI 模板。

prompt 就是一个返回格式化字符串的函数。client 将其渲染为用户可调用的模板，Claude Code 将其暴露为 slash command。Prompt 永远不会被自动注入，用户必须主动选择它。

最后一行是 server 启动。你不需要配置端口、搭建 HTTP 框架或管理 event loop，FastMCP 会自动处理所有 stdio 样板代码。

Transport 与认证

transport 层决定了 JSON-RPC 消息在 client 和 server 之间的具体传输方式。

当 server 在本地运行时，使用 stdio。host 应用程序会直接将你的 Python 脚本作为子进程执行。stdio 移除了整个网络栈——没有端口、没有 TLS、没有 auth，因为子进程继承了 host 的信任边界。

当 server 需要跨请求保持状态或需要从多台机器访问时，使用 Streamable HTTP。远程 server 面向网络，因此需要严格的认证。

# standup_server.py 底部if __name__ == "__main__":    # 默认 transport 是 stdio。host（Claude Code、    # Cursor、Claude Desktop 等）将此脚本作为子进程启动，    # 通过 stdin/stdout 与之通信。    # 无需端口、TLS、auth。信任边界由启动 host 的人决定。    mcp.run()    # 若要通过网络暴露同一个 server，改用 Streamable HTTP。    # SSE 已在 2025 年 3 月的规范更新中废弃，新代码不要使用。    #    # 生产环境的 HTTP 还需要在前面加一层 auth。    # OAuth 2.1 + Dynamic Client Registration 是当前的标准模式。    #    # mcp.run(    #     transport="streamable-http",    #     host="0.0.0.0",    #     port=8000,    # )

不带参数的默认调用即为 stdio。注释掉的代码块展示了切换到 HTTP 的路径。

本次构建我们坚持使用 stdio，因为它对 95% 的内部开发者工具来说是正确选择。如果你构建的工具只需要读取本地文件或本地 git 仓库，永远不应该将其放在网络接口之后。

确定了运行命令之后，问题不再是 server 如何与 client 通信，而是 server 本身是否正确。这就是 Inspector 的工作。

本地开发循环

永远不要第一步就把 server 直接接入 AI client 来测试。AI client 被设计为具有韧性——它们会静默吞掉 schema 不匹配的错误，忽略缺失的 capability，以保持聊天界面正常工作。如果你的 tool 失败了，client 只会让模型道个歉。

应该使用官方的 MCP Inspector 测试你的 server。它是一个基于浏览器的开发 UI，通过 stdio 与你的 server 通信。

npx @modelcontextprotocol/inspector python standup_server.py

运行此命令后，Inspector 会将你的 Python 脚本作为子进程启动，并打开一个本地 web 控制台。你可以看到原始的 JSON-RPC 握手过程，以及 server 声明的确切 capability。你可以直接在浏览器中点击 tool 和 resource 并实时执行它们。

在这个开发循环中，你会遇到三类错误。最常见的是 schema 不匹配——函数返回的结构与类型注解不符，Inspector 会立即标出。其次是 capability 缺失——你尝试调用一个 server 从未声明的 tool；Inspector 的控制台会精确显示握手期间实际注册了哪些 capability。最令人抓狂的是标准输出污染：一个多余的 print() 会破坏 JSON-RPC 流，因为 stdio 就是传输线路本身。把 print 替换成 Python 的 logging 模块，并配置为写入标准错误——协议明确将标准错误保留给人类可读的日志。

FastMCP 还支持一个开发模式，在你修改文件时自动重启 server。你可以传入 debug 标志，在 Inspector 中工作时启用热重载。

同一个 Server，三个 Client

这就是架构价值兑现的地方。我们只有一个 Python 文件，已在 Inspector 中验证它可以正常工作，现在要把它接入三个不同的 AI client，而不需要写任何一行 client 特定的代码。

每个支持 MCP 的 client 都会读取一个配置文件，来知道要启动哪些本地 server。这个配置文件的 JSON 格式在所有三个 client 中完全相同——它们都期望一个 mcpServers 对象，包含要运行的命令和要传递的参数。

Claude Code：

{  "mcpServers": {    "standup-helper": {      "command": "python",      "args": ["/Users/you/code/standup_server.py"]    }  }}

Cursor：

{  "mcpServers": {    "standup-helper": {      "command": "python",      "args": ["/Users/you/code/standup_server.py"]    }  }}

Claude Desktop：

{  "mcpServers": {    "standup-helper": {      "command": "python",      "args": ["/Users/you/code/standup_server.py"]    }  }}

mcpServers key、command、args——三个 client 完全一致。唯一的区别是每个 client 在哪个路径下查找配置文件。

打开其中任意一个，请求一份 standup。在幕后，client 生成 Python 进程，通过 stdio 协商 capability，将 summarize_standup 暴露给模型，并将模型的 tool 调用路由回你的脚本。git 命令运行，字典返回，模型写出 standup。三个 client 中的代码路径完全相同，没有任何差异。

我们没有把 ChatGPT 列入此次示例，因为 ChatGPT Connectors 目前只支持通过 Streamable HTTP 访问的远程 server。要将这个 standup 助手接入 ChatGPT，你需要通过网络暴露它，并配备公开 URL 和认证层——这是完全不同的运维配置，本次构建严格保持在本地。

MCP 不适合用在哪里

这个协议极其有用，但它不是万能锤。有些特定的架构场景中，MCP 是错误的选择。亚毫秒级延迟路径不适合，因为协议在每次 tool 调用时都会增加一次 JSON-RPC 序列化往返；如果你的 tool 运行在高频生成任务的紧内循环中，坚持使用直接 SDK 集成。流式 tool 响应目前也不被原生支持，尽管已列入 2026 年路线图。如果你需要返回特定的交互式图表或自定义表单，你构建的是 host 集成，而不是 MCP tool，因为协议严格将数据与呈现分离。此外，如果你的团队同时掌控 AI client 和后端，直接集成通常比引入 MCP 边界更容易维护。

协议很小，转变很大

过去六个月里我写的那三个 Slack 脚本，本可以是一个 MCP server。逻辑从来都一样，唯一不断变化的是每个 client 要求的那层适配代码。

协议本身很小。它定义了三种原语、两种 transport 和一次 JSON-RPC 握手。这种精简是刻意为之，它在构建智能的人和构建上下文的人之间划出了一道清晰的边界。

你花一个下午写出第一个 MCP server，在下一个新 AI 工具发布时就能回本——以及之后的每一次。