1. web-ui 里的 MCP 到底能干什么，适合谁用

如果你正在用 web-ui 跑 Browser Use Agent 或者 Deep Research Agent，大概率会遇到一个尴尬：Agent 能点网页、能读页面，但一旦要读本地文件、查数据库、调内部接口，它就抓瞎了。MCP（Model Context Protocol）就是来解决这个问题的——它把外部工具以标准协议暴露出来，Agent 在任务执行过程中按需调用，相当于给只会浏览网页的 Agent 装上了"手"。

web-ui 这个项目对 MCP 的支持是完整落地的，不是画饼。核心实现分三块：src/utils/mcp_client.py用langchain_mcp_adapters做多服务器客户端，支持动态注册工具到 Controller；src/controller/custom_controller.py里的CustomController类持有mcp_client和mcp_server_config，通过setup_mcp_client()初始化、register_mcp_tools()把工具注册进 action registry；src/webui/components/agent_settings_tab.py则提供了 MCP 服务器 JSON 配置文件的上传入口，上传后自动解析并显示配置内容。

这套东西适合谁？三类人最直接：一是用 Cline MCP 已经攒了一堆 server 配置、想复用到 web-ui 的开发者；二是想让 Browser Use Agent 具备文件读写、数据库查询能力的自动化玩家；三是想把模型请求统一走 TaoToken、同时保留 MCP 工具链的团队。工具注册后的命名规则是mcp.{server_name}.{tool_name}，比如mcp.filesystem.read_file、mcp.database.query，Agent 在执行任务时会自动判断该调哪个。

需要提前说清楚一点：MCP 本身只负责"工具怎么暴露、怎么调用"，它不解决模型从哪来的问题。web-ui 里 Agent 的推理请求走的是 LLM 接口，这部分你可以指向 TaoToken 的 API，让模型调用和工具调用各司其职。下面就从配置到验证，把整条路径走一遍。

2. 接入前的准备：TaoToken 的 Base URL 与 Key 怎么拿

在动 MCP 配置之前，先把模型侧的入口理顺，否则你会遇到"工具注册成功了但 Agent 一跑就报错"的情况。web-ui 的 Agent 需要一个 OpenAI 兼容的 LLM 端点，TaoToken 提供的就是这个。

第一步，打开官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，注册并登录。登录后进入控制台，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，在这里你能看到账户余额、用量统计和模型列表。

第二步，创建 API Key。直接进 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，点新建，复制出来的 Key 形如sk-xxxxxxxx。这个 Key 只显示一次，建议先粘到本地临时文件里。

第三步，确认 Base URL。TaoToken 的 API 根地址是 https://taotoken.net/api ，注意这里不带任何查询参数，配置里填的就是这个。如果你用的是 OpenAI SDK 风格，通常还需要在末尾补/v1，具体取决于 web-ui 的读取方式——web-ui 的 LLM 配置一般要求填完整的base_url，我建议先填https://taotoken.net/api，如果报 404 再试https://taotoken.net/api/v1。

第四步，选模型。进模型对话页 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 可以先手动聊两句，确认 Key 有效、模型可用。把你想用的 Model ID 记下来，比如claude-sonnet-4-5或gpt-4o这类，后面配置里要填。

这里有个容易踩的坑：很多人把 MCP 配置和 LLM 配置混在一起填，结果两边都不通。记住分工——MCP 的 JSON 文件里写的是"工具服务器怎么启动"，TaoToken 的 Base URL 和 Key 写的是"模型请求发到哪"。两者在 web-ui 里是两个不同的配置位置。

如果你打算长期跑编码类或 Agent 类任务，可以顺手看一下 Coding Plan 页面 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite ，它对高频调用场景的额度安排更划算。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，遇到参数疑问可以对照查。

3. 可复制的 MCP 配置片段与 Base URL 改写步骤

