1. 为什么 MCP Inspector 连不上本地 ServerMCP Inspector 是官方给 MCP Server 做可视化调试的交互式工具说白了就是 MCP 世界的 Postman能列出 Server 暴露的 tools、resources、prompts填入参数直接调用看返回结果。适合正在写 MCP Server 的开发者、做 AI Agent 工具链的同学以及想把内部能力封装成 MCP 接口但不确定通不通的人。我最近在本地起了一个基于 FastMCP 的 Server用mcp.run(transportstreamable-http)启动命令行看着一切正常端口也监听了但 Inspector 里点 Connect 就是转圈Server 端日志刷出一堆和 session、CORS 相关的报错。换成 SSE 模式又是另一套问题。折腾一圈才理清问题不在 Inspector而在 Server 的 ASGI 组装方式——FastMCP 自带的run()把 app 包得太死跨域和 session header 没暴露出来Inspector 拿不到Mcp-Session-Id握手直接断。这篇就把从连不上到跑通的完整链路写清楚Starlette 怎么挂载 streamable_http_app、CORS 要放哪些 origin、Inspector 的 Transport Type 和 URL 怎么填、SSE 旧模式怎么切以及怎么用 TaoToken 的统一 Key 给 Server 里的模型调用兜底。全程可复制照着改就能复现。2. TaoToken 前置统一 Key 与 API 通道MCP Server 本身只是协议层真正干活时经常要调模型——比如一个summarizetool 内部要请求大模型。如果每个 tool 都自己配一套 key本地调试会非常乱。我的做法是让 Server 统一走 TaoToken 的 API 通道一个 Key 覆盖多家模型调试时只关心协议通不通不用来回换配置。TaoToken 在这里的角色是「统一入口」官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。你需要在控制台建一个 Key然后把它写进 Server 的环境变量或配置文件。注意 API 地址不带 UTM 参数直接写https://taotoken.net/api即可。拿 Key 的入口在控制台创建后复制那串sk-开头的字符串。建议不要硬编码进server.py用.env或系统环境变量注入后面 Inspector 调试时改配置不用动代码。如果你后面要做长期编码或 Agent 循环调用可以看下 Coding Plan只是验证模型连通性用模型对话页面点几下就够了。3. 可复制配置Starlette CORS 骨架核心改动就一处别用mcp.run()改成手动组装 Starlette app把streamable_http_app()挂到路由上再套一层CORSMiddleware。下面是我实测能跑通的server.py骨架。# server.py import os from contextlib import asynccontextmanager from starlette.applications import Starlette from starlette.middleware.cors import CORSMiddleware from starlette.routing import Mount from mcp.server.fastmcp import FastMCP import uvicorn mcp FastMCP(demo-server) mcp.tool() def add(a: int, b: int) - int: 两数相加用于验证 tool 调用链路 return a b mcp.tool() def summarize(text: str) - str: 调用 TaoToken 统一通道做摘要示例占位 # 实际请求走 https://taotoken.net/api return freceived {len(text)} chars asynccontextmanager async def lifespan(app): async with mcp.session_manager.run(): yield app Starlette( routes[ Mount(/, appmcp.streamable_http_app()), ], lifespanlifespan, ) app CORSMiddleware( app, allow_origins[ http://localhost:6274, http://127.0.0.1:6274, ], allow_methods[GET, POST, DELETE, OPTIONS], allow_headers[*], expose_headers[Mcp-Session-Id], ) if __name__ __main__: uvicorn.run(app, host127.0.0.1, port8000)几个关键点必须对上错一个就连不上配置项值作用Mount 路径/挂streamable_http_app()实际端点变成/mcpallow_originslocalhost:6274和127.0.0.1:6274Inspector 默认端口expose_headersMcp-Session-Id浏览器要读到这个头allow_methods含 DELETE关闭 session 用lifespanmcp.session_manager.run()不写会报 session 未初始化启动命令uv run server.py # 或 python server.py看到Uvicorn running on http://127.0.0.1:8000就说明 Server 起来了。此时先别急着开 Inspector用 curl 探一下端点是否活着curl -i -X POST http://127.0.0.1:8000/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d {jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:curl,version:1.0}}}返回里带Mcp-Session-Id响应头说明协议层通了。这一步能省掉后面一半的排查时间。4. 验证请求Inspector 连接与 Run Tool先启动 Inspectornpx modelcontextprotocol/inspector如果浏览器打不开命令行里设一下 hostset HOST127.0.0.1 npx modelcontextprotocol/inspector启动后 URL 会变成127.0.0.1:6274浏览器就能访问了。进入界面后按下面填Transport TypeStreamable HTTPURLhttp://127.0.0.1:8000/mcpConnection TypeDirect点 Connect。连上后右侧出现资源面板因为示例 Server 只定义了 tools点 Tools 面板再点 List Tools就能看到add和summarize。选中add右侧出现参数表单填a3、b4点 Run Tool返回7就说明整条链路通了。如果要用 SSE 旧模式Server 端把 Mount 那行换掉app Starlette( routes[ Mount(/, appmcp.sse_app()), ], )注意 SSE 模式不需要lifespan去掉即可。Inspector 里 Transport Type 选SSEURL 填http://127.0.0.1:8000/sse其余操作一样。不过 SSE 是旧实现新项目建议直接用 Streamable HTTP。5. 本篇常见错排查连不上、Server 日志报 session 相关错误八成是没写lifespan或者用了mcp.run()而不是手动挂载。streamable_http_app()依赖 session manager 的生命周期必须用lifespan包住。浏览器控制台报 CORS检查allow_origins是否同时包含localhost:6274和127.0.0.1:6274。只写一个另一个访问方式就会被拦。连上了但 List Tools 为空确认 tool 是用mcp.tool()装饰的且函数有类型注解和 docstring。缺类型注解时 FastMCP 可能无法生成参数 schema。Run Tool 报 400 或参数校验失败Inspector 表单是按 schema 生成的如果 schema 里参数是必填但你没填会直接报错。对照右侧描述补全。端口冲突8000 被占用时换端口但 Inspector 里的 URL 也要同步改别只改一边。curl 能通、Inspector 不通基本锁定在 CORS 和expose_headers。Mcp-Session-Id没暴露浏览器读不到后续请求就带不上 session。6. 继续调试与接入跑通之后日常调试就是改 tool、重启 Server、Inspector 里重新 List Tools 再 Run。Server 里如果涉及模型调用统一走 TaoToken 的 API 通道Key 在控制台管理接入细节看接入文档。需要验证模型返回是否正常直接用模型对话页面测要做长期编码或 Agent 循环Coding Plan 更合适。API Keys 页面负责建 Key 和轮换别把 Key 写进代码提交到仓库。实测下来MCP Inspector 最大的价值是省掉了自己写 MCP Client 的成本——协议握手、session 管理、参数表单它都替你做了你只需要专注 Server 端逻辑。把 Starlette 挂载和 CORS 这两处配对后面基本不会再卡在连接上。