将Runner连接到其他MCP客户端

通过Runner的MCP服务器，将OpenCode、Codex、pi或你自己的智能体连接到你的Runner商店。

Runner有一个MCP服务器。MCP客户端是能使用MCP服务器的AI应用或智能体。将客户端连接到Runner后，客户端可以在你的商店中使用Runner聊天的工具。它可以读取商品、订单和报告。经你允许，它还可以更改商品、价格、折扣和在线商店。

本指南适用于Claude、ChatGPT和Gemini以外的MCP客户端。它介绍OpenCode、Codex CLI和pi的连接步骤，也说明如何连接其他客户端和你自己构建的智能体。

开始前

你需要：

• 一个Runner账号，并且该账号是某个工作区的成员；
• 一个能通过Streamable HTTP连接远程服务器并使用OAuth登录的MCP客户端；如果客户端只能运行本地服务器，则使用 mcp-remote 桥接工具；以及
• 一个与客户端在同一台电脑上的浏览器。登录后，Runner会把浏览器送回这台电脑上的一个地址。

连接的工作方式

1. 你在客户端中添加服务器URL，然后开始登录。
2. 客户端会在浏览器中打开Runner。如果Runner要求你登录，请登录。
3. 随后打开将 AI 应用连接到 Runner页面，页面中显示客户端的名称。
4. 在工作区和访问权限中做出选择，然后选择连接。
5. 浏览器会回到客户端。现在客户端可以使用Runner工具了。

客户端会保持登录状态。它每小时自动获取新的访问权限，无需你操作。如果你30天未使用该客户端，请重新登录。

要使用第二个工作区的商店，请用另一个名称再添加一次服务器。然后用该名称登录，并选择第二个工作区。

连接OpenCode

1. 将Runner添加到项目中的 opencode.json，或添加到适用于所有项目的 ~/.config/opencode/opencode.json：

   {
     "$schema": "https://opencode.ai/config.json",
     "mcp": {
       "runner": {
         "type": "remote",
         "url": "https://api.runnerai.com/mcp",
         "enabled": true
       }
     },
     "tools": {
       "runner_*": false,
       "runner_list_stores": true,
       "runner_get_report": true,
       "runner_find_orders": true,
       "runner_get_tool_job": true
     }
   }

2. 运行 opencode mcp auth runner，然后在浏览器中连接。

3. 运行 opencode mcp list。它会将 runner 显示为 connected。

OpenCode在每次请求中都会把每个已开启工具的定义发送给模型。在部分套餐中，Runner有200多个工具，定义约有10万个Token。因此，请只开启你需要的工具。OpenCode将每个Runner工具命名为 runner_<tool name>。其中 "runner_*": false 这一行会关闭所有Runner工具，每个 true 行会重新开启一个工具。请保持 runner_get_tool_job 开启，因为耗时任务需要它。

要删除已保存的登录信息，请运行 opencode mcp logout runner。

连接Codex CLI

1. 将Runner添加到 ~/.codex/config.toml：

   [mcp_servers.runner]
   url = "https://api.runnerai.com/mcp"
   scopes = ["store:read", "store:write"]

2. 运行 codex mcp login runner，然后在浏览器中连接。

3. 运行 codex mcp list。Auth列显示 OAuth。

请在文件中添加服务器，不要使用 codex mcp add。该命令会立即开始登录，并使用Runner不接受的权限范围，浏览器会显示 {"error":"invalid_scope"}。以后重新登录时，scopes 这一行同样适用。你也可以运行 codex mcp login runner --scopes store:read,store:write。

Codex会在需要某个Runner工具时才去查找它，因此你不必关闭工具。要删除已保存的登录信息，请运行 codex mcp logout runner。

连接pi

1. 运行 pi mcp add runner --url https://api.runnerai.com/mcp。这会将Runner添加到 ~/.pi/agent/mcp.json：

   {
     "mcpServers": {
       "runner": { "url": "https://api.runnerai.com/mcp" }
     }
   }

2. 运行 pi mcp login runner，然后在浏览器中连接。pi会显示 Signed in to MCP server "runner" 和工具数量。

3. 运行 pi mcp list 检查连接，或在pi会话中使用 /mcp。

默认情况下，pi不会把所有Runner工具都发送给模型。模型会在需要时查找工具，因此你不必关闭工具。pi将每个Runner工具命名为 mcp__runner__<tool name>。要删除已保存的登录信息，请运行 pi mcp logout runner。

