FastMCP 中文入门 · 宿主接通

verify 全绿，为什么
Cursor 里还是找不到？

第1课我会写 Tool，第2课我把 Resource / Prompt 也立住了。这节课不重复拆装饰器，专门讲宿主：配置放哪、环境为什么隔离、挂不上怎么排、CLI 里怎么验到能分辨对错。

▸ 方向键 / 空格 / 点击翻页　·　右下角可“自动播放”

魂：verify 全绿，不等于 Cursor 已经接通。

本期速览 · OVERVIEW

两道验收 · 一张地图

矛盾

≠

绿 ≠ 通

配置

项目级

.cursor/mcp.json

探针

whoami

固定身份串

过关

CLI

list + 真调

进程内绿灯只是入场券；CLI list + 真调才算过关。

学习目标

这节课你学完能做什么

1

能画清：进程内 Client 与宿主 mcp.json 是两道独立验收

2

知道配置放项目 .cursor/mcp.json 还是全局 ~/.cursor/mcp.json

3

会用 Cursor CLI：list → list-tools → agent 调 whoami；挂不上能改路径做对照

官方：Cursor 集成 / Running Your Server / Install MCP。

收藏卡① · 两道验收

verify 绿 ≠ 宿主通

我卡过无数次：verify OK，CLI 却 not loaded / 列表没有；多半不是 tool 写错。

验收	入口	绿灯只证明	红灯先查
进程内	uv run …/verify.py	tool 逻辑与返回值	server.py / assert
宿主	agent mcp list + 真调	宿主能发现并调用	路径、uv、env、是否在仓库根

尺子：verify 绿 + list 挂 = 配置/环境；verify 红 = 先别碰宿主。

两道验收独立；别用一道的结果推断另一道。

收藏卡② · 配置地图

项目级 vs 全局

位置	路径	适用
项目级（推荐）	fastmcp-lab/.cursor/mcp.json	只在本仓；CLI 也要在仓库根跑
全局	~/.cursor/mcp.json	任意工作区；易串味

官方 CLI 常用 --workspace .。我本机无 IDE 只用 CLI，验收一样：list ready + 真调。

本课跟读用项目级，避免全局串味。

隔离环境

uv / env / 别污染 stdout

默认传输 STDIO：宿主把 server 当子进程。

1

生命周期归宿主：不用长期挂 python server.py

2

环境隔离：看不到 shell 变量 → 密钥/env 写进 mcp.json；本课关 FASTMCP_CHECK_FOR_UPDATES

3

stdout 金贵：协议走 stdout，乱 print 会 silently 坏；调试走 stderr

PATH 里要有 uv；宿主不用你碰巧激活的 venv。

收藏卡③ · mcp.json 字段

两条接通路径

路径 A · 官方 CLI

uv run fastmcp install cursor ep03-host-connect/server.py --workspace .

路径 B · 手写（本课主跟）

复制 cursor-mcp.example.json → 改绝对路径 → 合并进 .cursor/mcp.json

字段	本课取值	干什么
type	stdio	本地子进程
command	uv	管项目环境
args	run --directory … python …/server.py	在仓根起 server
env	FASTMCP_CHECK_FOR_UPDATES=off	关启动查版本

最小字段表是收藏卡核心。

配置示意

mcp.json 长什么样

.cursor/mcp.json示意

"mcpServers": { "ep03-host-connect": {
  "type": "stdio", "command": "uv",
  "args": ["run", "--directory", "/绝对路径/fastmcp-lab",
           "python", "ep03-host-connect/server.py"],
  "env": { "FASTMCP_CHECK_FOR_UPDATES": "off" }
}}

绝对路径写错是最常见挂点；下一步故意改错做对照。

收藏卡④ · 相对第1课

代码只多两刀

不重复拆装饰器；多两刀服务「宿主接通探针」。

1

instructions：玩具域、只做接通练习

2

whoami：无参固定身份串，调通=连的是本课 server

server.py探针

mcp = FastMCP("ep03-host-connect",
    instructions="玩具域 hello server。只用于本机接通练习。")
@mcp.tool
def whoami() -> str:
    return "ep03-host-connect · FastMCP lab"

verify 进程内 assert 同句；打印写「Cursor 接通另见 README」。

排障实验

故意改错路径

1

基线

verify 绿 + agent mcp list ready

2

打坏

故意改错 --directory 一个字母

3

对照

再 list → 挂/非 ready；verify 应仍绿 → 问题在宿主配置

4

修好

改回 → ready → list-tools 见 whoami

尺子：先分「代码红」还是「配置红」。

这是能分辨对错的实验设计。

CLI 验收剧本

在仓库根执行

fastmcp-lab 根剧本

agent mcp list
agent mcp enable ep03-host-connect   # needs approval 时
agent mcp list-tools ep03-host-connect
agent -p "请只调用MCP工具whoami，把返回值原样打出来，不要解释" --mode ask

过关：ready + whoami () · 返回 ep03-host-connect · FastMCP lab

进程内绿灯只是入场券；CLI 这两步才算过关。

踩坑速查

挂了先对这五条

1

不在仓库根跑 CLI → 项目级 mcp.json 不生效

2

--directory 错 → verify 仍可能绿，list 挂

3

找不到 uv / 代理启动失败 → 给 FASTMCP_CHECK_FOR_UPDATES=off

4

needs approval → agent mcp enable

5

stdout 被污染 → server 别往 stdout 打调试

速查卡可收藏。

本节练习

必做 + 选做

必

verify → CLI 剧本真调 whoami

选

故意改错路径对照；试官方 fastmcp install cursor … --workspace .

过关标准：list ready + 真调返回固定身份串。

练习要对齐两道验收。

小结

带走两道验收

1

verify 管逻辑；list + 真调管宿主

2

交付：配置地图 + 隔离常识 + 打坏修好 + CLI 剧本

verify 全绿，不等于 Cursor 已经接通。两道验收，缺一不可。

传输面留给后课。

选题征集

你卡在哪一步？

①

路径

--directory / 仓库根

②

uv

PATH / 环境隔离

③

代理横幅

启动查版本

④

approval

list 亮了 Agent 不调

片尾征集。

— FastMCP 中文入门 · EP 03 —

会勇禾口王的AI笔记

FastMCP 中文入门 · FASTMCP LAB · EP03 · @huiyonghkw

verify 绿只是入场券 · CLI 真调才算过关

系列 · 官方文档陪读 · 边造边学

微信搜 会勇禾口王的AI笔记，回复 MCP 领收藏卡清单

片尾签收。

verify 全绿，为什么Cursor 里还是找不到？

两道验收 · 一张地图

这节课你学完能做什么

verify 绿 ≠ 宿主通

项目级 vs 全局

uv / env / 别污染 stdout

两条接通路径

mcp.json 长什么样

代码只多两刀

故意改错路径

在仓库根执行

挂了先对这五条

必做 + 选做

带走两道验收

你卡在哪一步？

路径

uv

代理横幅

approval

verify 全绿，为什么
Cursor 里还是找不到？