mcp-sse
MCP SSE 模式的参考实现：让 AI Agent 通过 HTTP SSE 调用远程工具服务，突破
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
MCP SSE 模式的参考实现：让 AI Agent 通过 HTTP SSE 调用远程工具服务，突破
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
想象一下，你正在用 Claude 开发一个复杂的多步骤工作流：先查天气，再根据天气结果决定是否发送通知，最后将结果写入数据库。在传统的 STDIO 模式下，这意味着 Claude 每次调用工具都需要"孵化"一个子进程——启动、等待、关闭。这种模式在本地开发时还能接受，但一旦进入生产环境、需要跨机器部署、需要让多个客户端同时共享同一个工具服务时，STDIO 的局限性就暴露无遗：进程无法长期运行，资源无法复用，云原生场景更是无从谈起。
这就是 mcp-sse 要解决的问题。它是 Model Context Protocol（MCP）官方推荐的 SSE（Server-Sent Events）传输模式的参考实现，让 MCP 服务器从"每次调用都重新启动的进程"变成"常驻运行的 HTTP 服务"，同时让 MCP 客户端从"孵化者"变成"纯连接者"。
mcp-sse 由开发者 sidharthrajaram 创建于 2025 年 1 月，定位为 MCP SSE 模式的参考实现仓库，而非一个具体的业务工具。它解决的问题是：探索在 STDIO 之外，如何用 HTTP + SSE 的方式让 MCP 客户端与服务器解耦。
作者基于 MCP Python SDK Issue #145 的讨论，将官方的 STDIO 示例（天气查询工具）改造成了 SSE 版本，形成了一套可直接运行的参考代码。截至 2026 年初，该仓库已获得 301 颗 GitHub Stars，被收录于 MCP 官方生态和 Smithery 工具市场，成为开发者理解 MCP 网络化传输的重要入口。
项目的核心特点在于"云原生友好"：服务器和客户端是完全解耦的两个进程，可以部署在不同的机器上，通过 HTTP SSE 端点通信，这对构建分布式 AI Agent 系统意义重大。
项目仅包含 4 个核心文件：weather.py（SSE 服务器）、client.py（SSE 客户端）、pyproject.toml（依赖管理）、Dockerfile（容器化），结构极为精简，但每一行代码都承担了重要的教学使命。
┌──────────────────┐ HTTP/SSE ┌──────────────────┐
│ MCP SSE Client │◄──────────────────────►│ MCP SSE Server │
│ (client.py) │ GET /sse (SSE) │ (weather.py) │
│ │◄──────────────────────►│ │
│ - Anthropic SDK │ POST /messages/ │ - FastMCP │
│ - mcp[cli] │ │ - Starlette │
│ - httpx │ │ - uvicorn │
└──────────────────┘ └──────────────────┘
服务端使用 FastMCP 框架注册工具函数，通过 Starlette（ASGI 应用）提供 HTTP 接口，关键在于 SseServerTransport 将 MCP 协议适配到 SSE 传输层：
from mcp.server.fastmcp import FastMCP
from mcp.server.sse import SseServerTransport
from starlette.applications import Starlette
from starlette.routing import Mount, Route
import uvicorn
mcp = FastMCP("weather") # 注册工具
def create_starlette_app(mcp_server):
sse = SseServerTransport("/messages/")
async def handle_sse(request):
async with sse.connect_sse(...) as (read, write):
await mcp_server.run(read, write, ...)
return Starlette(routes=[
Route("/sse", endpoint=handle_sse), # 客户端建立SSE连接
Mount("/messages/", app=sse.handle_post_message), # 接收工具调用响应
])
/sse 端点负责建立 SSE 长连接，/messages/ 端点负责接收工具执行结果的推送。这种双向通信机制让服务器可以在工具执行完毕后主动将结果推送给客户端。
服务端暴露两个天气工具：get_alerts(state) 查询美国指定州的活跃天气预警，get_forecast(latitude, longitude) 查询指定经纬度的天气预报，数据来源为美国国家气象局（NWS）公开 API。工具函数均使用 async 定义，通过 httpx.AsyncClient 调用外部天气 API。
客户端的核心是 MCPClient 类，封装了连接管理、查询处理和资源清理逻辑：
class MCPClient:
async def connect_to_sse_server(self, server_url):
# 建立 SSE 连接（非进程孵化！）
self._streams_context = sse_client(url=server_url)
streams = await self._streams_context.__aenter__()
self._session_context = ClientSession(*streams)
self.session = await self._session_context.__aenter__()
await self.session.initialize()
process_query 方法展现了完整的工具调用流程：先将用户问题发送给 Claude，Claude 决定调用哪个工具后，客户端通过 session.call_tool() 执行工具（实际由 SSE 服务器处理），工具结果返回后再继续与 Claude 对话，直到得到最终回答。这实现了多轮工具调用 + 上下文续接的能力。
| 组件 | 技术选型 | 说明 |
|---|---|---|
| MCP 协议 | mcp[cli]>=1.2.1 | 官方 Python SDK |
| SSE 传输 | mcp.server.sse | MCP 官方 SSE 适配器 |
| ASGI 框架 | starlette | 轻量 ASGI 框架 |
| HTTP 客户端 | httpx>=0.28.1 | 异步 HTTP 调用 |
| AI 模型 | anthropic>=0.45.1 | Claude API 集成 |
| 运行环境 | Python >= 3.13 | 通过 uv 管理 |
| 容器化 | 多阶段 Dockerfile | Python 3.13 slim + uv |
Python 版本要求 3.13 以上（较新），使用 uv 作为包管理工具而非传统的 pip，这是当前 Python 生态的现代化趋势。
项目提供了两种运行方式。本地开发模式下，先启动服务端（后台），再运行客户端交互程序：
# 终端 1：启动天气 MCP SSE 服务器
uv run weather.py --host 0.0.0.0 --port 8080
# 终端 2：启动交互式客户端（连接本地服务器）
uv run client.py http://0.0.0.0:8080/sse
容器化部署模式下，一行命令完成构建与运行：
docker build -t mcp-sse .
docker run -p 8080:8080 -e ANTHROPIC_API_KEY=sk-xxx mcp-sse
Dockerfile 采用了多阶段构建（基于 ghcr.io/astral-sh/uv:python3.13-slim），最终镜像体积控制在数百 MB 以内，依赖通过 uv sync --frozen 精确锁定，保证构建可复现性。
项目还接入了 Smithery，这是面向 MCP 生态的第三方市场，支持一键安装到 Claude Desktop：
npx -y @smithery/cli install @sidharthrajaram/mcp-sse --client claude
Smithery 自动生成 smithery.yaml 配置，定义了配置项（anthropicApiKey）和启动命令，实现从市场到本地 CLI 的无缝衔接。
这是一个参考实现，而非生产级工具集。服务端仅暴露两个美国天气查询工具，没有生产环境需要的认证机制、日志记录、错误重试、限流保护等。作为学习 MCP SSE 模式是完美的范本，但直接用于生产需要大量加固工作。
SSE 是单向通信协议（服务端→客户端），客户端向服务端的请求仍然需要通过 HTTP POST 发送。这意味着工具调用的双向通信实际上是"HTTP POST + SSE 推送"的组合，不如 WebSocket 那样天然双向。不过，MCP 协议本身已经封装了这种复杂性，对使用者透明。
当前版本将 ANTHROPIC_API_KEY 通过环境变量传入，在容器环境中需要注意密钥管理（建议使用 Docker secrets 或 K8s secret）。此外，Smithery.yaml 中定义的是 STDIO 模式的配置，若要通过 Smithery 使用 SSE 模式，需额外配置。
要求 Python >= 3.13，而 Python 3.13 于 2024 年 10 月才正式发布，生产环境中可能面临运行环境选择的限制。部分依赖（如 mcp[cli]>=1.2.1）对 Python 版本有隐性要求，使用时需要注意兼容性验证。
MCP 协议自 2024 年底推出后，STDIO 模式是第一个被广泛采用的参考实现，但 STDIO 天然不适合分布式场景。mcp-sse 的出现填补了 MCP "网络化传输"这一空白，为构建真正分布式的 AI Agent 系统提供了工程实践参考。
从 LangChain 的"工具定义→LLM 决策→函数调用"，到 MCP 的"工具注册→协议标准化→跨客户端复用"，AI 工具调用的标准化正在加速。mcp-sse 证明了 MCP 不仅可以本地调用，还能通过网络服务化，这对于构建企业级 AI 中台意义重大。
STDIO 模式下，每个工具调用都伴随着进程创建/销毁，资源消耗大且难以扩展。SSE 模式让工具服务成为真正的常驻进程，可以接入 Kubernetes HPA（水平 Pod 自动扩缩容）、服务网格、负载均衡等云原生基础设施，这是 AI Agent 工程化的重要方向。
sidharthrajaram/mcp-sse 是一个小而美的参考实现仓库，用最少的代码量（两个 Python 文件 + 一个配置文件）清晰地展示了 MCP 协议从 STDIO 到 SSE 的迁移路径。它不追求功能丰富，而是专注于传输模式的正确实现，对于想理解 MCP 网络化通信原理的开发者来说，是一份不可多得的实践素材。
对于 AI 爱好者而言，这个项目展示了 AI Agent 如何通过标准化协议调用远程工具——就像浏览器通过 HTTP 调用 Web API 一样自然。对于 AI 开发者而言，它是探索分布式 MCP 工具服务、构建私有 AI 工具市场的技术起点。随着 MCP 协议生态的成熟，这类基础设施项目的价值将持续放大。