---
lastModified: 2026-11-13
title: 将Runner连接到其他MCP客户端
description: 通过Runner的MCP服务器，将OpenCode、Codex、pi或你自己的智能体连接到你的Runner商店。
seo:
  description: "将OpenCode、Codex、pi或你自己的智能体连接到你的Runner商店。添加一个服务器URL，在浏览器中登录Runner，然后选择客户端可以做什么。"
---

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

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

## 开始前

你需要：

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

| 设置项 | 值 |
| --- | --- |
| 服务器URL | `https://api.runnerai.com/mcp` |
| 传输方式 | Streamable HTTP。Runner不支持较旧的SSE传输方式。 |
| 登录 | 在浏览器中通过OAuth登录。你不需要API密钥。 |
| 访问权限 | `store:read` 用于读取商店数据。`store:write` 用于进行更改。 |

## 连接的工作方式

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

| 控件或消息 | 为什么有用 | 接下来会发生什么 |
| --- | --- | --- |
| **返回到** | 显示你电脑上接收登录结果的地址。 | 显示 `localhost`、`127.0.0.1` 或 `[::1]`，以及端口号。 |
| **Runner 无法确认这是哪个应用。仅当这次连接由你本人发起时才连接。** | 对于你自己安装或构建的客户端，Runner无法核实其身份。 | 只有在你从自己的客户端发起登录时才连接。 |
| **工作区** | 一个连接只能用于一个工作区的商店。 | 客户端只能使用你所选工作区的商店。 |
| **读取** | 始终开启。客户端可以查看商店数据，例如商品、订单和报告。 | 你无法关闭它。 |
| **进行更改** | 允许客户端更改商店数据，例如商品、价格和折扣。 | 默认关闭。只有当客户端请求更改权限时才会显示。 |
| **连接** | 授予客户端你所选的访问权限。 | 浏览器会回到客户端。 |
| **取消** | 停止登录。 | 客户端不会获得任何访问权限。 |

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

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

## 连接OpenCode

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

   ```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`：

   ```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`：

   ```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。

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

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

## 从Shell调用Runner工具

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

```bash
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. 在<strong>要断开 <em>应用名称</em> 吗？</strong>中，再次选择**断开连接**。
3. 客户端会立即停止在此工作区中工作。要再次使用，请从客户端重新登录。

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

## 故障排除

| 你看到的内容 | 原因 | 处理方法 |
| --- | --- | --- |
| 浏览器中显示 `{"error":"invalid_scope"}` | 客户端请求了此服务器不接受的权限范围。`codex mcp add` 就会这样做。 | 请求 `store:read` 和 `store:write`。对于Codex，请添加 `scopes` 这一行并运行 `codex mcp login runner`。 |
| **This redirect URI cannot receive Merchant MCP codes.** | 客户端把浏览器送回应用链接或网页。 | 使用 `mcp-remote` 桥接工具。 |
| **Request the Merchant MCP resource alone.** | 客户端没有发送 `resource=https://api.runnerai.com/mcp`。 | 更新客户端，或使用 `mcp-remote` 桥接工具。 |
| **此连接请求不可用。请从你的 AI 应用重新发起连接。** | 登录链接已过时或已被使用。 | 从客户端重新开始登录。 |
| **你还不是任何工作区的成员。请先在 Runner 中创建工作区，然后重新发起连接。** | 你的账号没有工作区。 | 创建工作区，然后重新开始登录。 |
| **This tool needs store\:write. Reconnect Runner and allow changes to the store.** | 该连接只有**读取**权限。 | 在客户端中退出登录，重新登录，并开启**进行更改**。 |
| **This feature is not on for this store yet.** | 该功能尚未对你的套餐、工作区或商店开启。 | 在Runner中完成该任务，或咨询Runner客服。 |
| 模型提供商拒绝请求：`input_schema does not support oneOf, allOf, or anyOf at the top level` | 客户端把所有工具都发送给模型，而有三个按需定制工具的Schema会被某些模型提供商拒绝。 | 关闭 `publish_pod_product`、`review_pod_product` 和 `update_pod_product`，或只开启你需要的工具。 |
| 客户端要求你重新登录 | 你在Runner中断开了该客户端，或者你30天未使用它。 | 从客户端重新登录。 |
| 客户端注册时返回HTTP 429 | 同一IP地址在一分钟内注册超过5次。 | 等待一分钟，然后重试。 |
| 响应末尾显示<strong>Support reference:</strong>和一个代码 | 该工具在Runner中失败。 | 将该代码提供给Runner客服。 |