1. 为什么 macOS 上跑 mcp-browser 总卡在 JSON-RPC 这一步如果你在 macOS 上折腾过 mcp-browser大概率遇到过这种场景DMG 装好了WKWebView 窗口也弹出来了Settings 里能看到 8833 端口和那串 Bearer Token但 MCP 客户端一发initialize就报 401或者干脆连接被拒。问题往往不在浏览器本身而在「统一 Key 通道」和「JSON-RPC 握手」这两层没对齐。mcp-browser 的本质是一个原生 macOS 浏览器它把自己包装成 MCP Server通过本地 HTTP 传输暴露工具能力。AI 代理调用的不是某个云 API而是你本机 127.0.0.1:8833 上的 JSON-RPC 端点。这意味着两件事第一认证走的是每次启动生成的 Bearer Token不是固定密钥第二所有工具调用navigate、click、eval_js、screenshot都封装成 JSON-RPC 的tools/call请求。那 TaoToken 在这里扮演什么角色它提供统一 Key 和 API 通道让你不用在多个 MCP 客户端里反复填不同的 base_url 和 token。你可以把 TaoToken 理解成一个「凭证中转层」mcp-browser 负责浏览器操作TaoToken 负责把模型侧和工具侧的鉴权统一起来。这样你在 Claude Desktop、Codex 或者自建的 Agent 框架里只需要维护一份 Key 配置。这篇面向的是需要在 WKWebView 场景里跑通完整 JSON-RPC 链路的开发者。我会给出 config.toml 和 settings.json 的可复制骨架然后带你发一次真实的 JSON-RPC 请求确认 MCP 服务连通。适合已经装好 mcp-browser、但卡在客户端配置或调试环节的人。2. TaoToken 统一 Key 的前置准备在动 config.toml 之前先把 TaoToken 这边的凭证拿到手。访问 https://taotoken.net/api 进入控制台在 API Keys 页面创建一个新 Key。这个 Key 的作用是让模型侧请求和 MCP 工具调用共享同一套鉴权体系避免你在每个客户端里重复配置。创建完 Key 后你需要确认两件事一是 Key 的权限范围是否包含 MCP 工具调用二是 API 通道的 base_url 是否指向https://taotoken.net/api。TaoToken 的模型对话入口在 https://taotoken.net/api 下的 chat 端点而 MCP 相关的配置则通过 Coding Plan 或 Console 里的接入文档来获取。如果你打算长期跑编码类 Agent建议直接看 Coding Plan 的配置说明它会把 MCP Server 的注册和 Key 绑定一起处理掉。对于只是临时调试 mcp-browser 的场景用 API Keys 页面生成的 Key 就够了。这里有个容易踩的坑mcp-browser 自己的 Bearer Token 和 TaoToken 的 API Key 是两套东西。前者是本地 8833 端口的准入凭证后者是模型侧调用 TaoToken 通道的凭证。很多人在 settings.json 里把两者搞混结果 JSON-RPC 请求带着 TaoToken 的 Key 去访问 127.0.0.1:8833自然被拒。正确的做法是mcp-browser 的配置里填它自己生成的 TokenTaoToken 的 Key 填在模型客户端的 provider 配置里。3. 可复制的 config.toml 与 settings.json 骨架先看 config.toml。这个文件通常放在你的 MCP 客户端或 Agent 框架的配置目录下用来声明 mcp-browser 这个 Server 的传输方式和认证信息。# config.toml - mcp-browser MCP Server 配置骨架 [mcp_servers.mcp-browser] transport http url http://127.0.0.1:8833/mcp headers { Authorization Bearer mcp-browser-local-token } # TaoToken 统一 Key 通道模型侧 [providers.taotoken] base_url https://taotoken.net/api api_key your-taotoken-api-key model claude-sonnet-4-20250514注意mcp-browser-local-token要替换成你在 mcp-browser 的 Settings → Connection 里复制的那串 Token。这个 Token 每次重启应用都会重新生成所以如果你频繁重启建议在 Settings 里点一次「重新生成」后立刻更新配置文件或者干脆用应用内的 MCP Clients 自动配置功能。再看 settings.json。如果你用的是 Claude Desktop 或类似的客户端配置结构会不一样{ mcpServers: { mcp-browser: { transport: http, url: http://127.0.0.1:8833/mcp, headers: { Authorization: Bearer mcp-browser-local-token } } }, providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: your-taotoken-api-key } } }两个文件的核心区别在于config.toml 用 TOML 的表结构settings.json 用嵌套对象。但transport、url、headers.Authorization这三个字段是必须对齐的。我实测下来最容易出错的是 url 末尾的/mcp路径——漏掉它就会变成 404而不是 401报错信息会误导你以为 Token 有问题。另外mcp-browser 的 Settings → MCP Clients 标签页可以自动为已知客户端写入配置。如果你不想手动改文件可以直接在那里点一下对应客户端的按钮它会帮你把 url 和 Token 填好。但自动配置不会帮你填 TaoToken 的 Key那部分还是得手动加到 provider 配置里。4. 发一次 JSON-RPC 请求验证连通配置写好后别急着在客户端里点「连接」。先用 curl 直接打一次 JSON-RPC确认 8833 端口和 Token 都是通的。这一步能帮你把「MCP 服务本身的问题」和「客户端配置的问题」分开。先确认 mcp-browser 正在运行并且 Settings → Connection 里显示端口是 8833。然后打开终端发一个initialize请求curl -s -X POST http://127.0.0.1:8833/mcp \ -H Content-Type: application/json \ -H Authorization: Bearer mcp-browser-local-token \ -d { jsonrpc: 2.0, id: 1, method: initialize, params: { protocolVersion: 2024-11-05, capabilities: {}, clientInfo: { name: curl-test, version: 1.0.0 } } }预期返回是一个 JSON-RPC 响应包含result.serverInfo和result.capabilities。如果返回 401说明 Token 不对或者没带 Authorization 头如果返回 404说明 url 路径写错了检查是不是漏了/mcp如果连接被拒说明 mcp-browser 没启动或者端口不是 8833。initialize通过后再发一个tools/list请求确认工具注册正常curl -s -X POST http://127.0.0.1:8833/mcp \ -H Content-Type: application/json \ -H Authorization: Bearer mcp-browser-local-token \ -d { jsonrpc: 2.0, id: 2, method: tools/list, params: {} }你应该能看到navigate、click、eval_js、screenshot等工具的名称和参数 schema。这一步返回正常说明 MCP 服务端的 JSON-RPC 链路已经通了。最后做一次真实的工具调用用navigate打开一个页面curl -s -X POST http://127.0.0.1:8833/mcp \ -H Content-Type: application/json \ -H Authorization: Bearer mcp-browser-local-token \ -d { jsonrpc: 2.0, id: 3, method: tools/call, params: { name: navigate, arguments: { url: https://example.com } } }如果 WKWebView 窗口里页面跳转了并且返回结果里包含当前 URL 和标题那整条链路就打通了。这时候再回到你的 MCP 客户端里点连接成功率会高很多。5. 本篇常见错误排查401 Unauthorized最常见的原因是 Token 过期或复制时带了空格。mcp-browser 的 Token 每次启动重新生成如果你重启过应用但没更新配置就会 401。去 Settings → Connection 重新复制一次注意不要漏掉Bearer前缀和后面的空格。404 Not Foundurl 路径问题。确认是http://127.0.0.1:8833/mcp不是http://127.0.0.1:8833/或http://127.0.0.1:8833/mcp/。末尾多一个斜杠也可能导致路由不匹配。Connection refusedmcp-browser 没启动或者端口被占用。检查应用是否在运行Settings → Connection 里显示的端口是不是 8833。如果端口被其他进程占了可以在设置里改端口然后同步更新 config.toml 和 settings.json。JSON-RPC 返回 -32600 Invalid Request请求体不是合法的 JSON-RPC 2.0 格式。检查jsonrpc字段是不是2.0id是不是数字或字符串method和params是否配对。用 curl 时注意单引号和双引号的嵌套建议把请求体写到文件里再用-d request.json。tools/call 返回工具不存在tools/list里有的工具才能调用。如果你调的是screenshot但返回 method not found可能是 mcp-browser 版本较旧或者该工具在当前窗口状态下不可用。先跑一次tools/list确认工具名拼写。WKWebView 页面不跳转但返回成功这种情况通常是多窗口路由问题。mcp-browser 的 MCP 协调器只路由到最近聚焦的窗口如果你开了多个窗口工具调用可能作用在了另一个窗口上。关掉多余窗口只留一个再试。TaoToken 侧报鉴权失败检查 API Key 是否从 https://taotoken.net/api 的控制台正确复制base_url 是否指向https://taotoken.net/api。如果用的是 Coding Plan确认 Key 的权限范围包含你要调用的模型。6. 接入文档与后续调试入口JSON-RPC 链路跑通之后下一步通常是把 mcp-browser 接到实际的 Agent 工作流里。如果你需要重新生成或管理 TaoToken 的 Key直接去 API Keys 页面操作接入文档里有完整的 MCP Server 注册说明和参数对照表适合在换客户端时快速查字段。调试模型对话行为时可以用模型对话入口发几条测试消息确认模型侧能正确识别 mcp-browser 暴露的工具。如果你打算长期跑编码类 AgentCoding Plan 的配置会把 MCP 注册和 Key 绑定一起处理省去手动改 config.toml 的步骤。mcp-browser 的操作日志在 Settings 里可以查看每次工具调用的参数、结果摘要和时间都有记录。调试 JSON-RPC 时这个日志比客户端侧的报错信息更有用——它能告诉你请求到底有没有到达服务端以及服务端返回了什么。我习惯在 curl 验证通过后再去客户端里点连接这样出问题时能快速定位是传输层还是客户端配置层的问题。