MCP协议两种模式详解：stdio本地管道与HTTP远程传输

刚开始接触 Model Context Protocol也就是大家常说的 MCP的人通常会在同一个问题上绕圈子这个协议到底支持哪两种模式原因很简单MCP 的官方文档把 JSON-RPC、Tool、Resource、Transport 这些概念铺得很开直接用反而容易懵。我自己的理解更偏向把“两种模式”按传输层来切也就是本地进程内的 stdio 模式和走网络请求的 HTTP 模式对应最新的 Streamable HTTP 传输。搞懂这两个模式后面再看 Cursor、Claude Desktop、Figma MCP、Blender MCP、IDA Pro 这些五花八门的集成心里马上就有一张地图了。这篇文章就从“哪两种模式”这个问题出发把两种模式的工作原理、配置方式、避坑经验一次说透。先说结论目前 MCP 的主流实现里传输层就是两条路一条是 stdio另一条是基于 HTTP 的远程传输。早期版本的 HTTP over SSE 现在已经合并进了 Streamable HTTP 规范所以与其说是三种不如说就是本地和远程两种形态。1. MCP 的“两种模式”到底指什么1.1 MCP 的最小组成客户端、服务端、传输层MCP 不是一个具体的服务而是一套“让 AI 应用和外部工具/数据源对话”的协议框架。框架里有三个角色理解这三个角色才知道“两种模式”是在说谁。客户端MCP Client指那些想接入工具的 AI 应用比如 Claude Desktop、Cursor、Codex CLI、自研的 AI Agent。服务端MCP Server把某个能力封装成标准接口比如读本地文件、操作浏览器、查询某个数据库、控制设计软件。传输层Transport连接两者的管道决定消息以什么格式、走什么通道传递。传输层就是“两种模式”出现的层级。MCP 官方把传输层分成两类一类是进程内部的 stdio另一类是基于 HTTP 的网络传输。它们之间的差别不是“本地快一点”这种维度而是整个部署架构、通信方式、权限边界都完全不同。1.2 stdio 和 HTTP本质区别是什么stdio 模式是标准输入输出模式。客户端在本地启动一个子进程这个子进程就是 MCP Server然后通过进程的标准输入 stdin 和标准输出 stdout 来读写 JSON-RPC 消息。可以理解成两个人在同一台机器上通过一根“管道”传纸条纸条上写的是 JSON-RPC 格式的请求和响应。HTTP 模式走的是网络。客户端通过 HTTP 请求访问一个远程或本地的 URL 端点比如http://127.0.0.1:8080/mcp或https://mcp.example.com/mcp。最新的 Streamable HTTP 要求客户端和服务器之间通过 POST 请求发送 JSON-RPC 消息服务端则可以用 SSEServer-Sent Events流式推送响应。这就像两个人不在一个屋里通过寄信和回信的通道完成通信只是这个通道是标准 HTTP 协议。1.3 为什么会被“两种还是三种”搞糊涂很多人在查资料时会看到“stdio Streamable HTTP HTTPSSE 三种传输”的说法然后就卡住了。这里我简单解释一下历史MCP 早期规范里网络传输方式叫 HTTPSSE需要单独处理 SSE 端点和 POST 端点来收发消息。2025 年 3 月官方把规范迭代成了 Streamable HTTP将两类端点合并为一个/mcp端点弃用了旧的 HTTPSSE 方式。所以站在今天看你只需要关心两类本地 stdio以及统一的 HTTP Streamable 传输。旧模式在迁移过程中逐渐退出遇到老教程里写sseEndpoint的直接把它视为过时配置就好。2. 模式一stdio本地工具链的默认管道2.1 它的工作原理是怎么跑的在 stdio 模式下整个通信过程可以拆成四步MCP Client 根据配置文件里写的命令在本地启动一个子进程比如npx some/mcp-server。客户端把 JSON-RPC 消息写入子进程的 stdin。子进程MCP Server处理完请求后把响应写到自己的 stdout。客户端从子进程的 stdout 读取消息然后解析出结果。注意stdout 是“业务通道”而日志信息不能走 stdout。无论是 SDK 内部代码、业务日志还是调试输出都必须写到 stderr。为什么因为只要日志往 stdout 里混了客户端解析 JSON-RPC 就会失败轻则消息乱序重则整个会话直接失效。这一点是我见过的新手犯得最多的错误。那客户端是怎么知道子进程对应哪个服务的这取决于宿主应用的配置。以 Cursor 为例你在mcp.json或设置面板里配置一个 server填写命令、参数和环境变量保存后宿主就会根据这些信息拉起进程。配置的本质不是“网络连接”而是“进程启动参数”。2.2 什么时候优先选 stdiostdio 模式最典型的应用场景是“本地、单机、进程内”的工具本地文件读取和筛选比如搜索本地文本、读取某个目录下的文件列表调用本地 CLI 工具的能力比如通过命令行工具执行特定操作连接本地数据库或私有数据源数据不出本机开发调试阶段封装的一个临时 MCP Server配合 Cursor 或 Claude 快速验证需要直接操作桌面工具的插件比如 Blender MCP 在本地启动后AI 客户端通过本地子进程控制 Blender。用生活例子去类比stdio 更像“插 U 盘”你把这个服务插在本地 AI 应用的插槽上数据流动只在本机内部不经过网络安全边界好控制。2.3 一个可以照着配的 stdio 配置示例这里我给一个最简单的 Node.js 示例。我假设你已经有一个 MCP Server 会用官方 SDK 启动项目里执行入口是build/index.js那么在 Cursor 的 MCP 配置里可以这样写{ mcpServers: { my-local-server: { command: node, args: [/absolute/path/to/build/index.js], env: { MY_ENV: some-value } } } }如果你用的 Python 写的 server也可以用uvx或python作为 command{ mcpServers: { my-python-server: { command: uvx, args: [mcp-server-mypackage], env: {} } } }几个小细节值得提醒写绝对路径别写相对路径。很多宿主进程的工作目录不是你项目根目录相对路径一换环境就炸。环境变量尽量都显式给全。因为这种子进程不会继承宿主应用的全部环境变量有些情况下连PATH都不是你预期的。不要加“启动后自动退出”的逻辑server 需要保持进程阻塞等 stdin 里的消息。2.4 stdio 模式调试心得stdio 模式调试记住一个原则先直接手动试进程再交给客户端。手动试的方法很简单你拿着配置里的 command 在终端启动然后往 stdin 里敲 JSON-RPC 消息。比如{jsonrpc:2.0,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:manual,version:0.1}},id:1}如果进程本身有问题这里就能看到报错。如果手动能正常响应再去看客户端侧配置。另外SDK 里通常有调试开关。以官方 TypeScript SDK 为例在 server 启动时设置MCP_DEBUG环境变量或在代码里为 logger 指定输出到 stderr 都可以把调试信息打出来。日志文件建议单独写到一个本地文件里不要动不动就塞给宿主日志面板因为那些面板可能也会过滤或截断消息。提示stdio 的“双向通信”只是协议层面的表现它在底层依然是单进程同步 IO。也就是说如果 MCP Server 里有个任务长时间阻塞、不返回消息AI 应用侧就只能干等。这个问题在“长时间任务”一节里我会重点讲。3. 模式二HTTP远程能力和局域网共享的做法3.1 Streamable HTTP 到底改了什么HTTP 模式的核心是“客户端用 URL 来访问 MCP 服务”。这个 MCP Server 可以跑在另一台机器上也可以跑在本地的一个端口上关键是它变成了一个可以被 HTTP 访问的端点。Streamable HTTP 规范把消息格式统一成这样-客户端通过POST请求把 JSON-RPC 消息发到/mcp端点服务端可以把响应放在 HTTP Response 里直接返回也可以通过SSE流式返回多个消息需要保持会话时服务端会返回一个Mcp-Session-Id头客户端再发起请求时带上这个头服务端就知道这是同一个会话。这种设计的好处非常明显只需要一个端点、一套工具链就能完成全部通信不需要再区分什么“消息接收端”和“事件推送端”。举个实际请求的例子curl -X POST https://your.mcp.server/mcp \ -H Content-Type: application/json \ -H Authorization: Bearer TOKEN \ -d {jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:curl-test,version:0.0.1}}}如果你在终端里看到返回里带serverInfo和capabilities说明 HTTP 端点已经在正常工作了。3.2 哪些常见的集成用 HTTP 模式HTTP 模式在真实世界里几乎是“远程工具集成”的代名词Figma MCPFigma 团队提供了托管在远程地址的 MCP Server通过 OAuth 鉴权AI 客户端连接这个 URL 后可以读取设计稿结构、图层、标注甚至有人会直接用 Figma MCP 完成简单切图标注。要注意官方这套通常是远程托管的 HTTP 模式不是本地进程IDA Pro MCP安全分析场景里常把二进制逆向数据导出到 MCP Server配合 AI 辅助分析。这类服务可以跑在本地端口上但客户端通过 HTTP 连接团队共享的数据库查询服务把一个封装了公司内部知识库的 MCP Server 部署在服务器上本组所有人的 AI 客户端都通过 HTTP 访问同一个服务避免每个人各自配置一遍本地进程云平台相关的 MCP Server例如 Language Server、运维诊断类工具不少都提供远程端点。这里尤其要提 Figma MCP。很多人以为它像 Cursor 本地插件一样下载安装就行但实际体验下来Figma 的官方 MCP 更多是给你一个远程 URL你用客户端连过去通过授权后就能操作当前画布。这种远程模式的好处是“谁都不用装太多依赖”但代价是必须处理好认证、权限和网络可达性。3.3 HTTP 模式的安全与权限边界用 HTTP 模式我会把安全问题提到最高优先级因为一个没设鉴权的 MCP Server等于把你的工具能力开放给了整个内网。至少要做三件事鉴权不要让服务裸奔。MCP 规范支持通过Authorization头传递 Bearer Token也支持 OAuth 2.0 授权。如果服务只跑在内网也可以用 IP 白名单的方式收紧。校验来源如果你挂了网关要确保网关能识别并转发带 Session ID 的请求也要注意 CORS 策略不要放得太宽。限流AI 客户端会自动重试高并发对 MCP Server 的冲击不容小觑。尤其你的 Server 背后还连了数据库、设计工具这些重资源时限流是必须的。我在实际部署里习惯把 HTTP 模式的 MCP Server 放在一个独立网关后面由网关负责鉴权、SSL 和路由Server 本体不直接暴露到公网。这样做的好处是即使 MCP 本身遭遇异常请求Socket 层和鉴权层已经帮你挡住了大部分麻烦。3.4 HTTP 模式调试建议HTTP 模式调试比 stdio 好做很多因为你可以直接用浏览器或 curl 模拟请求。先不用 AI 客户端自己先按 initialize、tools/list、tools/call 的顺序走一遍看返回是否正常然后再到 Cursor 或 Codex CLI 里配置真实连接。一个特别容易踩的坑是“配置的 URL 路径不对”。有些 MCP Server 会把完整的根路径设为/mcp有的设为/sse/mcp有的直接在/下。如果你在客户端配置里写错路径通常是 404 或者 405。遇到这种问题别急着怀疑协议先确认路径、端口、请求方法对没对上。4. 两种模式怎么选决策判断框架4.1 按场景快速判断MCP 开发里最常见的一个问题是“我这个场景到底用哪种模式”。我一般会按下面这个顺序去判断服务只给本机 AI 应用用、不分享给其他人优先 stdio。好处是配置简单没有网络鉴权这堆事。服务部署在别人都要访问的机器上或者要共享给团队成员优先 HTTP。你需要的是一个长期在线、统一管理的入口。服务要跟远程软件联动比如 Figma 云端画布、在线文档优先 HTTP。因为这些服务的数据本来就在远程。服务操作本地 GUI 软件比如 Blender 控制一个本地建模窗口优先 stdio这样做更贴近“本地进程 本地 GUI”的感觉。你对数据隐私极度敏感、不能出内网优先 stdio 或内网 HTTP两者都行重点是有没有额外鉴权。同样直接给个速查表判断维度stdio 模式HTTP 模式适用主体单机、单用户多用户、跨机器配置复杂度低填个命令中高需要 URL、鉴权、网络消息通信stdin/stdout 管道POST SSE日志观察必须走 stderr可以放在 HTTP 统一日志进程生命周期跟随宿主进程启动/退出服务常驻运行安全性默认覆盖本机边界需要自己加强鉴权典型例子本地文件工具、CLI 封装、Blender 本地控制Figma MCP、团队共享知识库、云端数据工具4.2 宿主应用配置差异不同客户端对两种模式的支持程度略有差异但整体上都覆盖。比如 Cursor 的 MCP 面板里可以填命令式的本地 Server也可以填 URL 远程 ServerClaude Desktop 的配置文件同时支持command和url两种字段Codex CLI 里配置 MCP 时你可以指定 transport 类型为stdio还是http。一个值得留意的点不要以为“客户端支持 HTTP 模式”就可以完全替代本地模式。有些客户端会在每次启动时重新初始化 MCP 连接如果远程 URL 不可达这个客户端的整体启动速度都会被拖慢。比如你在 Codex 里配了一个超时的远程 MCP请求到了 30 秒没回应整个工具的交互节奏都会被打乱。这就是为什么很多 CLI 工具的 MCP 客户端会给你一个超时配置字段而不是默认无限等。4.3 一种实用的折中方案本地 stdio 包装远程服务现实里你可能会遇到一个远程 HTTP 的 MCP Server但客户端里本地 stdio 配置更顺手。这时候可以把这两者结合起来做一个“本地包装器”在本地启动一个小进程它通过 stdio 与 AI 客户端通信内部再把消息转发到远程 HTTP 端点。写这类包装器的时候核心就是做好消息格式的“翻译”。因为 stdio 和 HTTP 走的都是 JSON-RPC 消息底层消息体往往是一致的你甚至不需要改太多内容只需要把 stdio 收到的字节流转成 HTTP 请求发出去再把 HTTP 返回值写到 stdout。有现成的轻量脚本可以做这事也有人用 ts-node 或 bun 跑一小段代码。场景不复杂的话用一两百行代码就能搞定只是要注意超时和会话 ID 的维护。我的建议是如果只是为了个人使用能直接配 HTTP 就直接配如果客户端限制较多再用包装器做修改。包装器思路适合“统一入口”但多一层转发就多一层故障点不要在不需要的场合硬上。5. 实操里最容易踩的坑和对应排查方法5.1 启动后 30 秒超时的排查很多人配完 MCP Server 后遇到的第一个报错是类似mcp client for codex_apps timed out after 30 seconds。这个超时提示的意思是客户端已经尝试初始化 MCP 连接但服务端一直没回响。排查路径我给一个固定顺序先直接启动命令行看进程能不能跑起来、有没有输出错误看是不是PATH不对。某些宿主应用不会加载你 shell 环境变量导致系统找不到node、npx、uvx这种最简单看是不是 Initialize 握手没完成。有一些 Server 必须收到第一个 initialize 消息后才会进入正常状态你如果配置了某些“预加载参数”阻塞了进程自然就超时看日志里是否有 JSON-RPC 解析错误。多数情况是 stdout 混入了日志把通信管道破坏了。5.2 stdio 配置里的命令转义和参数拼接在配置 JSON 里写启动参数经常会遇到转义问题。比如某个 Server 要求传--allow-path /data/my folder中间带空格Windows 和 macOS 的处理方式就不一样。建议把所有需要传递的参数都写进args数组不要拼到一个庞大的 shell 字符串里。我的经验是凡是你能在 JSON 里用数组拆开写的就不要用 shell 整体串起来。这样能少掉一半跨平台问题。还有环境变量。如果你检查 Server 时发现某个环境变量始终为空可以先在 Server 代码里打印process.env看看宿主到底传了什么。因为不少 AI 客户端对敏感配置有白名单机制不是你想传什么都能传进去。5.3 HTTP 模式没有带鉴权头HTTP 模式最容易出的问题是“明明 URL 能打开但客户端连接不上”。这种情况十有八九是鉴权头没带对。有的 MCP Server 要求Authorization: Bearer xxx有的要求你在 URL 里带 token有的则要求在请求头里带Mcp-Session-Id。你拿 curl 先试一下看到底缺什么。如果服务端是自己写的再看 SDK 里有没对 header 做特殊兼容。5.4 会话和流不结束导致的挂起Streamable HTTP 模式下如果服务端返回 SSE 流客户端会一直保持连接等着事件推送。这个设计对“服务端主动推送事件”很友好但如果你在处理一个纯同步工具服务端却用流式响应而不是一次性返回客户端的体验就会变成“等了很久没返回”。我的建议是工具的处理逻辑若是一次性的就让它一次返回 JSON 结果只有在需要长时间运行、状态更新频繁时才用流式推送。大多数 MCP Client 对一次性响应处理得更顺手流式响应反而容易触发超时判断。5.5 日志文件路径和自定义日志管理很多 MCP Server 默认用 console 打印日志。一旦它被当作 stdio 子进程启动日志必须走 stderr否则会污染 stdout。更稳妥的做法是把日志写到指定的logs/mcp-server.log文件里并按时间戳切分。我写 Server 时会参考这样的代码思路把日志对象直接绑定到 stderr 流或者写入滚动文件。这样既能保存现场又不会破坏协议管道。如果你用的是第三方封装的 MCP Server至少也确认它能配置 log path否则出问题时你只能靠“猜”。提示不要迷信“默认日志一定在终端里”。多数宿主会用全屏 TUI 接管终端展示你的日志可能在它自己的界面里根本看不到。最好一开始就把日志文件路径定好。5.6 多个客户端同时连接同一个 stdio 进程stdio 模式的 Server 是“一对一”的一个子进程对应一个客户端不像 HTTP 那样天然支持多连接。如果你在多个应用里重复配置同一个 stdio 命令每个应用都会自己拉起一个独立进程这是正常的不要试图共享。但如果你一定要让一个本地服务被多个客户端共享那就把它改造成 HTTP 模式访问同一个 URL 端口。我见过有人强行用 stdio 做共享结果既丢消息又把机器资源吃满了。6. 一些真正能提升效率的组合建议6.1 用 stdio 模式做本地文件级工具如果你的目标是把本地的项目目录交给 AI 去读stdio 模式绝对是最省心的选择。假设你写了一个本地 MCP Server能让 AI 读取当前仓库的目录结构和指定文件内容那 Cursor 里连接它后可以直接让它分析某个模块的代码结构也可以检查配置里的依赖关系。这类需求不需要任何网络也不用担心鉴权跑起来非常顺畅。6.2 用 HTTP 模式快速接入外部专业服务团队协作或需要外部数据时优先选 HTTP 模式的现成服务。比如你在设计团队里想接 Figma MCP那就直接配置 Figma 提供的远程 URL授权一次后AI 可以读取画布里的文本、图层间距、命名规范等。这类服务的价值不在于“你维护了什么代码”而在于“你打通了一个生态”。不过要注意Figma MCP 和本地文件工具不一样它有授权范围。你给 AI 的能力是只读还是可编辑直接影响后续操作安全性。建议在授权时选择最小权限不要让 AI 顺手改动设计稿。6.3 从零开发 MCP Server 时先用 stdio 起手如果你正准备开发一个新的 MCP Server我的建议是先用 stdio 模式把工具逻辑跑通再去做 HTTP 部署。原因很简单stdio 模式没有网络鉴权、没有 URL 路由、没有会话管理这些额外负担你可以把精力集中在工具本身的实现上。等工具核心逻辑稳定了再封装一层 HTTP 适配加上鉴权、路由和日志这时的改动通常只是加了一个 Transport 层而不是重写业务逻辑。先本地、再远程是一条能让新手少走弯路的路径。就我个人的体验来说MCP 的两种模式不是“二选一”的关系而是一套协议在不同使用场景下的左右手。真正用好它取决于你什么时候拉起一个进程什么时候开放一个入口。理解这一点后你再去看那些围绕 MCP 的生态工具基本不会迷路。