AI Agent / 知识点

MCP 开发速查手册

手册条目

根据本地集成或远程访问需求选择 stdio 或 Streamable HTTP。

选择 stdio 或 Streamable HTTP

先看进程边界:由 MCP 宿主在本机启动、只服务当前宿主时选 stdio;需要独立部署、跨网络访问或同时服务多个客户端时选 Streamable HTTP。不要因为“以后可能远程”就提前引入 HTTP 运维成本。

stdio 与 Streamable HTTP 选择流程

选择表

判断项 stdio Streamable HTTP
启动方式 客户端拉起子进程 服务独立运行
典型范围 单机、单宿主、开发工具 远程服务、多客户端、容器或集群
通信入口 stdin / stdout 单一 MCP URL,例如 /mcp
日志位置 只能写 stderr,不能污染 stdout 应用日志系统;响应仍须符合 MCP
安全重点 可执行文件路径、环境变量、最小权限 TLS、认证授权、Host/Origin 校验、限流

配置示意

下面展示常见宿主配置形态。不同宿主的字段名可能略有差异,但进程型配置与 URL 型配置的边界不变。

json
{
  "mcpServers": {
    "local-tools": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/server.js"]
    },
    "remote-tools": {
      "type": "streamable-http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

生效行为:local-tools 由宿主创建子进程并通过标准流通信;remote-tools 连接已有 HTTP 端点。验证时分别检查子进程是否被拉起,以及远程端点能否完成发现、列出工具和调用工具。

风险与边界

选择 stdio 时,服务向 stdout 打印普通日志会破坏逐行 JSON-RPC,结果通常是初始化失败或消息解析错误。安全替代是把日志写到 stderr,并确保每条协议消息独占一行。

选择 Streamable HTTP 时,直接监听 0.0.0.0 且没有认证、TLS、Host/Origin 校验,会暴露工具调用能力,并可能遭受 DNS rebinding。安全替代是本地仅绑定 127.0.0.1;远程部署放在受控网关后,启用 HTTPS、令牌或 OAuth、来源校验和速率限制。

不要为新项目选择旧式 HTTP+SSE。以 2026-07-28 规范为基线,Streamable HTTP 使用单一 POST 端点,每个请求返回 JSON 或请求级 SSE;独立 GET 流和协议级会话属于旧版本兼容行为。

排障清单

  • stdio 启动即断开:检查绝对路径、运行时版本、工作目录、环境变量和文件权限。
  • stdio 出现解析错误:确认 stdout 只有 MCP 消息,普通日志全部转到 stderr。
  • HTTP 返回 403:检查 Host、Origin、反向代理改写和允许来源。
  • HTTP 能连通但工具不可见:确认客户端连接的是完整 /mcp URL,并检查协议版本与服务注册逻辑。

速查结论:同机、宿主拉起、单客户端优先 stdio;独立部署、跨网络或多客户端选择 Streamable HTTP。

目录与阅读设置

记录一个想法

MCP 开发速查手册

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通