TinyFish 实战：Search Fetch Agent MCP 全场景接入 Demo 与 TaoToken 配置骨架

1. 为什么要把 TinyFish 的 Search/Fetch/Agent/MCP 串成一条链路TinyFish 是一套面向 Agent 的网页基础设施 API核心能力有四块Search 负责实时检索、Fetch 负责把网页正文抓成干净 Markdown、Agent 负责多步云浏览器操作、MCP 负责把前几项能力直接挂到 Claude Code / Codex 这类客户端上。它适合谁适合正在搭 RAG 管道、做竞品监控、或者给编码 Agent 补一个能上网能力的开发者。单看每个端点都不复杂但真正落地时麻烦往往不在单个接口而在统一 Key 通道 多客户端配置 链路验证这三件事上。我见过太多人卡在同一个地方Search 用一套 key、Fetch 又换一套、MCP 客户端里再填一遍最后排查问题时根本不知道是哪一层挂了。所以这篇不重复讲 TinyFish 是什么而是直接给一套可复制的接入骨架——用 TaoToken 做统一 Key/API 通道把 Search、Fetch、Agent、MCP 四个场景的配置一次性铺好再附上启动后调 Search 与 Fetch 各一次的验证动作确认 Agent 链路真的连通。你拿到配置就能改改完就能跑。下面所有配置里的 Key 占位符统一写成YOUR_TAOTOKEN_KEY你替换成自己的即可。整篇按问题场景 → 前置准备 → 可复制配置 → 验证 → 排障 → 分流的顺序走技术部分占大头注册那点事一笔带过。2. TaoToken 前置统一 Key 与 API 通道的准备TaoToken 在这里扮演的角色是统一入口——你不需要为每个端点单独维护一套鉴权而是通过一个 Key 走同一条 API 通道客户端配置里只填一次地址和 Key。这对多场景接入特别关键因为 MCP 客户端settings.json / config.toml里最怕的就是配置分散、改一处漏一处。先做两件前置动作。第一拿到 Key进入控制台创建 API Key创建后立刻复制保存页面关掉通常就不再完整展示。第二确认你要接入的客户端类型——Claude Code 走settings.jsonCodex 走config.toml两者配置结构不同下面会分别给骨架。关于地址记住两个官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基址https://taotoken.net/apiAPI 基址不带 UTM 参数配置里填这个就行。控制台和 Key 管理页建议提前开好方便边配边核对。这里不展开注册流程重点放在配置本身——因为真正让你少踩坑的是下面这些能直接粘贴的骨架。注意Key 只展示一次建议存到本地受保护的文件里比如~/.taotoken_env权限设 600所有 demo 从这读取避免污染全局环境变量也避免误提交到 Git。3. 可复制配置MCP 客户端 settings.json 与 config.toml 骨架这一节是全文的核心。MCP 接入的最大好处是零本地进程——不用起服务、不用写胶水代码客户端直接通过 URL 连过去。下面给 Claude Code 和 Codex 两套骨架你按自己用的客户端选一套。3.1 Claude Code 的 settings.json 骨架Claude Code 的 MCP 配置放在settings.json里结构是mcpServers对象。骨架如下{ mcpServers: { taotoken: { url: https://taotoken.net/api/mcp, headers: { Authorization: Bearer YOUR_TAOTOKEN_KEY } } } }字段说明url指向 TaoToken 的 MCP 接入点headers.Authorization用 Bearer 方式带 Key。如果你的客户端版本对 header 字段名有要求也可以写成X-API-Key具体以客户端文档为准但 Bearer 是通用性最好的写法。配好后Claude Code 启动时会自动加载这个 serverAgent 就能直接调用 Search 和 Fetch不需要你写任何调用代码。3.2 Codex 的 config.toml 骨架Codex 用 TOML 格式配置项是mcp_servers注意下划线。骨架[mcp_servers.taotoken] url https://taotoken.net/api/mcp bearer_token YOUR_TAOTOKEN_KEY如果你的 Codex 版本不支持bearer_token简写就展开成 header 形式[mcp_servers.taotoken] url https://taotoken.net/api/mcp [mcp_servers.taotoken.headers] Authorization Bearer YOUR_TAOTOKEN_KEY两种写法效果一致选客户端能识别的那种。改完保存重启客户端让配置生效。3.3 环境变量方式推荐用于脚本类调用如果你还要在 Python / Node 脚本里直接调 Search 和 Fetch建议统一用环境变量避免 Key 硬编码echo TAOTOKEN_API_KEYYOUR_TAOTOKEN_KEY ~/.taotoken_env chmod 600 ~/.taotoken_env export TAOTOKEN_API_KEY$(cut -d -f2 ~/.taotoken_env)之后所有脚本从TAOTOKEN_API_KEY读取MCP 配置和脚本调用共用同一个 Key排查问题时只需看一处。4. 验证请求启动后调 Search 与 Fetch 各一次配置写完不算完必须验证链路真的通。验证动作分两步先调 Search再调 Fetch两个都返回正常结果说明 Key 通道和 MCP 链路都没问题。4.1 验证 Search用 curl 直接打 Search 端点确认返回结构化结果export TAOTOKEN_API_KEY$(cut -d -f2 ~/.taotoken_env) curl -s https://taotoken.net/api/search?queryplaywrightbrowserautomationrecency_minutes43200 \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ | python3 -m json.tool | head -40参数含义query是搜索词空格用或 URL 编码recency_minutes43200表示最近 30 天的新鲜度窗口。返回结构大致是{ results: [ { title: ..., url: https://..., description: ..., rank: 1 } ] }看到results数组里有内容Search 这一环就通了。如果返回 401 或MISSING_API_KEY说明 Key 没传对回到第 3 节检查 header。4.2 验证 FetchFetch 是 POST 请求把 URL 列表丢进去拿回干净正文curl -s -X POST https://taotoken.net/api/fetch \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {urls: [https://example.com], format: markdown} \ | python3 -m json.tool | head -30返回里results[0].text就是剥离了导航栏、广告、脚本之后的正文 Markdown。批量抓取时一次最多 10 个 URL单个 URL 失败只会进errors[]不影响其他 URL 的结果——这是批量场景最实用的特性。4.3 验证 MCP 链路客户端侧如果你走的是 MCP 接入验证方式更简单在 Claude Code 或 Codex 里直接让 Agent 执行一次搜索比如帮我搜一下 playwright 2026 的最新动态。Agent 能返回搜索结果说明 MCP server 加载成功、Key 通道正常。这一步不需要你写代码但它是端到端链路是否真正连通的最终确认。提示Search 和 Fetch 各调一次都成功基本可以判定 Agent 链路连通。如果 MCP 侧调不通但 curl 能通问题多半在客户端配置格式而不是 Key 本身。5. 本篇常见错排查配置和验证过程中最容易撞上的几类问题我按现象、原因、处理列成表方便你对照现象原因处理MISSING_API_KEY/ 401Key 没传或为空检查 header 是否正确传入注意大小写HTTP 429超过 rate limit加time.sleep()控速Search 和 Fetch 限速不同MCP 客户端加载失败settings.json / config.toml 格式错用 JSON/TOML 校验器过一遍注意逗号和引号Fetch 返回errors: [{...}]某个 URL 抓取失败检查 URL 是否可访问、是否被反爬Agent 返回 timeout多步操作超时用流式模式看进度或拆分 goal脚本里 Key 读不到环境变量没 export确认~/.taotoken_env权限和读取路径几个补充点。第一request_id会出现在错误响应里遇到端点存在但业务逻辑拒绝的情况拿这个 id 去找支持排查最快。第二MCP 配置里如果同时写了url和错误的 header 字段名客户端可能静默忽略表现为配置看起来对但就是不通所以改完一定要重启客户端并实际调一次。第三批量 Fetch 时不要因为一个 URL 失败就重跑整批先看errors[]定位具体是哪个。我试过把 Search 和 Fetch 的 Key 分开配结果排障时来回切换浪费了不少时间统一到 TaoToken 一个 Key 之后问题定位快了很多。6. 接入方式怎么选API Keys、模型对话还是 Coding Plan链路验证通过之后接下来就是按场景选接入方式。三种分流路径对应不同需求如果你是在做排障或接入调试重点是 Key 和文档直接去 API Keys 管理页创建/轮换 Key再对照接入文档核对 header 和端点格式。文档里有各端点的完整参数说明比反复试错高效。如果你想先验证模型效果、确认 Search 和 Fetch 返回的数据质量再决定要不要深度集成走模型对话入口直接在对话里试调用不用先写代码。如果你是长期做编码或 Agent 开发需要稳定的调用配额和更完整的通道能力那就上 Coding Plan把 Search、Fetch、Agent 的调用统一纳入计划管理避免按次计费带来的成本波动。三条路径的入口分别是API Keys 与接入文档https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content选哪条取决于你现在卡在哪一步配置不通就先去 API Keys 和文档想先看效果就去模型对话准备长期跑就上 Coding Plan。配置骨架已经在第 3 节给全了剩下的就是替换 Key、重启客户端、调一次 Search 和 Fetch 确认链路——这三步做完TinyFish 的 Search/Fetch/Agent/MCP 全场景接入就算真正落地了。