MCP Python SDK 服务器运行指南:传输方式、`mcp.run()` 与 `mcp` 命令行工具

原创2026-09-21 12:31:411,988 阅读
文章标签:人工智能大模型MCP 服务MCP Clients工具调用后端

MCP Python SDK 服务器运行指南:传输方式、mcp.run() 与 mcp 命令行工具

mcp.run() 是 MCP Python SDK 中启动服务器(MCPServer)的唯一入口,而围绕它需要做的最关键决策是传输方式(transport)——服务器与客户端之间的字节究竟如何流动。本指南基于 SDK 官方文档《运行服务器》展开,系统讲解 stdio 与 streamable-http 两种传输方式的选择、mcp.run() 的全部传输选项、log_level/debug 等服务器设置,以及 mcp dev、mcp run、mcp install、mcp version 四个 CLI 子命令的实战用法。读完本文,你将能独立把一个 MCP 服务器从本地子进程形态切换为可部署的 HTTP 服务,并理解底层实现原理。

选择传输方式:服务器与客户端之间的字节如何流动

官方文档用一个表格给出了三种传输方式的定位:

传输方式 是什么 何时使用
stdio 宿主把你的文件作为子进程启动,通过它的 stdin 和 stdout 通信 本地服务器。默认值
streamable-http 真正的 HTTP 服务器,监听一个端口 任何要部署的东西
sse 较旧的 HTTP 传输方式 不要用

警告:SSE 已被取代。 SSE 在 2025-03-26 协议修订版中已被 Streamable HTTP 取代。mcp.run(transport="sse") 仍然可用,也有自己的 sse_path= 和 message_path= 选项,但它只是为还没迁移的客户端留着的。不要在它之上构建任何新东西。

从源码看,run() 的实现正是围绕这三种传输方式分派逻辑的。在 server.py 中:

def run(
    self,
    transport: Literal["stdio", "sse", "streamable-http"] = "stdio",
    **kwargs: Any,
) -> None:
    """Run the MCP server. Note this is a synchronous function."""
    TRANSPORTS = Literal["stdio", "sse", "streamable-http"]
    if transport not in TRANSPORTS.__args__:
        raise ValueError(f"Unknown transport: {transport}")

    match transport:
        case "stdio":
            anyio.run(self.run_stdio_async)
        case "sse":
            anyio.run(lambda: self.run_sse_async(**kwargs))
        case "streamable-http":
            anyio.run(lambda: self.run_streamable_http_async(**kwargs))

可见 run() 是同步函数,内部通过 anyio.run 包装异步实现,这解释了文档强调的"它是同步的"这一特性。同时,run() 的重载签名(server.py)分别约束了 sse 与 streamable-http 各自可用的关键字参数,类型系统会在编译期帮你检查传输选项是否写错。

mcp.run() 入门:一个最小的服务器

以下是官方文档中的最小服务器示例(tutorial001.py):

from mcp.server import MCPServer

mcp = MCPServer("Bookshop")


@mcp.tool()
def search_books(query: str) -> str:
    """Search the catalog by title or author."""
    return f"Found 3 books matching {query!r}."


if __name__ == "__main__":
    mcp.run()

这段代码有四个要点:

  • run() 是同步的:服务器存活多久,它就阻塞多久。它内部通过 anyio.run() 驱动事件循环,直到服务器停止才返回。
  • 不带参数时,传输方式是 stdio:这是默认值,无需显式指定。
  • 它放在 if __name__ == "__main__": 之下:因为所有加载服务器的东西(mcp dev、mcp run、mcp install、你的测试)都会导入这个文件。这个保护条件防止一次导入变成一个运行中的服务器——模块被导入时不会执行 run(),只有直接运行该文件时才会启动。
  • MCPServer(...) 的构造参数描述服务器"是什么":名称(name)、标题(title)、说明(description)、版本(version)等。从构造函数签名(server.py)可以看到,MCPServer.__init__ 接受 name、title、description、instructions、website_url、icons、version、debug、log_level 等一系列参数,但没有 port、host 这类传输选项——它们只属于 run()。

深入 stdio:stdout 就是线路

stdio 传输没有什么需要配置的。宿主把你的文件作为子进程启动,把请求写入它的 stdin,再从它的 stdout 读取响应。

自己运行一下,就能看出这意味着什么:

python server.py

什么也不打印,也不返回。它在 stdin 上等着宿主先开口。从源码看,run_stdio_async(server.py)的实现非常直观:

async def run_stdio_async(self) -> None:
    """Run the server using stdio transport."""
    async with stdio_server() as (read_stream, write_stream):
        await self._lowlevel_server.run(
            read_stream,
            write_stream,
            self._lowlevel_server.create_initialization_options(),
        )

它借助 stdio_server() 建立读写流,再把低层 Server 挂到这两个流上运行。

为什么服务期间不能往 stdout 乱打印