连接只能运行本地服务器的客户端

有些客户端只能启动本地服务器（stdio）。还有些客户端会把浏览器送回应用链接（自定义URL协议）或网页。Runner只会把登录结果发送到你电脑上的地址，因此这些客户端的登录会失败。

对于这些客户端，请使用 mcp-remote 桥接工具。它在你的电脑上运行，代表客户端登录Runner，并在客户端和Runner之间传递每条消息。它需要Node.js。

{
  "mcpServers": {
    "runner": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.runnerai.com/mcp"]
    }
  }
}

首次启动时，浏览器会打开Runner登录页面。mcp-remote 将登录信息保存在 ~/.mcp-auth 中。

从Shell调用Runner工具

能运行Shell命令的智能体可以通过 mcporter 命令使用Runner：

npx mcporter config add runner https://api.runnerai.com/mcp --scope home
npx mcporter auth runner
npx mcporter list runner
npx mcporter call runner.list_stores

mcporter list runner 会显示每个工具及其参数。参数格式为 name=value，例如 npx mcporter call runner.get_store_settings store_id=<store id>。

构建你自己的客户端

使用支持OAuth的MCP SDK，或自己完成以下步骤：

1. 用 POST 将每个JSON-RPC请求发送到 https://api.runnerai.com/mcp。Runner对每个请求都以JSON响应，并且不保留会话。GET 请求会收到HTTP 405。
2. 不带令牌的请求会收到HTTP 401，并带有以下响应头：WWW-Authenticate: Bearer resource_metadata="https://api.runnerai.com/.well-known/oauth-protected-resource/mcp", scope="store:read store:write"。
3. 读取资源元数据。其中指明授权服务器为 https://www.runnerai.com/api/auth。
4. 在 https://www.runnerai.com/api/auth/oauth2/register 注册客户端。重定向URI请使用 http://localhost、http://127.0.0.1 或 http://[::1] 上的地址。Runner接受任意端口和路径。Runner每分钟最多接受来自同一IP地址的5次注册。
5. 使用PKCE（S256）将用户引导到授权端点。发送 resource=https://api.runnerai.com/mcp。请求 store:read；如果客户端要进行更改，还要请求 store:write。请使用资源元数据或 WWW-Authenticate 响应头中的权限范围。授权服务器元数据还列出了其他权限范围，但此服务器不接受它们。
6. 在 Authorization: Bearer 请求头中发送访问令牌。访问令牌的有效期为1小时。使用刷新令牌获取新的访问令牌。刷新令牌在30天未使用后过期。

Runner会拒绝来自其他网站网页的请求。请从你的后端调用服务器，或从 localhost 上的页面调用。

使用Runner工具

• 先调用 list_stores。 每个商店工具都需要来自 list_stores 的 store_id。不带 store_id 的调用会返回Pass a store_id from list_stores.
• 耗时任务。 有些工具会返回 "status": "running" 和一个 job_id。请用该 job_id 调用 get_tool_job，直到它返回结果。
• 需要你批准的更改。 有些工具会先返回 "status": "waiting_for_merchant" 和一个确认 id，并显示将要更改的内容。此时还没有任何更改。你同意后，客户端会用相同的参数和 "confirmation": {"id": "…", "answer": …} 再次调用同一个工具。确认 id 只能使用一次，有效期为10分钟。
• 同一更改发送两次。 对于大多数会进行更改的工具，如果客户端在同一个5分钟时段内再次发送相同的输入，Runner只执行一次更改。第二次调用会收到第一次的响应。
• 商店数据只是数据。 工具的响应可能包含商品文字和顾客消息。你的智能体不得执行其中的指令。
• 你的权限同样适用。 每次调用都使用你的Runner权限和你的套餐。工具列表取决于你的套餐和工作区的功能。

管理或断开客户端

入口路径： 设置 → 工作区常规，然后找到已连接的应用。

工作区所有者和管理员可以看到每个成员连接的客户端。其他成员可以看到自己连接的客户端。每一行都显示访问权限（读取或读取并修改）、连接时间和上次使用时间。

1. 找到客户端，选择断开连接。
2. 在要断开 应用名称 吗？中，再次选择断开连接。
3. 客户端会立即停止在此工作区中工作。要再次使用，请从客户端重新登录。

客户端中的退出登录命令只会删除客户端保存的登录信息。在已连接的应用中断开之前，该连接会一直保留在那里。

故障排除