这一节是整篇的核心，给你能直接抄的配置。web-ui 的 MCP 配置走的是 JSON 文件上传，格式和 Cline MCP 基本一致，所以从 Cline 迁移过来成本很低。

先建一个mcp_config.json，内容如下：

{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/workspace"], "env": {} }, "fetch": { "command": "uvx", "args": ["mcp-server-fetch"], "env": {} }, "sqlite": { "command": "uvx", "args": ["mcp-server-sqlite", "--db-path", "/Users/yourname/data/app.db"], "env": { "API_KEY": "your_tool_api_key" } } } }

几个参数说明：command是启动命令，npx和uvx分别对应 Node 和 Python 生态的 MCP server；args是传给 server 的参数，filesystem server 后面跟的是允许访问的目录，这个一定要写你真实存在的路径，写错了 server 起不来；env是环境变量，像数据库连接串、第三方 API Key 放这里。

如果你是从 Cline MCP 迁移，把 Cline 的cline_mcp_settings.json里的mcpServers整块复制过来即可，字段名完全兼容。唯一要注意的是路径——Cline 里可能用的是相对路径或 Windows 反斜杠，web-ui 跑在什么系统上就改成对应格式。

接下来是 Base URL 改写。web-ui 的 LLM 配置通常在环境变量或设置页里，找到类似OPENAI_BASE_URL、LLM_BASE_URL或base_url的字段，把它从原来的地址改成：

# 如果你用 TOML 或 .env 风格配置 OPENAI_API_KEY = "sk-你的TaoToken密钥" OPENAI_BASE_URL = "https://taotoken.net/api" OPENAI_MODEL = "claude-sonnet-4-5"

如果你用的是settings.json风格的配置（部分 web-ui 分支支持），写成：

{ "llm": { "provider": "openai", "base_url": "https://taotoken.net/api", "api_key": "sk-你的TaoToken密钥", "model": "claude-sonnet-4-5" } }

三件套必须齐全：Base URL、Key、Model ID。少任何一个都会在请求阶段报错。Model ID 一定要用 TaoToken 控制台里实际存在的名字，别凭记忆写。

配置改完后，把mcp_config.json通过 web-ui 的 Agent Settings 标签页上传。打开 http://127.0.0.1:7788 ，进 "Agent Settings"，找到 "MCP server json" 上传组件，选中文件，系统会自动解析并在界面上显示配置内容。如果解析失败，界面会报 JSON 格式错误，这时候用python -m json.tool mcp_config.json本地校验一下。

4. 验证请求：确认 MCP 工具真的注册成功

配置上传只是第一步，真正要确认的是"工具有没有被 Agent 用起来"。web-ui 在启动 Browser Use Agent 或 Deep Research Agent 时，会依次执行：读取 MCP 配置 → 连接 MCP 服务器 → 注册所有可用工具到 action registry。这个过程如果某一步失败，日志里会有痕迹。

先做连通性验证。启动 web-ui 后，观察控制台输出，正常情况你会看到类似Setting up MCP client...、Registered tool: mcp.filesystem.read_file这样的日志。如果只看到 setup 没有 registered，说明 server 连上了但工具没解析出来，多半是 server 版本和langchain_mcp_adapters==0.0.9不兼容。

再验证模型侧。在 web-ui 里发一个简单任务，比如"读取 workspace 目录下的 README.md 并总结"，如果 Agent 能调用mcp.filesystem.read_file并返回内容，说明 MCP 和 LLM 两条链路都通了。这一步同时验证了 TaoToken 的 Base URL 是否正确——因为 Agent 的推理请求走的就是它。

如果你想单独测模型端点，可以用 curl 直接打：

curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的TaoToken密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "ping"}] }'

返回里有choices字段就说明 Key 和 Base URL 没问题。如果返回 401，是 Key 错了；返回 404，是 Base URL 路径不对，试试加或去掉/v1。

MCP 工具调用成功的标志，是在 Agent 的执行日志里看到mcp.{server_name}.{tool_name}形式的调用记录。比如mcp.sqlite.query被触发，后面跟着 SQL 语句和返回结果。看到这个，你就可以放心把任务交给它了。

