最近在交流群里被问到最多的一个基础问题就是MCP 协议到底支持哪两种模式我最早踩过这个坑当时直接照抄网上的配置把本地脚本路径填进客户端发现同一个 MCP server 根本没法给团队其他人用。后来认真把资料捋了一遍才彻底搞清楚所有关于 MCP 的讨论落到传输层上就两个大方向——一种是走进程标准输入输出的 stdio 模式另一种是走网络接口的 HTTP/SSE 模式。两者传输的消息格式都遵循 JSON-RPC 2.0但通道不同、进程启动方式不同、能力暴露范围也不同。这篇文章我就从概念、原理、配置到选型思路把这套东西完整讲一遍顺便把我在实操中遇到的坑也整理出来给正在配置 Cursor、Claude Code 或自研 Agent 的读者做个参考。1. MCP 的两种模式到底是什么stdio 与 HTTP/SSE 的定位1.1 从配置文件里看到的“两种入口”不管你用哪个客户端现在配置 MCP server 时基本会遇到两类填法。一类是填命令行类似{ mcpServers: { my-tools: { command: python, args: [server.py] } } }另一类是填 URL类似{ mcpServers: { my-tools: { url: http://127.0.0.1:8000/mcp } } }前者就是 stdio 模式后者就是 HTTP/SSE 模式。很多教程里也会把它们称成“本地模式”和“远程模式”说法不同指的基本是同一件事MCP 客户端和 MCP 服务端之间用什么样的物理通道交换数据。1.2 两种模式背后的设计逻辑MCP 全称是 Model Context Protocol它做的核心事情是给 AI 应用提供一套标准化的“工具调用”和“数据访问”接口。既然是接口协议就必须定义消息格式和传输方式。消息格式方面MCP 采用 JSON-RPC 2.0这是一套非常成熟的规范客户端调用服务端的一个工具本质上就是发一条包含方法名和参数的 JSON 请求服务端再返回一个 JSON 结果。传输方式上MCP 选择了两条路线。一条是进程内路线客户端直接拉起一个子进程通过管道和它通信这就是 stdio另一条是网络路线客户端通过 HTTP 请求访问一个常驻服务服务端把结果以流式事件推回来这就是 HTTP/SSE。所谓“两种模式”准确说是两种传输模式也可以理解成两种部署形态。我打个比方stdio 模式像你把一个工具箱直接递到 AI 手里AI 随用随开HTTP/SSE 模式像你把工具箱放到局域网的一间仓库里AI 通过网络远程取用仓库可以由多个人共同维护。1.3 为什么不是一种模式也不是三种有朋友可能看过 MCP 官方文档里的 Streamable HTTP Transport会疑惑是不是出现了第三种模式。这里需要稍微解释一下MCP 规范一直在迭代早期网络模式用的是 HTTP SSE 分离设计客户端发请求走普通 HTTP服务端推送事件走 SSE 单向长连接端点通常是/sse后来规范演进为 Streamable HTTP把请求和事件都揉进同一个 HTTP 通道端点通常是/mcp。但从更大的分类上看这仍然属于“通过网络接口连接的远程模式”和基于进程管道的 stdio 模式是并列的两大类。所以平时说“MCP 支持两种模式”是指 stdio 和 HTTP/SSE或其演进形态 Streamable HTTP这样理解是准确且不过时的。2. stdio 模式本地进程内通道的详细拆解2.1 stdio 模式的工作原理stdio 模式的全称是 Standard Input/Output Transport原理非常简单MCP client 在本地启动 MCP server 对应的子进程然后通过子进程的标准输入stdin写入请求消息从标准输出stdout读取响应消息。两边维持一个 JSON-RPC 2.0 的双向消息流直到某一方主动退出。这里有一个特别容易被忽略的细节server 的日志不能直接往标准输出打印。因为 stdout 已经被协议占用如果代码里写着print(server started)消息会混进协议数据里客户端轻则解析失败重则直接报错。正确做法是用stderr输出日志或者在标准库里配置 logging 模块指向标准错误。这个细节我见过太多次了排查起来非常迷惑。2.2 stdio 模式非常适合哪些场景stdio 模式最典型的落地场景是你需要给你的 AI 编码工具挂上一批本地工具。比如在 Claude Code、Cursor、Continue 这类工具里加一个 Python 脚本、Node 脚本或本地服务封装让 AI 能直接查询本地数据库、读写文件、运行命令行工具。因为进程是随用随起的不常驻、不占端口也不会有端口冲突的问题安全边界非常清晰只有本机用户能触发外部网络访问不到。另外stdio 模式在安全工具领域也特别常见。比如 BurpSuite MCP、IDA MCP、Yakit MCP 等本质上都是把安全分析工具封装成 MCP server由客户端本地拉起、本地调用。这样工具内部自动化的会话、临时文件、凭据都留存在本机不会把敏感操作暴露到网络层。2.3 在 Claude Code 和 Cursor 中的配置示例我先以 Claude Code 为例配置文件通常在项目根目录的.mcp.json或用户目录的配置里写法大同小异{ mcpServers: { weather: { command: python, args: [/Users/me/projects/weather/server.py], env: { API_KEY: your-key-here } } } }这里的env字段很关键很多第三方工具都要求环境变量直接写在配置里能避免污染全局环境。Cursor 的配置也类似一般在项目根目录建.cursor/mcp.json支持同样的字段。配置完成后重启客户端AI 就能自动发现并调用这个工具了。我建议新手第一次跑通过程中最好先用一个最简单的工具函数验证链路比如写一个返回当前时间的函数。链路通了之后再逐步增加复杂工具这样排查问题会省很多时间。2.4 stdio 模式的边界和易踩的坑启动时间过长的坑部分 MCP server 启动时会先做依赖加载、模型初始化如果在本地用npx拉包还会等很久。很多客户端默认连接超时是 30 秒直接导致“连接失败”。我一般先手动在终端里执行一下启动命令确认能正常启动再挂到客户端里。Python 环境不一致客户端进程继承的是客户端的 PATH。你在某个虚拟环境里装好了依赖可用python /path/to/venv/bin/python server.py指定解释器比依赖默认 PATH 稳妥得多。不能用 stdout 打日志前面强调过日志必须走 stderr 或独立的日志文件。退出清理server 进程由客户端管理如果工具里开了线程、临时文件必须在退出钩子里做清理否则会留下僵尸进程或临时资源。3. HTTP/SSE 模式远程 MCP 服务的工作方式3.1 远程模式到底是怎么连的HTTP/SSE 模式现在更常见的说法是 Streamable HTTP Transport解决的问题很直接你想让 AI 客户端通过网络去调用一个服务这个服务可以跑在远程服务器、局域网设备、或者隔壁同事的电脑上而不是仅仅作为客户端本地的子进程。在这种模式下MCP client 首先向一个 HTTP 端点发送 HTTP 请求消息体仍然是 JSON-RPC 2.0 格式。服务端收到请求后执行对应工具再把结果通过事件流推回客户端。在早期实现里这个推送通道使用了 Server-Sent Events也就是 HTTP 长连接服务端推送在现在的 Streamable HTTP 实现里服务端既可以正常返回 HTTP 响应也可以在需要时开启 SSE 会话进行多轮消息交换。端点路径常见的有/mcp和/sse两种具体看服务端实现。3.2 为什么越来越多团队选择远程模式远程模式最大的价值是“一处部署多处调用”。你把工具服务部署在一台服务器上CLI 客户端、桌面客户端、甚至网页应用都能通过 HTTP 访问同一个 MCP 能力。比如团队里维护了一个数据库查询工具将其封装成远程 MCP server那么多个前端开发同学的 AI 外挂都能通过同一个地址获得该能力不需要每个人都在本地装一遍依赖环境、配一遍数据库权限。远程模式也很适合浏览器扩展场景。热搜里提到“谷歌浏览器扩展设置中启用 MCP 连接”、“Chrome DevTools MCP”这些实际是让浏览器侧的能力通过 MCP 暴露出来供 AI 使用。由于浏览器扩展身边跑在独立的进程里用本地 stdio 模式去拉起它并不方便网络模式反而自然得多。Playwright MCP 的远程形态、Cesium MCP 在 GIS 场景里的调用也都是同理。3.3 远程 MCP server 的配置示例在客户端配置里远程 MCP 只需要填 URL 和可选的请求头{ mcpServers: { remote-tools: { url: http://192.168.1.100:8000/mcp, headers: { Authorization: Bearer your-token } } } }如果服务端使用了 API Key、Token 或 OAuth 鉴权请求头里的鉴权字段必须和服务端要求一致。这一点看起来简单实际很容易踩坑很多 server 对鉴权失败返回的是 401 或 403但有些封装库会把错误包装成“连接失败”导致你误以为网络不通绕了一圈最后发现是 token 过期了。3.4 远程模式的注意事项端口与地址要确认好http://127.0.0.1:8000/mcp只能本机访问想给局域网同事用要换成0.0.0.0监听并提供本机局域网 IP 或主机名。回调地址问题早期 SSE 实现中服务端会给客户端返回一个事件的回调端点如果你的客户端和服务端之间有 NAT、防火墙必须确保回调地址可达。这也是很多人在远程模式下配置失败的主要原因。鉴权不能省远程 MCP 暴露在网络上如果不加鉴权等于把内部工具能力直接公开给别人务必使用 Bearer Token、API Key 或更完整的 OAuth 方案。4. 两种模式怎么选对照表和判断思路4.1 一张表看清核心差异维度stdio 模式HTTP/SSE 模式远程通信载体本地进程 stdin/stdoutHTTP/HTTPS 网络接口启动方式客户端按需启动子进程服务端常驻工作进程管理随客户端生命周期独立部署、独立管理适用场景本地工具、本机文件、开发调试团队共享、远程数据、浏览器扩展网络依赖无有需要端口可达鉴权方式一般无需网络鉴权Bearer Token、OAuth、API Key安全边界仅本机进程暴露到网络需主动加固调试复杂度较低像普通命令行程序较高涉及网络、鉴权、回调典型工具Claude Code 本地脚本、IDA MCP、BurpSuite MCP团队共享服务、Chrome DevTools MCP、Cesium MCP4.2 我的选型建议我自己的经验是开发阶段坚决先用 stdio能本地调通就先本地调通。因为 stdio 模式下所有问题都集中在代码逻辑和 JSON 格式上不牵扯网络链路一旦换到远程模式防火墙、端口、鉴权、回调地址这些因素会同时涌进来问题定位成本会成倍上升。等确认工具函数本身没问题之后再看使用方是谁。如果只有自己这台电脑使用挂在本地进程里最省事如果能给团队复用、并且你愿意维护一个常驻服务那就迁到远程模式。另外要注意并不是所有 MCP server 都天然支持两种模式有些第三方工具只实现了其中一种配置前建议先看文档或仓库里的示例。4.3 生态里的真实分布目前市面上很多热门 MCP 都两种模式都支持比如 Playwright MCP 可以在本地以 stdio 方式跑安装好的浏览器自动化脚本也可以作为远程服务被多个客户端连接Figma MCP、蓝湖 MCP 这类偏向设计稿数据访问的通常走远程模式更方便因为设计稿本身在云端服务端直接拉取数据后返回给 AI 即可。安全工具领域则不一样BurpSuite MCP、IDA MCP 等工具调用往往需要本地进程和复杂 GUI 环境stdio 模式更贴近它们的使用方式。而像 12306 MCP、Apifox MCP 这种对接业务 Web 服务的普遍优先实现远程模式因为接口本来就在外网直接封装成 HTTP 服务是自然选择。理解了这个分布规律你在选型时就不会因为“这个工具只能本地跑”或者“那个工具必须填 URL”而感到困惑了。5. 从零实现一个支持双模式的 MCP serverPython 实操5.1 准备环境和项目初始化我以 Python 实现为例原因是生态最成熟。先建一个虚拟环境并安装官方 SDKmkdir mcp-demo cd mcp-demo python -m venv .venv source .venv/bin/activate pip install mcp[cli] fastmcp这里的 FastMCP 是官方 SDK 提供的高层封装写工具非常简洁。需要说明的是不同版本 API 名称略有差异老版本里网络模式曾用transportsse新版本更多看到transportstreamable-http如果你用的版本不一样以该版本文档为准。5.2 先写一个最简单的工具函数新建server.pyfrom mcp.server.fastmcp import FastMCP mcp FastMCP(DemoServer) mcp.tool() def get_weather(city: str) - str: 根据城市名返回简要天气描述 return f{city} 今天晴转多云气温 24~28 摄氏度 if __name__ __main__: mcp.run(transportstdio)在终端先手动执行一下python server.py正常情况下程序会挂住并等待输入这时候你可以往 stdin 里粘一条 JSON-RPC 消息试试不过新手不用这么做因为客户端会帮你完成握手。只要能正常启动不报错说明工具定义没问题。5.3 挂载为 stdio 模式并测试把这段配置写进 Claude Code 或 Cursor 的 MCP 配置{ mcpServers: { demo-server: { command: python, args: [/absolute/path/to/server.py] } } }这里提醒一下command最好写解释器的绝对路径尤其是在虚拟环境下。比如command: /Users/me/mcp-demo/.venv/bin/python然后让 AI 发起调用比如“帮我查询北京市的天气”。如果 AI 能自动调用工具并返回正确的文字结果说明 stdio 链路已经打通。整个过程就像在终端对着命令行喊话特别直观。5.4 换成 HTTP/SSE 模式启动我们把入口改成网络模式if __name__ __main__: # 也可以根据版本写成 transportsse mcp.run(transportstreamable-http)重新启动python server.py启动后默认会在本地监听一个端口通常框架会打印监听地址。然后在客户端配置里填{ mcpServers: { demo-server-http: { url: http://127.0.0.1:8000/mcp } } }如果客户端版本比较老支持的是同时期的 SSE 配置那路径很可能是{ mcpServers: { demo-server-http: { url: http://127.0.0.1:8000/sse } } }如果返回工具列表和调用工具都正常说明远程模式也通了。5.5 自定义日志管理技巧MCP server 端的日志管理是很多人忽略的一块。默认情况下FastMCP 会输出一些框架日志但如果你想接上自己的日志系统可以在入口处做这样一件事import logging logging.basicConfig( levellogging.INFO, format%(asctime)s [%(levelname)s] %(name)s: %(message)s, handlers[ logging.StreamHandler(), logging.FileHandler(mcp_server.log, encodingutf-8) ] )把日志同时输出到控制台和文件线上排查问题时非常省事。我还见过有人把日志接到告警系统里工具调用失败时直接推送通知这属于进阶用法但思路值得参考。5.6 密钥、环境变量和敏感配置写远程模式时不要在代码里写死鉴权 token。优先让配置系统处理比如读取环境变量或者通过客户端配置文件里的headers字段传入。要明白一个原则stdio 模式下密钥放在配置对象里还勉强能接受远程模式下服务端暴露在网络任何硬编码凭据都是风险点。我还见过一些项目把密钥写进仓库里这个习惯一定不要养成。6. 高频问题排查与避坑记录6.1 连接超时timed out after 30 seconds很多人在配置 MCP server 时遇到“timed out after 30 secondsadd or adjust timeout”之类报错。这个报错本质是客户端等待服务端完成握手或首个响应超过了默认时限。原因通常有三个服务端启动太慢比如 npx 拉依赖、服务端端口没通、你试用的是本地 stdio 但解释器路径不对导致进程根本没起来。排查顺序我建议这样先在终端手动启动 server确认一条命令能跑起来再检查配置里的路径和环境变量最后才去调大客户端超时参数。如果你的客户端支持命令行参数或配置文件调整超时可以适当放宽到 60 秒但根因还是要准确定位。6.2 远程模式连不上但本地 curl 能通这种情况我遇到很多次。第一件事是确认服务端确实监听了对外接口127.0.0.1和0.0.0.0的监听范围完全不同第二件事是检查防火墙和端口开放第三件事是关注回调地址。特别是早期的 SSE 模式服务端会告诉客户端一个 event stream 地址如果客户端访问不到这个地址连接一样会失败。如果你只是自己本机测试把地址都填127.0.0.1最稳。如果一定要给远程机器用先找个简单的 HTTP 接口测试服务端是否能被远程访问再挂 MCP 配置基本可以排除一大半环境问题。6.3 鉴权不生效鉴权问题在配置后非常容易踩雷。远程 mode 的鉴权字段必须和 MCP server 的校验逻辑严格对应。常见的坑是客户端规范是放Authorization: Bearer xxx你写成了Authorization: xxx服务端要求 API Key 放在自定义头你放到了 Authorizationtoken 本身包含特殊字符JSON 里没做好转义。我的调试办法是先用 curl 直接打一次接口手动带同样的请求头观察返回状态码。curl 通了客户端再不通那问题就在客户端的配置格式上curl 都不通那就是服务端鉴权逻辑或网络问题。6.4 stdout 被日志污染这个坑在 stdio 模式里尤其常见。你本地测试时直接用print输出运行日志挂到客户端后客户端把进程的 stdout 当成协议通道多出来任何非 JSON 内容都会导致握手失败。解决办法前面也提过所有日志输出必须走stderr、logging模块或文件日志别碰 stdout。6.5 客户端能看到工具但调用失败工具列表都能拉出来说明客户端与服务端的握手、工具发现流程正常。调用失败通常出在工具函数内部参数类型不匹配、服务端执行超时、或者工具内部报错被外层包装成了“调用失败”。这时候最有效的手段是看服务端日志。如果你配置了 5.5 小节里的自定义日志管理很容易从日志里定位到具体的异常堆栈。如果服务端没日志先给框架加 logging 再说别盲目改客户端配置。6.6 一份避坑速查表现象可能原因排查优先级timmed out 30s服务端启动慢/网络不通/路径错误先手动启动 server无法连接远程地址监听地址只绑定了127.0.0.1检查监听地址和端口SSE 回调无法访问NAT/防火墙/公网地址不可达检查网络拓扑工具列表为空server 未正确实现工具注册查看服务端日志调用失败工具内部异常查看日志堆栈日志污染协议用了 print 输出 stdout强制改用 stderr最后再分享一条个人实操体会纯本地开发阶段我强烈建议先用 stdio 模式把每个工具函数跑通确认返回格式没问题之后再考虑用 streamable-http 提供成服务。原因很简单stdio 模式下任务的调试就像普通命令行程序一样直观一旦上了 HTTP会出现回调、鉴权、跨网段访问等一堆额外变量排查链路会变长。我先用 curl 手测接口再到客户端里做验证这个顺序帮我省下了大量来回找问题的时间。MCP 的两种模式本质不复杂复杂的是环境差异养成“先本地、再远程、最后才调参”的习惯你会比我少走很多弯路。