用 MCP 5 分钟接入第一个工具：从装 SDK 到 Claude Desktop 跑通

2024 年 11 月，Anthropic 把一份名为 Model Context Protocol (MCP) 的协议开源出来，定位是「AI 工具的 USB-C」。到 2026 年第二季度，OpenAI、Google、Microsoft、阿里云百炼、腾讯云、百度全线表态支持；Linux Foundation 也接过了协议治理，成立 Agentic AI Foundation。一个协议在 18 个月里走完 USB-C 当年用 5 年才走完的路。

本文做一件最小的事：用 Python SDK 写一个能读本地文件的 MCP Server，在 Claude Desktop 里把它接上跑通，再简单提一下 Server 端的「传输选型」——这是绝大多数 5 分钟教程不讲清楚、真正落地时又会卡住的点。

一、先回答一个问题：MCP 到底解决什么

MCP 出现之前，每个 AI 客户端（Claude、Cursor、Cline、Continue、Zed）都有自己的「工具/插件」接口，互不兼容。对接一个数据源，写一次，跑通一个客户端，下一个客户端又得改一遍。

MCP 把这件事标准化成 client ↔ server 两端协议：

• MCP Host：跑了 AI 客户端的进程（Claude Desktop、Cursor、VS Code Copilot Chat 等）
• MCP Client：Host 进程内的一个 SDK 实例，负责跟 Server 通信
• MCP Server：你（或第三方）写的小进程，按 MCP 协议暴露 Resources、Tools、Prompts 三类原语

MCP Host 想要调用工具时，直接问 Server 「你有哪些 tool」，拿回自然语言描述 + JSON Schema，再决定要不要 invoke。所有的 client 走同一套流程，server 写一次到处跑。

类比：MCP 就是 LSP（Language Server Protocol）的 Agent 版。LSP 让 VS Code、Sublime、Neovim 共用一套「给 Python 提供补全」的代码；MCP 让 Claude、Cursor、Cline 共用一套「给 LLM 提供工具」的协议。

二、5 分钟跑通：写一个「读本地文件」MCP Server

Step 1: 装 SDK（30 秒）

python3 -m venv .venv && source .venv/bin/activate
pip install "mcp[cli]" httpx
# 当前推荐版本：mcp==1.9.x（pip 拉取最新稳定即可）

验证：

python3 -c "import mcp; print('mcp', mcp.__version__ if hasattr(mcp, '__version__') else 'OK')"

Step 2: 写一个最小 Server（2 分钟）

新建 read_file_server.py：

from mcp.server.fastmcp import FastMCP
from pathlib import Path

mcp = FastMCP("local-file-reader")

@mcp.tool()
def read_file(path: str, max_lines: int = 100) -> str:
    """读取一个本地文本文件，返回前 max_lines 行。
    
    Args:
        path: 绝对路径，例如 /Users/me/notes.txt
        max_lines: 最多返回多少行，默认 100
    """
    p = Path(path).expanduser().resolve()
    if not p.is_file():
        return f"ERROR: {p} is not a file"
    # 安全约束：禁止越界读取敏感路径（示例）
    if any(part.startswith('.') for part in p.parts) and '.ssh' in p.parts:
        return "ERROR: refused to read .ssh/*"
    return '\n'.join(p.read_text(encoding='utf-8').splitlines()[:max_lines])

if __name__ == "__main__":
    mcp.run()  # 默认 stdio 传输

注意三件事：

1. docstring 是关键：MCP 把这个 docstring 原封不动地作为「tool 描述」发给 LLM。写得越清楚，模型调用越准。

2. 类型注解也是协议的一部分：max_lines: int = 100 会被自动转成 JSON Schema 里的 {type: integer, default: 100}。

3. 默认是 stdio 传输：本机通信最简单，零网络配置。生产再换 SSE / Streamable HTTP。

Step 3: 装到 Claude Desktop（1 分钟）

Claude Desktop 的 MCP 配置文件在：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "local-file-reader": {
      "command": "/Users/me/.venv/bin/python",
      "args": ["/Users/me/read_file_server.py"]
    }
  }
}

重启 Claude Desktop。在对话窗口左下角应该看到 🔌 图标亮起，列出 read_file 工具。

Step 4: 第一次调用（1 分钟）

在 Claude Desktop 输入：

帮我读一下 /Users/me/notes/today.md 的前 50 行

Claude 会显式弹一个权限确认框——这是 MCP 的「人在环监督」机制，任何 tool 调用前用户必须同意。确认后，模型拿到返回内容，继续组织回答。

至此，5 分钟跑通链路完成。重点不是代码，是流程——这三步走完，你就有了「写自己的 MCP Server」的可复用范式。

三、用 MCP Inspector 调试

写完 Server 没法直接 print 调试——stdio 传输下你的 print 会跟 JSON-RPC 帧混在一起，调试器一抓就懵。

官方提供了 MCP Inspector（一个可视化调试 web 工具）：

mcp-inspector python /Users/me/read_file_server.py
# 浏览器打开 http://127.0.0.1:5173

界面分三块：

• Resources / Tools / Prompts 列表（看 Server 注册了什么）
• Request 构造器（手工填 JSON 调一次）
• Response 查看器（看原始 JSON-RPC 响应）

