1. Linux 服务器上 Python MCP 服务到底解决什么问题如果你正在把 Claude Desktop、Cursor 和自研 Agent 接到同一套工具能力上大概率会遇到一个很现实的问题每个客户端都要单独配一遍工具改一次逻辑就要同步改三处时间全花在重复劳动上。MCPModel Context Protocol就是为解决这类问题出现的它把「工具能力」从客户端里抽出来变成一个独立服务谁需要谁连。这篇要讲的是在 Linux 服务器上用 Python 部署 MCP 服务的完整路径。为什么强调 Linux 服务器因为本地 STDIO 模式只适合单机调试一旦你要让多台机器、多个客户端、甚至线上 Agent 共用同一套工具就必须把服务放到服务器上跑成常驻进程。Python 官方 MCP SDK 提供了 STDIO 和 Streamable HTTP 两种传输方式前者用于本机进程调用后者用于跨网远程调用生产环境基本都走 HTTP。适合谁看需要在 Ubuntu/CentOS/麒麟这类系统上部署 MCP 服务的后端或运维同学想让 Claude、Cursor、自研 Agent 共用一套工具能力的开发者已经写过 MCP 工具但卡在「怎么让它稳定常驻、怎么让多个客户端都连上」这一步的人。我试过把工具逻辑写在客户端配置里结果是每换一个客户端就要重写一遍参数后来改成服务端统一部署客户端只填一个 URL维护成本直接降下来。下面按「环境准备 → 双模式服务 → 客户端接入 → 验证 → 排障」的顺序走每一步都给可复制的命令和配置。2. TaoToken 统一 Key 接入 MCP 客户端的前置准备MCP 服务本身解决的是「工具怎么被调用」但客户端在调用模型时还需要一个模型入口。Claude Desktop、Cursor 这类客户端默认走各自的官方通道如果你想让它们统一走一个可管理的入口就需要把 Base URL 和鉴权改到 TaoToken。这一步和 MCP 服务部署是两条并行的线MCP 服务负责工具TaoToken 负责模型请求两者在客户端侧汇合。TaoToken 在这里的角色是统一 Key 接入层。你可以在官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 了解整体能力实际接入时用到的 API 地址是 https://taotoken.net/api这个地址不加 UTM 参数直接填进客户端配置即可。需要提前准备的东西不多一个可用的 Key、确认客户端支持自定义 Base URL、以及知道你要用的 Model ID。关于 Key 的获取进入控制台后创建 API Key 即可具体入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。拿到 Key 之后不要直接写死在代码里建议放到环境变量或客户端的配置文件中。模型对话调试可以用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 先确认模型可用再往客户端里填。这里要提醒一点MCP 服务和模型接入是两件事不要混在一个配置文件里。MCP 的mcpServers段管的是工具服务地址模型接入的 Base URL 和 Key 管的是模型请求。两者分开配置排障时才能快速定位是哪一层出了问题。如果你后面要用 Claude Code 这类编码 Agent长期跑的话可以看 Coding Plan 方案 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合持续性的编码任务。3. 可复制的 Python MCP 服务配置与 systemd 常驻这一节是全文的核心给出可以直接复制到服务器上跑的配置。先建目录和虚拟环境把依赖隔离好避免和系统 Python 冲突。mkdir -p /opt/mcp-python cd /opt/mcp-python python3.11 -m venv venv source venv/bin/activate pip install --upgrade pip pip install mcp[cli]依赖清单里mcp[cli]会带上官方 SDK 和 Inspector 相关组件。如果你要固定版本可以生成requirements.txtmcp1.9.0 uvicorn0.30.6 starlette0.37.2然后是 Streamable HTTP 模式的服务源码http_server.py这是生产推荐模式from mcp.server import Server import mcp.types as types from mcp.server.streamable_http import run_streamable_http_server app Server(python-mcp-http) app.tool(namehello, description基础测试工具验证服务连通性) async def hello(name: str) - list[types.TextContent]: return [types.TextContent(typetext, textfHello {name}! Linux Python MCP 远程服务调用成功)] app.tool(nameadd, description两数相加计算工具) async def add(a: float, b: float) - list[types.TextContent]: return [types.TextContent(typetext, textf计算结果{a b})] def main(): run_streamable_http_server( app, host0.0.0.0, port8120, path/mcp ) if __name__ __main__: main()systemd 服务文件写到/etc/systemd/system/mcp-python-http.service注意ExecStart用的是虚拟环境里的 Python 绝对路径[Unit] DescriptionPython MCP Streamable HTTP Production Server Afternetwork.target [Service] Userroot WorkingDirectory/opt/mcp-python ExecStart/opt/mcp-python/venv/bin/python3 http_server.py Restarton-failure RestartSec5 EnvironmentPYTHONUNBUFFERED1 [Install] WantedBymulti-user.target启动并设置开机自启systemctl daemon-reload systemctl enable mcp-python-http systemctl start mcp-python-http systemctl status mcp-python-http端口放行按系统选一条# Ubuntu ufw allow 8120/tcp # CentOS / 麒麟 firewall-cmd --add-port8120/tcp --permanent firewall-cmd --reload客户端侧如果要走 TaoToken 统一入口以 Cursor 的模型配置为例Base URL 填https://taotoken.net/apiKey 填控制台创建的 KeyModel ID 填你确认可用的模型。这三件套Base URL Key Model ID在 Cline、CC Switch、Codex 的auth.json里也是同样的结构只是字段名不同。MCP 服务地址则单独写在mcpServers段里两者不要混。4. 验证请求与成功结果从自检到真实工具调用服务起来之后不要急着接客户端先在服务器本机自检。用 curl 打一下端点确认服务在监听curl -i http://127.0.0.1:8120/mcp如果返回 200 或协议握手相关的响应说明服务进程正常。接着用官方 Inspector 做可视化调试npx modelcontextprotocol/inspector --url http://127.0.0.1:8120/mcp打开浏览器界面后你能看到工具列表里有hello和add两个工具点进去手动调用一次观察报文收发。这一步能确认工具注册和协议握手都没问题。然后用自研 Agent 的客户端代码做一次真实调用from mcp.client.streamable_http import streamable_http_client from mcp import ClientSession import asyncio async def mcp_client_demo(): async with streamable_http_client(http://服务器IP:8120/mcp) as (read, write): async with ClientSession(read, write) as session: await session.initialize() res await session.call_tool(add, arguments{a: 100, b: 200}) print(MCP 工具调用结果, res) if __name__ __main__: asyncio.run(mcp_client_demo())预期输出里能看到计算结果300.0这样的文本内容。如果这一步成功说明「服务端工具注册 → HTTP 传输 → 客户端协议握手 → 工具调用」整条链路是通的。Claude Desktop 和 Cursor 的接入配置分别写到各自文件里。Claude Desktop 的claude_desktop_config.json{ mcpServers: { linux-python-mcp: { url: http://服务器IP:8120/mcp } } }Cursor 的.cursor/mcp.json内容一致保存后完全退出客户端再重启最小化窗口不会重新加载配置。重启后在客户端的工具列表里应该能看到hello和add手动触发一次hello返回问候信息就说明客户端侧也通了。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth排障时先分清是哪一层的问题模型请求层还是 MCP 工具层。下面几个报错是实际部署里最常撞到的。401 Unauthorized一般出现在模型请求层说明 Key 没填对或没带上。检查客户端里 Base URL 是否为https://taotoken.net/apiKey 是否完整复制、有没有多余空格。如果用的是 Codex 的auth.json确认字段名和层级没写错Key 要放在正确的鉴权字段下。local proxy failed通常和网络出口或代理配置有关。先确认服务器本身能正常访问外网再检查客户端有没有残留的代理设置。MCP 服务本身监听0.0.0.0:8120如果客户端连的是公网 IP要确认云安全组和系统防火墙都放行了 8120。reading choices这类报错多出现在模型返回结构不符合预期时常见原因是 Model ID 填错或者客户端把非对话接口当成了对话接口。回到模型对话页面确认可用模型把 Model ID 原样填进客户端。OAuth相关报错一般出现在客户端尝试走官方鉴权流程时。如果你已经把 Base URL 改到 TaoToken就不应该再触发官方 OAuth。检查客户端配置里有没有残留的官方登录态清掉后重新用 Key 鉴权。还有一个高频坑客户端配置不生效。Claude Desktop 和 Cursor 都需要完全退出进程再启动托盘里最小化不算退出。另外 MCP 服务端路径必须和客户端 URL 里的/mcp完全一致少一个斜杠都会握手失败。模块缺失报错则基本是用了系统 Python 而不是虚拟环境里的解释器检查 systemd 文件里的ExecStart路径。6. 把 Claude、Cursor 和自研 Agent 收敛到一套接入部署完成之后你的结构应该是这样的Linux 服务器上跑一个 systemd 常驻的 Python MCP 服务对外暴露/mcp端点Claude Desktop、Cursor、自研 Agent 各自在配置里填这个 URL工具能力就统一了模型请求层则通过 TaoToken 的 Base URL 和 Key 收敛到一个入口Key 在控制台管理模型在模型对话页确认。后续要扩展工具只需要在http_server.py里加app.tool装饰的函数重启服务所有客户端自动获得新工具不用逐个改配置。如果要上生产建议在 Nginx 后面加一层反向代理并启用 HTTPS同时给 MCP 端点加 Bearer Token 校验避免公网裸端口暴露。日志用journalctl -u mcp-python-http -f实时看工具调用记录建议持久化方便溯源。需要长期跑编码 Agent 的话Coding Plan 比按次调用更合适入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入文档和 API Key 管理分别在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 和 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。Claude Code 相关的接入可以参考 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite 里面有针对 Anthropic 协议的配置说明。最后留一个实操建议每次改完服务端代码先在本机用 Inspector 调一次再重启 systemd最后才去客户端验证。这个顺序能帮你把问题锁定在最小范围内不至于服务端和客户端同时改、出了问题不知道是谁的锅。