MCP 传输方式与客户端参数配置

适用范围:本文的可运行示例以本项目安装的 Python MCP SDK 1.16.0 为准。不同版本的客户端 API 有差异,末尾列出迁移提示。

先分清三个概念

因此,stdio、Streamable HTTP 和 SSE 是连接方式,不是三种不同的 MCP 工具类型。连接建立以后,它们都可以通过 ClientSession 执行 list_tools()、call_tool() 等协议操作。

应用 / Agent
    ↓
ClientSession:初始化、列举工具、调用工具
    ↓
Transport:stdio / Streamable HTTP / SSE
    ↓
MCP Server

一眼对比

方式 服务端在哪里 客户端提供什么 本项目 SDK 1.16.0 的入口 何时选用
stdio 客户端启动的本地子进程 启动命令、参数、可选环境和工作目录 StdioServerParameters + stdio_client() 本地工具、桌面应用启动的服务
Streamable HTTP 已运行的 HTTP 服务 MCP 端点 URL;按需提供请求头、认证、超时 streamablehttp_client() 新建远程 MCP 接入时优先考虑
SSE(旧传输) 已运行的 HTTP 服务 SSE 端点 URL;按需提供请求头、认证、超时 sse_client() 对接仍采用旧 SSE 传输的服务
进程内连接 同一 Python 进程中的服务端对象 服务端对象或测试夹具 取决于使用的 SDK API 嵌入式场景和测试;无需子进程或 URL

选择顺序:服务需要由你的程序在本机启动,选 stdio;服务已部署并提供 Streamable HTTP 端点,选 Streamable HTTP;只有服务明确提供旧 SSE 端点时才选 SSE。进程内连接属于特殊的嵌入或测试方式,不能把它当成一个远程地址配置。

下文的 async with 示例是代码片段,实际使用时应放进 async def main(),再由 asyncio.run(main()) 启动。

1. stdio:描述怎样启动本地服务端

StdioServerParameters 是 stdio 子进程的启动配置,并非所有 MCP Server 共用的配置类。客户端启动进程后,通过其标准输入和标准输出交换 MCP 消息;服务端日志应写到标准错误,避免破坏协议消息。

参数 作用 示例
command 可执行命令 npx、python、uv
args 传给命令的参数列表 文件系统服务包名、允许访问的目录
env 子进程需要的环境变量 服务所需的 API Key
cwd 子进程的工作目录 项目目录
encoding / encoding_error_handler stdio 文本编解码设置 有特殊编码需求时再配置

与本项目 task5 对应的写法:

from pathlib import Path
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

notes_dir = Path(__file__).resolve().parent / "notes"
server = StdioServerParameters(
    command="npx",
    args=["-y", "@modelcontextprotocol/server-filesystem", str(notes_dir)],
)

async with stdio_client(server) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()

这里的 args 是启动文件系统服务端所需的命令行参数;notes_dir 是服务端允许访问的目录。使用脚本所在目录定位它,可以避免从不同工作目录运行时误指向不存在的 notes 目录。

2. Streamable HTTP:连接已经运行的服务端

客户端传入的是服务端的 MCP 端点 URL,例如 http://localhost:8000/mcp。客户端不会因为拿到 URL 就负责启动服务端。不要把一个普通网页地址或旧 SSE 地址当成 Streamable HTTP 端点。

本项目安装的 SDK 1.16.0 使用 streamablehttp_client(注意函数名中没有 streamable 和 http 之间的下划线):

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

url = "http://localhost:8000/mcp"

async with streamablehttp_client(url) as (read, write, get_session_id):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()

这个版本的上下文返回三个值:读流、写流和获取 HTTP 会话 ID 的回调。只调用工具时可以不使用 get_session_id,但解包时要保留它。

常用参数 作用
url MCP 端点
headers 自定义 HTTP 请求头,例如认证信息
auth HTTP 认证对象
timeout 普通请求的超时
sse_read_timeout 流式响应读取超时
terminate_on_close 关闭客户端时是否请求终止服务端会话

认证、代理等高级配置应按正在使用的 SDK 版本查参数签名。不要把新版文档中的 httpx2.AsyncClient 示例直接套在本项目的 1.16.0 上。

3. SSE:兼容旧服务端

SSE 是较早的远程传输方式,和 Streamable HTTP 是不同的端点及客户端实现。服务器如果只提供类似 http://localhost:8000/sse 的旧端点,才使用 sse_client:

from mcp import ClientSession
from mcp.client.sse import sse_client

url = "http://localhost:8000/sse"

async with sse_client(url) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()

常用配置包括 url、headers、auth、timeout 和 sse_read_timeout。Streamable HTTP 的响应也可能使用 SSE 事件流;这不意味着它就是这里所说的旧 SSE 传输。两者应按服务端实际提供的端点和协议选择。

4. 进程内连接:用于嵌入和测试

如果服务端对象本来就在同一进程中,有些 SDK API 可以直接连接它,省去子进程和网络。它与前面三种方式相比,更像一种嵌入或测试连接方式。本项目的 MCP SDK 1.16.0 没有下文提到的高层 Client 类,不要照搬新版 Client(server_object) 的示例来运行当前代码。

参数配置的关键区别

问题 stdio Streamable HTTP / 旧 SSE
谁启动服务端? 客户端启动本地子进程 服务端预先运行,客户端只连接
用什么定位服务端? command + args URL
服务所需的环境变量放哪里? 子进程启动配置 env 服务端自己的部署环境;客户端认证通常通过 HTTP 配置
连接何时可用? 进入 stdio_client 上下文并完成 initialize() 后 进入 HTTP 客户端上下文并完成 initialize() 后
何时关闭? 退出上下文时结束会话并清理子进程 退出上下文时关闭连接及会话

无论采用哪种传输,构造参数对象不等于连接成功。必须在异步上下文中建立传输、创建 ClientSession、调用 initialize(),之后才能列举或调用工具。

SDK 版本提示

本项目当前使用 mcp 1.16.0,对应本文示例:

Python SDK 2.x 的官方文档展示了更高层的 Client:可以通过传入 URL 或 StdioServerParameters 选择传输;其 HTTP 函数名和 HTTP 客户端配置方式也与 1.16.0 不同。升级 SDK 后再按新文档改写,不能混用两代 API。

参考资料