这也意味着 stdout 就是线路(the wire)。服务期间,SDK 把线路移到一个私有描述符上,并把刷新到 stdout 的输出(子进程写入它继承的 stdout、刷新过的 print())转到 stderr,在那里不会破坏数据流。但有三类输出仍然会"漏"到线路上:

  • 在开始服务之前就刷新到 stdout 的输出(包装脚本的 echo、导入时的无缓冲 print);
  • 一直缓冲到解释器退出时才排空的 print();
  • 其他任何直接写入继承 stdout 的行为。

对于真正想要的输出,logging 模块才是正确的工具:它的 handler 会在每条记录产生时就把它刷新到 stderr。SDK 内部也正是这么做的——configure_logging(logging.py)在安装了 rich 时使用 RichHandler(console=Console(stderr=True)),明确把日志输出到 stderr,从而与作为线路的 stdout 彻底隔离:

def configure_logging(
    level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = "INFO",
) -> None:
    handlers: list[logging.Handler] = []
    try:
        from rich.console import Console
        from rich.logging import RichHandler
        handlers.append(RichHandler(console=Console(stderr=True), rich_tracebacks=True))
    except ImportError:
        pass
    if not handlers:
        handlers.append(logging.StreamHandler())
    logging.basicConfig(level=level, format="%(message)s", handlers=handlers)

更完整的日志主题可参考日志记录。

试一试:用 Inspector 连接你的 stdio 服务器

uv run mcp dev server.py

Inspector 做的事和真实宿主完全一样:它把 server.py 作为子进程启动,通过 stdio 连接它。

你从没给过它端口。根本就没有端口。

这正是 stdio 的本质——无需网络层,宿主与服务器之间就是进程内的两个管道。

Streamable HTTP:把同一个服务器放到端口上

要把同一个服务器放到端口上,在 run() 里指明传输方式(及其选项)(tutorial002.py):

from mcp.server import MCPServer

mcp = MCPServer("Bookshop")


@mcp.tool()
def search_books(query: str) -> str:
    """Search the catalog by title or author."""
    return f"Found 3 books matching {query!r}."


if __name__ == "__main__":
    mcp.run(transport="streamable-http", port=3001)

这一行会构建一个 Starlette 应用并用 uvicorn 提供服务。客户端连接到 http://127.0.0.1:3001/mcp。

从源码看,run_streamable_http_async(server.py)的流程是:先调用 self.streamable_http_app(...) 构建 Starlette 应用,再用 uvicorn.Config + uvicorn.Server 启动:

starlette_app = self.streamable_http_app(
    streamable_http_path=streamable_http_path,
    json_response=json_response,
    stateless_http=stateless_http,
    event_store=event_store,
    retry_interval=retry_interval,
    max_request_body_size=max_request_body_size,
    session_idle_timeout=session_idle_timeout,
    max_sessions=max_sessions,
    transport_security=transport_security,
    host=host,
)
config = uvicorn.Config(starlette_app, host=host, port=port, log_level=self.settings.log_level.lower())
server = uvicorn.Server(config)
await server.serve()

注意 uvicorn 的 log_level 直接取自 self.settings.log_level——这印证了后文"服务器设置"一节中 log_level 同时影响 HTTP 传输服务行为的事实。

run() 上的传输选项详解

每种传输方式都有自己的关键字参数,全都在 run() 上:

  • host / port:监听的位置。默认 127.0.0.1 和 8000。
  • streamable_http_path:MCP 端点所在的路径。默认 /mcp。
  • json_response=True:用单个 JSON 正文回应每个 POST,而不是 SSE 流。这个正文只容得下响应本身,别的什么都放不下,所以:
    • 在请求中途回调客户端的工具(ctx.elicit()、采样 sampling)会在这一段抛出 NoBackChannelError;
    • 与进行中的调用绑定的通知(ctx.report_progress() 的进度、每次调用的日志消息)会被丢弃;
    • 独立的 GET 流仍然承载与之无关的通知。
  • stateless_http=True:每个请求一个全新的传输,不跟踪会话。
  • max_request_body_size:接受的最大请求正文大小,单位为字节。默认 4 MiB;更大的请求在解析或创建会话之前就会收到 HTTP 413。只有当合法的 MCP 消息确实超过这个大小时才调高它。
  • session_idle_timeout:旧版会话在没有任何进行中请求的情况下可以闲置多少秒,之后服务器会关闭它。默认 1800 秒。None 表示禁用。见会话生存期与限制。
  • max_sessions:一个进程同时持有多少个旧版会话。默认 10 000。None 表示不设上限。同一节里有介绍。
  • event_store、retry_interval、transport_security:可恢复性和 DNS 重绑定防护。它们可以先放一放,等部署到 localhost 以外的地方再说;部署与扩展 介绍了 transport_security。

常见错误:传输选项不属于 MCPServer(...)

警告:传输选项传给 run(),不是 MCPServer(...)。构造函数描述服务器是什么:名称、版本、说明。run() 描述它如何对外提供服务。搞反了,Python 在 MCP 介入之前就会报错:

TypeError: MCPServer.__init__() got an unexpected keyword argument 'port'

