在 Cursor 里 MCP 面板显示 file-search 是绿的不代表对话里就能用文件搜索工具。模块三 3.2 的实操题是用 Python 写一个 MCP Server 实现文件搜索工具再在 Claude/Cursor 中注册使用。真正卡住人的地方往往不是 Python 那几十行而是 Cursor 侧的模型通道和 Key —— 面板上的 MCP 服务一直未就绪或者模型请求本身就不通工具列表压根加载不出来。这条只解决一件事把 Cursor 的模型通道换成 TaoToken。注册和创建 Key 在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcursor-mcp-intro 完成通道通了你再去跑本地那个 MCP Server。TaoToken 在这里只承担模型通道和 Key 来源两个角色不替代你自己写的 MCP Server也不接管任何文件搜索逻辑。文件在哪些目录、匹配什么关键字仍然由你的 Python 代码决定。1. 问题定位Cursor 侧模型通道与 mcp.json 是两条独立链路先把两件事拆开后面排查会快很多。第一条链路是 Cursor 调模型。Cursor 的 Chat、Tab、Agent 这些功能要发请求给某个模型端点请求带上模型 ID 和 Key。这条链路不通表现为对话没反应、报鉴权或连接类错误跟 MCP 没有半点关系。第二条链路是本机 MCP Server。Cursor 作为 Host按mcp.json里的command和args拉起一个本地子进程通过 stdio 和它通信拿到 Resources / Tools / Prompts 列表。这条链路不通表现为 MCP 面板红字、工具列表为空、调用报错。3.2 这节课的核心目标其实是第二条链路但很多人第一步就死在第一条链路上Cursor 里还留着旧的模型通道Key 可能失效或者配额耗尽结果一进 Agent 模式就请求失败误以为是 MCP Server 写错了。所以正确的顺序是先把模型通道切到 TaoToken 并验证普通对话再注册 MCP 文件搜索工具。顺序反了你会在一堆无关报错里打转。2. 拿 Key 的前置动作官网创建 模型广场确认模型 ID打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcursor-mcp-signup 注册账号进入控制台创建 API Key。Key 形如YOUR_API_KEY只在这一步出现一次复制后自己存好不要贴进 git 仓库。创建完 Key顺手在模型广场里确认你要用的模型 ID。这一步别省Cursor 里手填模型名时必须和模型广场给出的 ID 完全一致大小写、连字符、版本后缀都要对上。写错一个字符表现通常是模型列表里那一项被划掉或者对话直接返回模型不存在的错误。把两样东西记在手边Base URLhttps://taotoken.net/api结尾不带/v1也不加任何 UTM 参数KeyYOUR_API_KEY模型 ID以官网模型广场当前给出的为准3. Cursor 可复制配置Base URL 与 Key 填在哪Cursor 的模型设置路径大致是Settings → Models。找到 OpenAI 相关的 API Key 输入项同时打开 Override Base URL 的开关把地址填成https://taotoken.net/apiKey 填入刚创建的YOUR_API_KEY。保存之后回到 Models 列表如果目标模型不在默认列表里用 Add model 手动添加名称严格照模型广场的 ID 填。这里有两个非常常见的填法错误填成https://taotoken.net/api/v1。这样请求路径会多一层最终打到不存在的端点上。基址就是https://taotoken.net/api/v1不要自己补。从浏览器地址栏直接复制带 UTM 的官网链接粘进去。那串?utm_source...是统计参数不是 API 地址的一部分。另外如果你同时在用 Claude Code它的配置是另一套走settings.json里的ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY跟 Cursor 的 OpenAI 兼容配置不要混用、也不要把ANTHROPIC_*变量塞进 Cursor 的配置里。4. Python 侧file-search 这个 MCP Server 怎么写模型通道配好后回到模块三 3.2 的正题。用官方 MCP Python SDK 写一个最小可用的文件搜索 Serverpip install mcp[cli]# server.py from __future__ import annotations import os from pathlib import Path from mcp.server.fastmcp import FastMCP SEARCH_ROOT Path(os.environ.get(SEARCH_ROOT, .)).resolve() MAX_RESULTS int(os.environ.get(MAX_RESULTS, 50)) SKIP_DIRS {.git, node_modules, __pycache__, .venv, dist} mcp FastMCP(file-search) def _iter_files(): for path in SEARCH_ROOT.rglob(*): if any(part in SKIP_DIRS for part in path.parts): continue if path.is_file(): yield path mcp.tool() def search_files(keyword: str, suffix: str ) - str: 在 SEARCH_ROOT 目录下按文件名或文件内容搜索关键字返回相对路径列表。 hits: list[str] [] for path in _iter_files(): if suffix and path.suffix ! suffix: continue if keyword in path.name: hits.append(str(path.relative_to(SEARCH_ROOT))) else: try: text path.read_text(encodingutf-8, errorsignore) except OSError: continue if keyword in text: hits.append(str(path.relative_to(SEARCH_ROOT))) if len(hits) MAX_RESULTS: break return \n.join(hits) if hits else NO_MATCH if __name__ __main__: mcp.run()几点设计上的取舍值得说明搜索根目录和结果上限都从环境变量读是为了让同一份代码在不同项目里复用跳过.git、node_modules这类目录是为了避免一次调用扫出几万个文件把上下文撑爆。这个 Server 只读本地工作区不碰任何外部服务。写好之后先用 Inspector 在终端确认工具本身没问题npx modelcontextprotocol/inspector python /abs/path/to/server.pyInspector 里能看到search_files这个工具以及它的入参 schema再手动调一次返回一批相对路径说明 Server 侧已经完成。5. 注册到 Cursormcp.json 与工具列表检查Cursor 认的是mcp.json全局配置在~/.cursor/mcp.json也可以放到项目里的.cursor/mcp.json。内容形如{ mcpServers: { file-search: { command: /abs/path/to/venv/bin/python, args: [/abs/path/to/server.py], env: { SEARCH_ROOT: /abs/path/to/your/workspace, MAX_RESULTS: 50 } } } }三个细节决定它能不能起来command用绝对路径的解释器别只写python。Cursor 拉子进程时的 PATH 和你在终端里不一定相同虚拟环境里的 SDK 也未必在系统解释器里。args里的脚本路径同样用绝对路径相对路径会以 Cursor 的工作目录为基准解析很容易指向别处。SEARCH_ROOT指向你要检索的工作区别直接给家目录或者整个磁盘根。保存后重启 Cursor或按提示重载 MCP 配置。打开 MCP 面板file-search应该变成可用状态展开能看到search_files工具。看到工具名才算注册成功。6. 验证顺序先一条普通对话再调 search_files按前面说的顺序验证不要跳步。第一步在 Cursor 的 Chat 里发一条与 MCP 无关的普通对话比如让它回一个固定字符串。这条通了说明模型通道、Base URL、Key、模型 ID 四件事都对上了。这一步不通后面所有 MCP 的排查都是浪费。第二步切到 Agent 模式不是纯问答模式让它用自然语言触发工具例如在当前工作区里搜索包含FastMCP的文件。正常情况下你会看到一次search_files的工具调用记录以及返回的相对路径列表。第三步做一次边界验证搜一个肯定不存在的关键字确认返回的是NO_MATCH而不是报错或空字符串。这能区分工具没被调用和调用了但没命中。7. 常见错误与排查Cursor MCP 专属MCP 面板一直转圈或显示红点。九成是command或args的解释器/脚本路径不对。把mcp.json里那两条命令复制到终端原样执行一遍终端能起来的Cursor 才可能起来。服务是绿的但工具列表为空。检查mcp.tool()装饰的函数是否有类型注解和 docstring。FastMCP 靠这两样生成入参 schema缺了就会注册失败或生成空工具。模型对话通但 Agent 从不触发工具。确认当前是 Agent 模式有些会话上下文里已经带了一堆无关内容新开一个会话再试。另外检查是否在设置里关掉了 MCP 工具的使用权限。调用返回超时。大概率是SEARCH_ROOT指到了一个超大目录或者没配SKIP_DIRS一次扫描把整个依赖树读了一遍。把根目录收窄到源码目录并把结果上限降下来。Base URL 相关报错。回看第 3 节的两种错填多写/v1、粘进了带 UTM 的官网链接。改回https://taotoken.net/api再来一次。Key 泄露风险。mcp.json里如果放了 Key别提交到仓库模型 Key 属于 Cursor 的设置项跟 MCP 的env是两处别把 Key 写进env里当业务参数用。8. 接回课程这条链路之后能做什么走到这里你手上有了两样可复用的东西一条通过 TaoToken 配通的 Cursor 模型通道和一个能被 Agent 调用的本地文件搜索工具。模块三接下来讲的权限管理、降级机制、Token 预算控制都可以在这个最小组合上加比如给search_files加结果条数上限和目录白名单就是最朴素的权限控制搜索无命中时返回明确提示而不是抛异常就是最朴素的降级。后续要轮换或新建 Key直接在控制台管理https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentcursor-mcp-keysutm_campaignrewrite 。如果你打算长期在 Cursor 里跑这类 Agent 任务配好的这套通道更适合走 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcursor-mcp-coding-planutm_campaignrewrite 。接入细节和参数对照可以查文档https://taotoken.net/doc/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentcursor-mcp-docutm_campaignrewrite 。