企业官网建设流程全解析

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 的配置里填它自己生成的 Token，TaoToken 的 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 Found：url 路径问题。确认是http://127.0.0.1:8833/mcp，不是http://127.0.0.1:8833/或http://127.0.0.1:8833/mcp/。末尾多一个斜杠也可能导致路由不匹配。

Connection refused：mcp-browser 没启动，或者端口被占用。检查应用是否在运行，Settings → Connection 里显示的端口是不是 8833。如果端口被其他进程占了，可以在设置里改端口，然后同步更新 config.toml 和 settings.json。

JSON-RPC 返回 -32600 Invalid Request：请求体不是合法的 JSON-RPC 2.0 格式。检查jsonrpc字段是不是"2.0"，id是不是数字或字符串，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 暴露的工具。如果你打算长期跑编码类 Agent，Coding Plan 的配置会把 MCP 注册和 Key 绑定一起处理，省去手动改 config.toml 的步骤。

mcp-browser 的操作日志在 Settings 里可以查看，每次工具调用的参数、结果摘要和时间都有记录。调试 JSON-RPC 时，这个日志比客户端侧的报错信息更有用——它能告诉你请求到底有没有到达服务端，以及服务端返回了什么。我习惯在 curl 验证通过后，再去客户端里点连接，这样出问题时能快速定位是传输层还是客户端配置层的问题。