1. 为什么要在 Cursor 里给 MCP 配一个统一通道MCP 是 Model Context Protocol 的缩写它做的事情可以理解成给大模型装了一排标准插座不管背后是本地脚本、远程服务还是数据库查询只要按 MCP 协议暴露成 tools、resources、prompts客户端就能用同一套方式调用。Cursor 从 0.4x 版本开始支持 MCP你可以在编辑器里直接让 Agent 调用自己写的工具函数比如算个数、查个文件、跑个脚本。但真正上手时很多人会卡在同一个地方每个 MCP server 都要单独配 Key、单独填 base_url项目一多settings.json 就变成一团乱麻。我这次的做法是把模型请求统一走 TaoToken 的 API 通道MCP server 本身只负责暴露工具不关心模型从哪来。这样 Cursor 里的 settings.json 骨架就能保持干净换模型、换 Key 只改一处。这篇适合谁已经会用 Python 写点小脚本、想在 Cursor 里跑通第一个 MCP server、并且希望把模型调用收敛到一个入口的人。工具链用 FastMCP uv前者是 MCP Python SDK 里的高层封装后者负责虚拟环境和依赖锁定。整条链路跑通后你会在 Cursor 里看到 Agent 成功调用add工具并返回结果。2. 前置准备TaoToken 通道与 uv 环境2.1 拿到统一 Key 和 API 地址TaoToken 在这里的角色是模型请求的统一入口。你不需要在 MCP server 里硬编码某个厂商的地址而是把 base_url 指向https://taotoken.net/apiKey 从控制台生成。这样做的好处是MCP server 代码里只出现一个环境变量Cursor 的 settings.json 里也只引用这个变量不会散落多个 Key。具体操作路径打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 进控制台在 API Keys 页面创建一个新 Key。建议按项目命名比如cursor-mcp-test方便后面排查是哪个项目在用。创建后先复制到剪贴板后面写进.env文件。注意Key 只显示一次如果没存下来就重新生成一个。不要把它直接写进会提交到 git 的 settings.json用环境变量或.env隔离。2.2 用 uv 初始化项目uv 是 Rust 写的 Python 包管理器速度比 pip 快很多而且自带锁文件。先确认本机装了 uvuv --version如果没有按官方方式装一个即可。然后建项目目录mkdir mcp-server-test cd mcp-server-test uv init --python 3.11uv init会生成pyproject.toml和.python-version。接着加依赖uv add mcp[cli]1.0.0这一步会创建.venv并写入uv.lock。如果你之前用pip install -r requirements.txt报过Could not find a version that satisfies the requirement mcp[cli]1.0.0大概率是当前 pip 源没同步这个包换成uv add走默认源就能解决。装完后验证一下uv run python -c import mcp; print(mcp.__version__)能打印出版本号说明 SDK 就位。3. 可复制配置FastMCP server 与 Cursor settings.json 骨架3.1 写一个最小 FastMCP server在项目根目录建server.py内容如下。这里只保留一个add工具和一个info资源目的是让链路最短、排错最容易from mcp.server.fastmcp import FastMCP mcp FastMCP(mcp-server-test, json_responseTrue) mcp.tool() def add(a: int, b: int) - int: 将两个整数相加 return a b mcp.resource(info://server) def server_info() - str: return mcp-server-test | FastMCP | tools: add if __name__ __main__: mcp.run()FastMCP的构造函数第一个参数是 server 名称json_responseTrue让返回走 JSON 格式方便 Cursor 解析。mcp.tool()装饰器把普通函数注册成 MCP 工具类型注解会被自动转成参数 schema。3.2 Cursor 的 settings.json 骨架Cursor 的 MCP 配置有两个位置全局~/.cursor/mcp.json和项目级项目根/.cursor/mcp.json。项目级优先推荐用项目级这样配置跟着代码走。在项目根建.cursor/mcp.json骨架如下{ mcpServers: { mcp-server-test: { command: uv, args: [run, python, server.py], env: { TAOTOKEN_API_KEY: 你的Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }这里command用uvargs是run python server.py。关键点是 Cursor 打开的工作区根目录必须是mcp-server-test这样uv run的 cwd 正好是项目目录能找到server.py和pyproject.toml。如果你遇到ModuleNotFoundError: No module named mcp说明 Cursor 用了系统 Python 而不是项目.venv。改成显式指定解释器和绝对路径{ mcpServers: { mcp-server-test: { command: /绝对路径/mcp-server-test/.venv/bin/python, args: [/绝对路径/mcp-server-test/server.py], env: { TAOTOKEN_API_KEY: 你的Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }把/绝对路径/换成你机器上的真实路径。这样即使 Cursor 的 cwd 不对也能找到解释器和脚本。3.3 参数对照表字段作用常见坑command启动 MCP server 的可执行文件写uv时依赖 cwd 正确args传给 command 的参数路径含空格要确认转义env注入环境变量Key 不要提交到 gitTAOTOKEN_BASE_URL统一 API 入口不要带尾部斜杠4. 验证请求从 Inspector 到 Cursor Agent4.1 先用 MCP Inspector 验证 server 本身在项目目录启动 HTTP 模式uv run python server.py --http如果server.py里没写--http分支可以临时用 stdio 模式配合 Inspector。更稳的方式是直接用 Inspector 连 stdionpx -y modelcontextprotocol/inspector uv run python server.pyInspector 会打开一个本地页面在 Tools 标签里找到add输入a1、b1点调用。返回2就说明 server 注册和调用都正常。这一步不涉及 Cursor先把 server 单独跑通能省掉后面一半的排查时间。4.2 在 Cursor 里让 Agent 调用保存.cursor/mcp.json后重启 Cursor。打开项目在对话里输入用 add 工具算 1 加 1如果配置正确Agent 会调用 MCP 工具并返回2。如果日志里出现No server info found说明 Cursor 没能把 server 跑起来拿不到任何能力信息。排查顺序先确认command和args路径正确再确认 cwd 是项目根最后确认.venv里装了mcp。4.3 验证 TaoToken 通道MCP server 本身不直接调模型但你可以加一个工具来验证通道是否通。比如加一个ask_model工具内部用TAOTOKEN_BASE_URL和TAOTOKEN_API_KEY发请求。这样在 Cursor 里调用它就能同时验证 MCP 链路和 TaoToken 通道。如果只想先验证模型对话可以直接用模型对话页面发一条消息确认 Key 有效。5. 本篇常见错排查5.1 Invalid JSON: EOF while parsing a value这个报错出现在 stdio 模式下。MCP 把每一行 stdin 当成 JSON-RPC 消息解析如果你在运行 server 的终端里随手敲了回车空行不是合法 JSON就会报这个错。处理方式很简单stdio 模式下不要手动输入任何内容只让 Cursor 或 Inspector 来写 stdin。5.2 Could not find a version that satisfies the requirement mcp[cli]1.0.0pip 源里没有mcp包常见于内网镜像或网络受限环境。不是写法问题PyPI 上确实有。换成uv add mcp[cli]1.0.0或者临时指定源pip install mcp[cli]1.0.0 -i https://pypi.org/simple5.3 ModuleNotFoundError: No module named mcpCursor 启动 MCP 时用的 Python 不是项目.venv里的。解决方式是在mcp.json里显式写.venv/bin/python的绝对路径args里写server.py的绝对路径。这样不依赖 cwd也不依赖 Cursor 的环境推断。5.4 No server info foundCursor 启动 server 失败没收到 tools/resources/prompts 信息。最常见原因是全局~/.cursor/mcp.json里用了command: uv但 Cursor 的 cwd 不是项目根找不到server.py。改用项目级.cursor/mcp.json或者用绝对路径。改完记得重启 Cursor配置不会热加载。5.5 端口占用HTTP 模式默认监听 8000如果被占用会启动失败。换端口uv run python server.py --http --port 8010然后在 Inspector 里把 URL 改成http://localhost:8010/mcp。6. 把链路固定下来下一步怎么走跑通最小链路后建议做三件事。第一把TAOTOKEN_API_KEY从mcp.json里挪到系统环境变量或.env避免 Key 进 git。第二把server.py里的工具按项目需要扩展FastMCP 的mcp.tool()可以叠加多个resources 和 prompts 也按同样方式注册。第三如果后面要长期在 Cursor 里做编码和 Agent 任务可以了解 Coding Plan把模型调用和 MCP 工具链一起管起来。接入文档里有更完整的参数说明和示例遇到配置问题时对照着看会快很多。模型对话页面适合快速验证 Key 和通道API Keys 页面用来管理多个项目的 Key。整条链路的核心就一句话MCP server 负责暴露能力TaoToken 负责统一模型入口Cursor 的 settings.json 只做连接。把这三层分清楚后面加多少工具都不会乱。
MCP 学习笔记：用 FastMCP + uv 在 Cursor 里配 TaoToken 的 settings.json 骨架
1. 为什么要在 Cursor 里给 MCP 配一个统一通道MCP 是 Model Context Protocol 的缩写它做的事情可以理解成给大模型装了一排标准插座不管背后是本地脚本、远程服务还是数据库查询只要按 MCP 协议暴露成 tools、resources、prompts客户端就能用同一套方式调用。Cursor 从 0.4x 版本开始支持 MCP你可以在编辑器里直接让 Agent 调用自己写的工具函数比如算个数、查个文件、跑个脚本。但真正上手时很多人会卡在同一个地方每个 MCP server 都要单独配 Key、单独填 base_url项目一多settings.json 就变成一团乱麻。我这次的做法是把模型请求统一走 TaoToken 的 API 通道MCP server 本身只负责暴露工具不关心模型从哪来。这样 Cursor 里的 settings.json 骨架就能保持干净换模型、换 Key 只改一处。这篇适合谁已经会用 Python 写点小脚本、想在 Cursor 里跑通第一个 MCP server、并且希望把模型调用收敛到一个入口的人。工具链用 FastMCP uv前者是 MCP Python SDK 里的高层封装后者负责虚拟环境和依赖锁定。整条链路跑通后你会在 Cursor 里看到 Agent 成功调用add工具并返回结果。2. 前置准备TaoToken 通道与 uv 环境2.1 拿到统一 Key 和 API 地址TaoToken 在这里的角色是模型请求的统一入口。你不需要在 MCP server 里硬编码某个厂商的地址而是把 base_url 指向https://taotoken.net/apiKey 从控制台生成。这样做的好处是MCP server 代码里只出现一个环境变量Cursor 的 settings.json 里也只引用这个变量不会散落多个 Key。具体操作路径打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 进控制台在 API Keys 页面创建一个新 Key。建议按项目命名比如cursor-mcp-test方便后面排查是哪个项目在用。创建后先复制到剪贴板后面写进.env文件。注意Key 只显示一次如果没存下来就重新生成一个。不要把它直接写进会提交到 git 的 settings.json用环境变量或.env隔离。2.2 用 uv 初始化项目uv 是 Rust 写的 Python 包管理器速度比 pip 快很多而且自带锁文件。先确认本机装了 uvuv --version如果没有按官方方式装一个即可。然后建项目目录mkdir mcp-server-test cd mcp-server-test uv init --python 3.11uv init会生成pyproject.toml和.python-version。接着加依赖uv add mcp[cli]1.0.0这一步会创建.venv并写入uv.lock。如果你之前用pip install -r requirements.txt报过Could not find a version that satisfies the requirement mcp[cli]1.0.0大概率是当前 pip 源没同步这个包换成uv add走默认源就能解决。装完后验证一下uv run python -c import mcp; print(mcp.__version__)能打印出版本号说明 SDK 就位。3. 可复制配置FastMCP server 与 Cursor settings.json 骨架3.1 写一个最小 FastMCP server在项目根目录建server.py内容如下。这里只保留一个add工具和一个info资源目的是让链路最短、排错最容易from mcp.server.fastmcp import FastMCP mcp FastMCP(mcp-server-test, json_responseTrue) mcp.tool() def add(a: int, b: int) - int: 将两个整数相加 return a b mcp.resource(info://server) def server_info() - str: return mcp-server-test | FastMCP | tools: add if __name__ __main__: mcp.run()FastMCP的构造函数第一个参数是 server 名称json_responseTrue让返回走 JSON 格式方便 Cursor 解析。mcp.tool()装饰器把普通函数注册成 MCP 工具类型注解会被自动转成参数 schema。3.2 Cursor 的 settings.json 骨架Cursor 的 MCP 配置有两个位置全局~/.cursor/mcp.json和项目级项目根/.cursor/mcp.json。项目级优先推荐用项目级这样配置跟着代码走。在项目根建.cursor/mcp.json骨架如下{ mcpServers: { mcp-server-test: { command: uv, args: [run, python, server.py], env: { TAOTOKEN_API_KEY: 你的Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }这里command用uvargs是run python server.py。关键点是 Cursor 打开的工作区根目录必须是mcp-server-test这样uv run的 cwd 正好是项目目录能找到server.py和pyproject.toml。如果你遇到ModuleNotFoundError: No module named mcp说明 Cursor 用了系统 Python 而不是项目.venv。改成显式指定解释器和绝对路径{ mcpServers: { mcp-server-test: { command: /绝对路径/mcp-server-test/.venv/bin/python, args: [/绝对路径/mcp-server-test/server.py], env: { TAOTOKEN_API_KEY: 你的Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }把/绝对路径/换成你机器上的真实路径。这样即使 Cursor 的 cwd 不对也能找到解释器和脚本。3.3 参数对照表字段作用常见坑command启动 MCP server 的可执行文件写uv时依赖 cwd 正确args传给 command 的参数路径含空格要确认转义env注入环境变量Key 不要提交到 gitTAOTOKEN_BASE_URL统一 API 入口不要带尾部斜杠4. 验证请求从 Inspector 到 Cursor Agent4.1 先用 MCP Inspector 验证 server 本身在项目目录启动 HTTP 模式uv run python server.py --http如果server.py里没写--http分支可以临时用 stdio 模式配合 Inspector。更稳的方式是直接用 Inspector 连 stdionpx -y modelcontextprotocol/inspector uv run python server.pyInspector 会打开一个本地页面在 Tools 标签里找到add输入a1、b1点调用。返回2就说明 server 注册和调用都正常。这一步不涉及 Cursor先把 server 单独跑通能省掉后面一半的排查时间。4.2 在 Cursor 里让 Agent 调用保存.cursor/mcp.json后重启 Cursor。打开项目在对话里输入用 add 工具算 1 加 1如果配置正确Agent 会调用 MCP 工具并返回2。如果日志里出现No server info found说明 Cursor 没能把 server 跑起来拿不到任何能力信息。排查顺序先确认command和args路径正确再确认 cwd 是项目根最后确认.venv里装了mcp。4.3 验证 TaoToken 通道MCP server 本身不直接调模型但你可以加一个工具来验证通道是否通。比如加一个ask_model工具内部用TAOTOKEN_BASE_URL和TAOTOKEN_API_KEY发请求。这样在 Cursor 里调用它就能同时验证 MCP 链路和 TaoToken 通道。如果只想先验证模型对话可以直接用模型对话页面发一条消息确认 Key 有效。5. 本篇常见错排查5.1 Invalid JSON: EOF while parsing a value这个报错出现在 stdio 模式下。MCP 把每一行 stdin 当成 JSON-RPC 消息解析如果你在运行 server 的终端里随手敲了回车空行不是合法 JSON就会报这个错。处理方式很简单stdio 模式下不要手动输入任何内容只让 Cursor 或 Inspector 来写 stdin。5.2 Could not find a version that satisfies the requirement mcp[cli]1.0.0pip 源里没有mcp包常见于内网镜像或网络受限环境。不是写法问题PyPI 上确实有。换成uv add mcp[cli]1.0.0或者临时指定源pip install mcp[cli]1.0.0 -i https://pypi.org/simple5.3 ModuleNotFoundError: No module named mcpCursor 启动 MCP 时用的 Python 不是项目.venv里的。解决方式是在mcp.json里显式写.venv/bin/python的绝对路径args里写server.py的绝对路径。这样不依赖 cwd也不依赖 Cursor 的环境推断。5.4 No server info foundCursor 启动 server 失败没收到 tools/resources/prompts 信息。最常见原因是全局~/.cursor/mcp.json里用了command: uv但 Cursor 的 cwd 不是项目根找不到server.py。改用项目级.cursor/mcp.json或者用绝对路径。改完记得重启 Cursor配置不会热加载。5.5 端口占用HTTP 模式默认监听 8000如果被占用会启动失败。换端口uv run python server.py --http --port 8010然后在 Inspector 里把 URL 改成http://localhost:8010/mcp。6. 把链路固定下来下一步怎么走跑通最小链路后建议做三件事。第一把TAOTOKEN_API_KEY从mcp.json里挪到系统环境变量或.env避免 Key 进 git。第二把server.py里的工具按项目需要扩展FastMCP 的mcp.tool()可以叠加多个resources 和 prompts 也按同样方式注册。第三如果后面要长期在 Cursor 里做编码和 Agent 任务可以了解 Coding Plan把模型调用和 MCP 工具链一起管起来。接入文档里有更完整的参数说明和示例遇到配置问题时对照着看会快很多。模型对话页面适合快速验证 Key 和通道API Keys 页面用来管理多个项目的 Key。整条链路的核心就一句话MCP server 负责暴露能力TaoToken 负责统一模型入口Cursor 的 settings.json 只做连接。把这三层分清楚后面加多少工具都不会乱。