从 server.py 的构造函数签名可以确认:MCPServer.__init__ 的关键字参数只有 name、title、description、instructions、website_url、icons、version、debug、log_level、warn_on_duplicate_*、dependencies、lifespan、auth、resource_security、request_state_security、cache_hints、subscriptions、middleware 等,没有任何传输相关参数。错误地把 port 等参数传给构造函数,Python 解释器会直接拒绝。

run() 是捷径

run() 是捷径。一旦需要更多能力——把服务器挂载到现有应用里、一个进程里跑两个服务器、为浏览器客户端配置 CORS——就要自己构建 ASGI 应用,再交给任意 ASGI 服务器运行。这就是添加到现有应用 的内容。

服务器设置:与传输方式无关的构造函数参数

运行方面有几件事与传输方式无关,它们是构造函数参数(tutorial003.py):

from mcp.server import MCPServer

mcp = MCPServer("Bookshop", log_level="DEBUG")


@mcp.tool()
def search_books(query: str) -> str:
    """Search the catalog by title or author."""
    return f"Found 3 books matching {query!r}."


if __name__ == "__main__":
    mcp.run()
  • log_level:在构造 MCPServer(...) 的那一刻传给 logging.basicConfig()。它配置的是根 logger,所以也会设置你自己的 logger 的级别,而不只是 SDK 的。默认 "INFO"。允许的取值从源码看是 "DEBUG"、"INFO"、"WARNING"、"ERROR"、"CRITICAL" 五个级别(server.py)。值得注意的是,configure_logging 是在 MCPServer.__init__ 中同步调用的(server.py),所以一旦构造完成,根 logger 的级别就立即生效。
  • debug:转发给 HTTP 传输构建的 Starlette 应用。默认 False。

两者都落在 mcp.settings 上,可以在运行时读回。从源码看,MCPServer.__init__ 会构造一个 Settings 模型(server.py),把 debug、log_level、warn_on_duplicate_*、dependencies、lifespan、auth 一并存入 self.settings,因此运行时可以通过 mcp.settings.log_level、mcp.settings.debug 读取回这些配置。

mcp 命令:围绕运行方式的 CLI 工具

[cli] 附加依赖会安装一个把这些都包起来的小型命令行工具。它的四个子命令分别对应不同的运行场景。

mcp dev:在 MCP Inspector 下运行

uv run mcp dev server.py
uv run mcp dev server.py --with pandas --with numpy
uv run mcp dev server.py --with-editable .
  • --with 往它构建的环境里添加包;
  • --with-editable 把你自己的包安装进去。

它需要 PATH 上有 npx:Inspector 是一个 Node.js 应用。

mcp run:导入文件并执行

mcp run 导入文件,找到服务器对象(模块级的 mcp、server 或 app),然后对它调用 run():

uv run mcp run server.py
uv run mcp run server.py:bookshop
  • 当对象不叫 mcp、server 或 app 时,用 : 后缀指明它的名字;
  • 在这里,你的 if __name__ == "__main__": 块永远不会执行:mcp run 自己调用 run(),它唯一转发的选项是 --transport。

mcp install:注册到 Claude Desktop

uv run mcp install server.py --name "Bookshop"
uv run mcp install server.py -v API_KEY=abc123 -f .env
  • -v KEY=VALUE 和 -f .env 把环境变量记录在该条目里。Claude Desktop 在它自己的进程里启动你的服务器,你 shell 里的环境变量那里没有——所以需要显式传入。
  • Claude Desktop 是 mcp install 唯一认识的宿主。其他宿主(Claude Code、Cursor、VS Code)都在各自的配置文件里接受同样的启动命令,连接到真实的宿主 逐一介绍了它们。

mcp version:查看版本

uv run mcp version

打印已安装的 SDK 版本。

提示:mcp dev 和 mcp run 只认 MCPServer(高层封装)。如果用底层的 Server 构建,就要自己运行它。见底层 Server。

回顾:运行服务器的核心要点

  • 传输方式是字节到达服务器的方式:本地子进程用 stdio,端口用 streamable-http。SSE 已被取代。
  • mcp.run() 选择传输方式。不带参数时是 stdio,并且会阻塞。
  • 每个传输选项(host、port、streamable_http_path……)都是 run() 的参数,绝不是 MCPServer(...) 的。
  • 把 run() 放在 if __name__ == "__main__": 之下。所有加载服务器的东西都会先导入这个文件。
  • log_level= 和 debug= 是构造函数参数;它们落在 mcp.settings 上。
  • mcp dev 用于 Inspector,mcp run 执行文件,mcp install 用于 Claude Desktop,mcp version 查看版本。
  • 传输方式永远不会改变服务器"是什么":本页的三个教程文件(tutorial001.py、tutorial002.py、tutorial003.py)暴露的是完全相同的工具——改变传输方式只是改变了字节到达服务器的方式,工具本身、工具参数、服务器能力完全一致。

下一步:当 run() 成为限制时

登录后查看全文
python-sdk