从零手写一个MCP Agent服务:stdio与SSE两种连接模式的踩坑实录

从零手写一个MCP Agent服务:stdio与SSE两种连接模式的踩坑实录

上周我在给公司的内部知识库做一个Agent入口,需要把几个自研工具(文档检索、SQL查询、发通知)暴露给Claude Desktop和自建的Agent框架同时使用。本来想直接抄官方示例了事,结果发现一旦涉及"同一个MCP服务要同时被本地客户端和远程Agent调用"这个需求,stdio和SSE的选型就没那么简单了。这篇记录一下我踩过的具体坑。

一、先搞清楚MCP到底在传什么

MCP(Model Context Protocol)本质是JSON-RPC 2.0的一层约定。客户端和服务端之间交换三类消息:请求(带id)、响应(带对应id)、通知(无id)。工具注册走的是tools/list,调用走tools/call。

理解这一点很重要,因为後面stdio和SSE的差异,本质上只是"这层JSON-RPC消息怎么在传输层流动"的差异。

二、stdio模式:本地跑起来最省事,但有个致命细节

stdio模式下,MCP服务是一个被客户端作为子进程启动 的可执行程序,双方通过标准输入输出通信。协议规定:一行一条JSON-RPC消息。

我第一版用的是Python的mcp库,按文档写了大概这样:

python 复制代码
from mcp.server import Server
from mcp.server.stdio import stdio_server
import mcp.types as types

app = Server("kb-server")

@app.list_tools()
async def list_tools():
    return [
        types.Tool(
            name="search_docs",
            description="搜索内部知识库文档",
            inputSchema={
                "type": "object",
                "properties": {"query": {"type": "string"}},
                "required": ["query"],
            },
        )
    ]

@app.call_tool()
async def call_tool(name, arguments):
    if name == "search_docs":
        result = await do_search(arguments["query"])
        return [types.TextContent(type="text", text=result)]

async def main():
    async with stdio_server() as (read, write):
        await app.run(read, write, app.create_initialization_options())

看起来没问题,但我踩的第一个坑是日志 。我在工具函数里随手写了个print(f"query={query}"),结果客户端直接报JSON解析错误。原因是stdout是协议通道,任何非JSON输出都会污染它。所有调试输出必须走stderr ,也就是print(..., file=sys.stderr)或者用logging配置到stderr。这个坑我查了半小时才反应过来。

第二个坑是进程生命周期 。stdio模式下服务由客户端拉起,客户端退出服务就没了。我一开始想在里面维护一个长连接的向量库客户端,结果每次重启都要重新建连,冷启动能到两三秒。后来改成在on_initialized回调里做预热,才勉强压到800ms左右。

三、SSE模式:能远程,但会话隔离要自己管

因为还有一部分Agent跑在服务器上,不可能让它去启动本地进程,所以我又加了一个SSE入口。

SSE模式的结构是:客户端先GET /sse建立一个长连接,服务端通过这条连接推送消息,同时返回一个endpoint事件告诉客户端往哪个URL发POST请求。之后的JSON-RPC请求都用POST发过去。

用mcp库大致这样:

python 复制代码
from mcp.server.sse import SseServerTransport
from starlette.applications import Starlette
from starlette.routing import Route, Mount

sse = SseServerTransport("/messages/")

async def handle_sse(request):
    async with sse.connect_sse(
        request.scope, request.receive, request._send
    ) as streams:
        await app.run(streams[0], streams[1], app.create_initialization_options())
    return Response()

starlette_app = Starlette(
    routes=[
        Route("/sse", endpoint=handle_sse),
        Mount("/messages/", app=sse.handle_post_message),
    ]
)

这里我踩了最惨的一个坑 :一开始我把app(Server实例)定义成全局单例,想着所有连接共享。结果多个客户端同时连进来时,会话状态互相串了------A客户端的初始化参数会被B客户端看到,tools/call的返回偶尔发错连接。

翻源码才明白:每个SSE连接必须对应一个独立的Server会话 。正确做法是在handle_sse里为每个连接创建一个新的会话实例,或者至少保证create_initialization_options()返回的状态是per-connection的。我改了之后并发测试5个客户端才稳定。

另一个坑是代理超时 。我们前面挂了nginx,默认proxy_read_timeout是60秒。SSE连接空闲超过60秒就被nginx掐断,客户端重连时又拿不到原来的session id,工具调用直接失败。解决办法是在nginx配置里针对/sse路径设proxy_read_timeout 3600s并关闭proxy_buffering,同时在服务端每30秒发一个心跳注释行:\n\n保活。

四、两种模式到底怎么选

结合这次的实际使用,我的判断标准是这样的:

选stdio:客户端和服务在同一台机器、服务是本地工具(文件操作、本地数据库)、不关心多客户端并发。优点是零网络配置、天然进程隔离、安全性好(不暴露端口)。

选SSE:服务要远程部署、要被多个Agent或用户共享、需要集中做鉴权和限流。代价是必须自己处理会话隔离、心跳保活、反向代理配置这些事。

我最后的方案是同一份工具逻辑,两个入口 :tools/目录放纯业务函数,stdio_server.py和sse_server.py分别只做传输层封装。这样改工具逻辑只改一处,两个入口都不会漏。

五、几个容易忽略的点

  1. 错误返回要用isError: true,而不是抛异常。抛异常客户端收到的是协议层错误,Agent无法把它当成工具执行结果来处理,会直接中断对话。
  2. tools/list返回的inputSchema要写全 ,尤其是required。我第一次漏了,Claude调用时经常传空参数进来。
  3. SSE的session id不要复用。断线重连要当成新会话,旧会话的资源(比如数据库连接)要显式清理,否则连接池会被耗光。
  4. stdio下不要用asyncio.run嵌套 。mcp库自己管事件循环,你在工具函数里再起一个loop会直接报RuntimeError: This event loop is already running。

这次做完最大的感受是:MCP的协议本身不复杂,真正花时间的是传输层的那些"工程细节"------日志通道、会话隔离、超时保活。这些在示例代码里都不会写,但线上跑起来一个都躲不掉。

相关推荐
Danny转行做跨境1 天前
跨境数据CLI怎么用? 一个命令行调61个接口实录
跨境电商·mcp·sorftime
J船长1 天前
Agent开发 00|从 ChatGPT 到生产级 AI Agent
agent
Flynt1 天前
我让 AI 给掘金首页做了次性能体检:LCP 8.9 秒是真的,但它判读错了一处
chrome·性能优化·mcp
Csvn1 天前
如果明天供应商涨价 3 倍?三层解耦,换模型只改一行配置(C05)
人工智能·aigc·agent
七夜zippoe1 天前
Agent 告警设计:分级告警、智能降噪与值班排班
开发语言·ai·agent·告警·智能降噪·值班排班
FengY_HYY1 天前
从人类组织到人类&大模型组织,我的位置在哪里?
人工智能·程序员·llm
prince_zxill2 天前
把 17 个散文件装进一个文件夹:拆解 claude-plugins-official 的插件打包术(47,413 Star 实测)
python·github·agent·mcp·claude code
程序员张富华2 天前
一次发布拦住12个破坏性变更:我们给Agent工作流加了Schema门禁
人工智能·agent
xrlfreedom2 天前
MCP 面试高频考点:给 MCP Server 加日志、指标与分布式追踪,面试追问你能答到第几层?
结构化输出·mcp·mcp server
ZhengEnCi2 天前
Claude 的记忆是怎么设计的:四层记忆栈,和一场叫「做梦」的离线整理
aigc·agent·ai编程