mcp

Model Context Protocol 的服务器、客户端与接入配置。

补充说明

MCP 是让模型应用连接外部工具和数据源的开放协议，基于 JSON-RPC。服务器暴露 tools、resources、prompts；客户端（Claude Code、IDE、桌面应用）负责发现并调用。

传输方式主要有 stdio 和 Streamable HTTP。stdio 适合本地进程，HTTP 适合远程共享服务；早期 SSE 传输已被 Streamable HTTP 取代，新旧客户端要匹配协议版本。

安装与启动

pip install -U "mcp[cli]"

Python SDK 自带 FastMCP，适合快速写工具服务器：

cat > server.py <<'PY'
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("ops-tools")

@mcp.tool()
def disk_usage(path: str = "/") -> dict:
    """返回指定路径的磁盘总量、已用和可用字节数。"""
    import shutil
    usage = shutil.disk_usage(path)
    return {"total": usage.total, "used": usage.used, "free": usage.free}

@mcp.resource("config://app")
def app_config() -> str:
    """返回应用配置摘要。"""
    return "env=prod\nregion=cn"

if __name__ == "__main__":
    mcp.run(transport="stdio")
PY
python server.py

stdio 服务器启动后不会打印欢迎信息，stdout 已被 JSON-RPC 占用。

常用示例

在 Claude Code 中注册 stdio 服务器：

claude mcp add --transport stdio ops-tools -- python /abs/path/server.py
claude mcp list

用 Inspector 调试工具列表和调用参数：

npx -y @modelcontextprotocol/inspector python /abs/path/server.py

远程部署改用 Streamable HTTP，并加认证：

# server.py 中改为 mcp.run(transport="streamable-http")
claude mcp add --transport http ops https://mcp.example.com/mcp \
  --header "Authorization: Bearer $MCP_TOKEN"

易错点与排错

• stdio 模式下任何 print 或日志写到 stdout 都会破坏 JSON-RPC 帧；日志一律走 stderr 或 logging。
• 工具描述和参数类型来自函数签名与 docstring；缺少类型注解时客户端拿到错误 schema，模型无法正确传参。
• 相对路径按服务器进程的 cwd 解析，不是用户工作区；工具里使用绝对路径或显式配置根目录。
• 远程 HTTP 服务没有认证就暴露公网，等于把内网工具交给任何人；至少加 bearer token 或 OAuth，并限制来源。
• 客户端用 SSE、服务器用 Streamable HTTP（或反过来）会连接失败；确认双方支持的传输和协议版本。
• GUI 客户端启动的进程 PATH 很短，python 可能不是你以为的解释器；在配置里写绝对路径并固定虚拟环境。
• 工具执行时间超过宿主超时会被中断，但服务器侧可能仍在运行；为长任务设计幂等和状态查询接口。
• 工具返回超大文本会挤占模型上下文；分页、截断或只返回摘要，并给出行数/字节数。
• npx 启动的服务器每次可能下载不同版本；生产配置固定包版本，离线环境预装依赖。

读完自测

合上页面，先回答，再展开对照。

1. stdio 和 Streamable HTTP 分别适合什么场景？
2. 为什么 MCP 服务器不能往 stdout 打印日志？
3. 工具 schema 从哪里来？

相关条目

• langgraph
• crewai
• autogen
• ollama
• langchain