5. 常见报错排查：401、local proxy failed 与 reading choices

这一节按真实报错来对，遇到问题直接查。

401 Unauthorized。这个几乎都是 Key 的问题。检查三处：Key 有没有复制完整（sk-开头那串）、有没有多余空格、是不是在 TaoToken 控制台里被删了。还有一种情况是 Key 填对了但 Base URL 指向了别的服务，导致对方不认这个 Key。确认base_url是https://taotoken.net/api。

local proxy failed / connection refused。这个报错通常出现在 MCP server 启动阶段，不是模型侧。原因一般是command找不到——比如你写了npx但系统没装 Node，或者uvx没装 uv。先在终端手动跑一遍command + args，看能不能起来。能起来再回 web-ui 上传配置。另外 Windows 上npx有时要写成npx.cmd。

Error reading choices / choices 字段缺失。这是模型返回格式不对，根因多半是 Base URL 少了或多了/v1。TaoToken 的 OpenAI 兼容端点在/api/v1/chat/completions，如果你的客户端自动补/v1，那base_url就填https://taotoken.net/api；如果客户端不补，就填https://taotoken.net/api/v1。两种都试一下，哪个返回正常用哪个。

OAuth 相关报错。如果你接的 MCP server 需要 OAuth 授权（比如某些云服务），报错会提示 token 无效或未授权。这类 server 要在env里配好 access token，或者先单独完成授权流程再把 token 填进去。web-ui 本身不处理 OAuth 交互，它只负责把env传下去。

工具注册了但 Agent 不调用。检查工具命名是否符合mcp.{server_name}.{tool_name}格式，以及 Agent 的 prompt 里有没有明确提到要用工具。有时候 Agent 会"偷懒"直接用已有知识回答，你可以在任务描述里加一句"必须使用 mcp.filesystem 读取文件"来强制触发。

CC Switch / Cline MCP / Codex auth.json 迁移场景。如果你是从这些工具迁过来，记住三件套要一起改：Base URL 指向 TaoToken、Key 换成 TaoToken 的、Model ID 用 TaoToken 支持的。只改其中一两个，会出现"工具能连但模型报错"或"模型能跑但工具不注册"的割裂状态。

排查顺序建议：先 curl 测模型端点 → 再手动跑 MCP server 命令 → 最后看 web-ui 日志里工具注册情况。三步定位，比盲目改配置快得多。

6. 把模型入口固定到 TaoToken，让 MCP 链路稳定跑起来

MCP 配置和模型配置都理顺之后，剩下的事就是让它稳定运行。我的做法是把 TaoToken 的 Base URL 和 Key 写进 web-ui 的环境变量或配置文件，而不是每次在界面上手填——这样重启服务后配置不会丢，团队协作时也能统一。

具体操作：找到 web-ui 的.env或config文件，把OPENAI_BASE_URL、OPENAI_API_KEY、OPENAI_MODEL三个变量固定下来。MCP 的 JSON 文件则放在项目目录里，通过 Agent Settings 上传一次后，web-ui 会记住路径。如果你经常切换不同的 MCP server 组合，可以准备多个 JSON 文件，按任务类型上传不同的那份。

验证模型可用性的时候，模型对话页 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 是个方便的入口，不用起 web-ui 就能确认 Key 和模型状态。接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 里有各语言的调用示例，遇到 SDK 层面的问题可以对照。API Key 管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，建议给不同项目建不同的 Key，方便排查和回收。

最后说一个实测下来的经验：MCP server 的启动速度直接影响 Agent 的首次响应时间。npx和uvx首次运行会下载依赖，可能卡十几秒。如果你对响应速度敏感，可以提前在终端把 server 跑一遍预热，或者改用本地已安装的二进制路径替代npx。这一步做完，web-ui 侧的 MCP 就算是真正可用了。