实战经验：永远先在 Inspector 里把 Server 跑顺，再接入 Claude Desktop。否则 Host 端弹个 permission denied，你都不知道是协议错了还是权限写错了。

四、传输选型：stdio / SSE / Streamable HTTP

这是 5 分钟教程不讲、但生产必踩的坑。

| 传输 | 适用场景 | 优点 | 缺点 |

|---|---|---|---|

| stdio | 本机调用、子进程模型 | 零网络配置、启动快、最安全 | 不能跨机、不能被远端 Host 用 |

| SSE (HTTP+SSE) | 旧版远程（2025-03 之前主流） | 能跨机、长连接推送 | 需要保活、CDN 容易断、浏览器侧麻烦 |

| Streamable HTTP | 2026 主流远程 | 走标准 HTTP POST + 可选 SSE、CDN 友好、Stateless | 需 OAuth 2.1 / Bearer 鉴权配置 |

2026-03-26 的 spec 更新把 Auth 从草案升正式版，HTTP transport 升级为 Streamable HTTP——所有新项目直接选 Streamable HTTP，不要再选 SSE。

怎么选？默认 stdio（同机）。要跨机或部署在云上，再选 Streamable HTTP。SSE 留给维护旧项目用。

五、一次端到端的握手流程

下图是 Claude Desktop 第一次连上你的 Server 时，实际发生的 5 个 JSON-RPC 帧：

关键点：

• initialize 是握手第一步，失败就全完——Server 端必须正确处理能力声明（capabilities）。
• tools/list 返回的是自然语言描述 + JSON Schema，不是可执行代码。模型自己读描述决定何时调。
• tools/call 才是真正执行——Host 端必须做权限确认，MCP 规范里有「Host 必须在执行前获得用户明确同意」的硬要求。

六、4 个真工程坑（5 分钟教程不讲）

1. docstring 写得烂 → 工具被乱调：模型看到的只是你的 docstring。模糊的「read a file」会让模型在不需要读文件时也调它。把使用场景、典型路径示例、限制都写进 docstring。

2. stdio 模式 print 调试会污染协议流：所有调试输出走 stderr（MCP Host 端只监听 stdout 的 JSON-RPC 帧）。print(..., file=sys.stderr)。

3. 绝对路径 vs 相对路径：Server 进程的 CWD 跟 Host 不一定一致。永远用绝对路径，或者在 tool 里 Path(path).expanduser().resolve() 规范化。

4. 权限边界：MCP Host 必须做 tool-level 权限管控（Claude Desktop 的 permission dialog 就是这个）。Server 端不要假设自己跑在「沙箱」里——自己加 path 白名单 + 敏感目录拒绝。

七、结语：MCP 不是银弹，但已经是事实标准

2026 年的 MCP 已经走过了「是/否」的争论期。它不完美（Simon Willison 指出过「55K token 的工具定义挤爆上下文」的案例；Perplexity CTO 也公开过「MCP 复杂度大于收益」的观点），但它已经大到没法忽略——OpenAI、Google、Microsoft、Anthropic、阿里、腾讯、百度、Docker、Linux Foundation 全部下场。

对个人开发者：学 MCP 的边际成本极低（5 分钟跑通第一个 Server），但复用价值极高（写一个 Server，Claude / Cursor / Cline / Zed / VS Code 都能用）。

对团队决策者：新项目默认按 MCP 思路设计工具层。不要再为单个 AI 客户端写定制插件了。

下一步建议：

• 把团队的「读数据库」「查 Confluence」「触发 Jenkins」三个高频工具改写成 MCP Server
• 用 MCP Inspector 把每个 Server 调通再上 Claude Desktop
• 远程部署用 Streamable HTTP + OAuth 2.1

5 分钟跑通只是开始。MCP 的真正价值，是让你写一次工具，所有 AI 客户端都能用。

参考资料：

官方文档

• Anthropic: Introducing the Model Context Protocol - 2024-11-25
• MCP 官方文档: What is MCP? - 持续更新
• MCP Specification 2025-03-26 - 当前稳定版 spec
• MCP Architecture 详解 - 持续更新
• Claude 官方 MCP 文档 - 持续更新

开源项目

• modelcontextprotocol/python-sdk - 23.5k stars, MIT, 2026-06-30 更新
• modelcontextprotocol/typescript-sdk - 12.8k stars, 2026-06-30 更新
• modelcontextprotocol/inspector - 10.2k stars, 官方调试工具

行业报道

• 腾讯云开发者: MCP 协议 2025 大爆发 2026 走向成熟期 - 2026
• 安全内参: Agent 治理的起点——MCP 提供了兼容性和安全性的技术方案 - 2025-04-16

社区讨论

• HN Algolia: "Model Context Protocol" 搜索 - 持续聚合
• 知乎专栏: 模型上下文协议 MCP 版本 2025-3-26 - 2025

对比基准 / 生态观察

• MCP 官方 Blog: 2026-07-28 Release Candidate - 2026
• MCP 官方 Blog: MCP Apps 发布 - 2026-01

本文由 AI 生成。内容基于公开资料整理，可能存在事实偏差，引用链接请以原始来源为准。