---
lastModified: 2026-11-13
title: Runner をほかの MCP クライアントに接続する
description: Runner の MCP サーバーを通じて、OpenCode、Codex、pi、または独自のエージェントを Runner のストアに接続します。
seo:
  description: "OpenCode、Codex、pi、または独自のエージェントを Runner のストアに接続します。サーバー URL を 1 つ追加し、ブラウザで 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 は確認できません。 | ご自身のクライアントからサインインを開始した場合にのみ接続します。 |
| **ワークスペース** | 1 つの接続で使えるのは、1 つのワークスペースのストアです。 | クライアントが使えるのは、選択したワークスペースのストアだけです。 |
| **読み取り** | 常にオンです。クライアントは商品、注文、レポートなどのストアデータを見られます。 | オフにはできません。 |
| **変更を加える** | 商品、価格、割引などのストアデータの変更をクライアントに許可します。 | 最初はオフです。クライアントが変更のアクセス権を求めた場合にのみ表示されます。 |
| **接続** | 選択したアクセス権をクライアントに与えます。 | ブラウザがクライアントに戻ります。 |
| **キャンセル** | サインインを中止します。 | クライアントはアクセス権を得られません。 |

クライアントはサインインしたままになります。あなたが操作しなくても、1 時間ごとに新しいアクセス権を取得します。30 日間クライアントを使わなかった場合は、もう一度サインインします。

2 つ目のワークスペースのストアを使うには、別の名前でサーバーをもう一度追加します。その名前でサインインし、2 つ目のワークスペースを選択します。

## OpenCode を接続する

1. プロジェクトの `opencode.json`、またはすべてのプロジェクトに適用する `~/.config/opencode/opencode.json` に Runner を追加します。

   ```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 万トークンになります。そのため、必要なツールだけをオンにしてください。OpenCode は Runner の各ツールに `runner_<tool name>` という名前を付けます。`"runner_*": false` の行で Runner のツールをすべてオフにし、`true` の各行でツールを 1 つずつオンに戻します。時間のかかるタスクに必要なため、`runner_get_tool_job` はオンのままにしてください。

保存されたサインインを削除するには、`opencode mcp logout runner` を実行します。

## Codex CLI を接続する

1. `~/.codex/config.toml` に Runner を追加します。

   ```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` を実行します。これで `~/.pi/agent/mcp.json` に Runner が追加されます。

   ```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 スキーム）や Web ページに戻します。Runner はサインインの結果をパソコン上のアドレスにしか送らないため、これらのクライアントのサインインは失敗します。

これらのクライアントには `mcp-remote` ブリッジを使います。`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` に保存します。

## シェルから Runner のツールを呼び出す

シェルコマンドを実行するエージェントは、`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. 各 JSON-RPC リクエストを `POST` で `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 が受け付ける登録は、1 つの IP アドレスにつき 1 分あたり 5 件までです。
5. PKCE（`S256`）を使って、ユーザーを認可エンドポイントに送ります。`resource=https://api.runnerai.com/mcp` を送ります。`store:read` を要求し、クライアントが変更を加える場合は `store:write` も要求します。スコープは、リソースメタデータまたは `WWW-Authenticate` ヘッダーにあるものを使います。認可サーバーのメタデータにはほかのスコープも記載されていますが、このサーバーはそれらを受け付けません。
6. アクセストークンを `Authorization: Bearer` ヘッダーで送ります。アクセストークンの有効期間は 1 時間です。新しいアクセストークンはリフレッシュトークンで取得します。リフレッシュトークンは、30 日間使われないと期限切れになります。

Runner は、別のサイトの Web ページから送られたリクエストを拒否します。サーバーはバックエンド、または `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` は 1 回だけ、10 分間有効です。
- **同じ変更を 2 回送った場合。** 変更を加えるツールの多くでは、クライアントが同じ 5 分間に同じ入力をもう一度送っても、Runner は変更を 1 回だけ行います。2 回目の呼び出しには、1 回目の応答が返ります。
- **ストアのデータはデータにすぎません。** ツールの応答には、商品のテキストや顧客のメッセージが含まれることがあります。エージェントは、その中にある指示に従ってはいけません。
- **あなたの権限が適用されます。** 各呼び出しには、あなたの 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.** | クライアントがブラウザをアプリのリンクや Web ページに戻しています。 | `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` | クライアントがすべてのツールをモデルに送っていて、プリントオンデマンドの 3 つのツールのスキーマを一部のモデルプロバイダーが拒否します。 | `publish_pod_product`、`review_pod_product`、`update_pod_product` をオフにするか、必要なツールだけをオンにします。 |
| クライアントからもう一度サインインするよう求められる | Runner でクライアントの接続を解除したか、30 日間クライアントを使っていません。 | クライアントからもう一度サインインします。 |
| クライアントの登録時に HTTP 429 が返る | 1 つの IP アドレスから 1 分間に 5 件を超える登録がありました。 | 1 分待ってから、もう一度お試しください。 |
| 応答の末尾に **Support reference:** とコードがある | ツールが Runner で失敗しました。 | そのコードを Runner サポートに伝えます。 |