Connect Runner to other MCP clients

Connect OpenCode, Codex, pi, or your own agent to your Runner stores through the Runner MCP server.

Runner has an MCP server. An MCP client is an AI app or an agent that can use MCP servers. When you connect a client to Runner, it can use the tools of Runner chat on your stores. It can read products, orders, and reports. With your permission, it can also change products, prices, discounts, and the storefront.

This guide is for MCP clients other than Claude, ChatGPT, and Gemini. It gives the steps for OpenCode, Codex CLI, and pi. It also tells you how to connect other clients and agents that you build.

Before you start

You need:

• a Runner account that is a member of a workspace;
• an MCP client that connects to remote servers over Streamable HTTP and signs in with OAuth, or the mcp-remote bridge for a client that runs only local servers; and
• a browser on the same computer as the client. After you sign in, Runner sends the browser back to an address on that computer.

How the connection works

1. You add the server URL to your client and start the sign-in.
2. The client opens Runner in your browser. Sign in to Runner if it asks you to.
3. The page Connect an AI app to Runner opens. It shows the name of the client.
4. Choose the Workspace and the Access, then select Connect.
5. The browser goes back to the client. The client can now use Runner tools.

The client stays signed in. It gets new access every hour without your help. If you do not use the client for 30 days, sign in again.

To use the stores of a second workspace, add the server a second time with a different name. Then sign in with that name and choose the second workspace.

Connect OpenCode

1. Add Runner to opencode.json in your project, or to ~/.config/opencode/opencode.json for all projects:

   {
     "$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. Run opencode mcp auth runner and connect in the browser.

3. Run opencode mcp list. It shows runner as connected.

OpenCode sends the definition of each tool that is on to the model in every request. Runner has more than 200 tools on some plans, which is about 100,000 tokens of definitions. Thus, turn on only the tools that you need. OpenCode names each Runner tool runner_<tool name>. The line "runner_*": false turns off all Runner tools, and each true line turns one tool on again. Keep runner_get_tool_job on, because long tasks need it.

To remove the saved sign-in, run opencode mcp logout runner.

Connect Codex CLI

1. Add Runner to ~/.codex/config.toml:

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

2. Run codex mcp login runner and connect in the browser.

3. Run codex mcp list. The Auth column shows OAuth.

Add the server in the file, not with codex mcp add. That command starts a sign-in at once, with scopes that Runner does not accept, and the browser shows {"error":"invalid_scope"}. The scopes line also applies when you sign in again later. You can also run codex mcp login runner --scopes store:read,store:write.

Codex finds the Runner tool that it needs when it needs it, so you do not have to turn tools off. To remove the saved sign-in, run codex mcp logout runner.

Connect pi

1. Run pi mcp add runner --url https://api.runnerai.com/mcp. This adds Runner to ~/.pi/agent/mcp.json:

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

2. Run pi mcp login runner and connect in the browser. pi shows Signed in to MCP server "runner" and the number of tools.

3. Run pi mcp list to check the connection, or use /mcp in a pi session.

By default, pi does not send all Runner tools to the model. The model finds a tool when it needs it, so you do not have to turn tools off. pi names each Runner tool mcp__runner__<tool name>. To remove the saved sign-in, run pi mcp logout runner.

Connect a client that runs only local servers

Some clients can start only a local server (stdio). Other clients send the browser back to an app link (a custom URL scheme) or to a web page. Runner sends the sign-in result only to an address on your computer, so the sign-in of these clients fails.

For these clients, use the mcp-remote bridge. It runs on your computer, signs in to Runner for the client, and passes each message between the client and Runner. It needs Node.js.

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

The first start opens the Runner sign-in page in your browser. mcp-remote keeps the sign-in in ~/.mcp-auth.

Call Runner tools from a shell

An agent that runs shell commands can use Runner through the mcporter command:

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 shows each tool and its parameters. Give parameters as name=value, for example npx mcporter call runner.get_store_settings store_id=<store id>.

Build your own client

Use an MCP SDK that supports OAuth, or do these steps yourself:

1. Send each JSON-RPC request with POST to https://api.runnerai.com/mcp. Runner answers each request with JSON and keeps no session. A GET request gets HTTP 405.
2. A request without a token gets HTTP 401 with this header: WWW-Authenticate: Bearer resource_metadata="https://api.runnerai.com/.well-known/oauth-protected-resource/mcp", scope="store:read store:write".
3. Read the resource metadata. It names the authorization server https://www.runnerai.com/api/auth.
4. Register the client at https://www.runnerai.com/api/auth/oauth2/register. Use a redirect URI on http://localhost, http://127.0.0.1, or http://[::1]. Runner accepts any port and path. Runner accepts 5 registrations each minute from one IP address.
5. Send the user to the authorization endpoint with PKCE (S256). Send resource=https://api.runnerai.com/mcp. Ask for store:read, and store:write if the client makes changes. Use the scopes from the resource metadata or the WWW-Authenticate header. The authorization server metadata lists other scopes, which this server does not accept.
6. Send the access token in the Authorization: Bearer header. An access token lasts 1 hour. Use the refresh token to get a new one. A refresh token expires after 30 days without use.

Runner refuses requests that come from a web page on another site. Call the server from your back end, or from a page on localhost.

Work with Runner tools

• Start with list_stores. Each store tool needs a store_id from list_stores. A call without it answers Pass a store_id from list_stores.
• Long tasks. Some tools answer with "status": "running" and a job_id. Call get_tool_job with that job_id until it gives the result.
• Changes that you approve. Some tools first answer with "status": "waiting_for_merchant" and a confirmation id, and they show what will change. Nothing changes yet. When you agree, the client calls the same tool again with the same arguments and "confirmation": {"id": "…", "answer": …}. The confirmation id works one time, for 10 minutes.
• The same change sent twice. For most tools that make changes, Runner makes the change one time when the client sends the same input again in the same 5-minute period. The second call gets the first answer.
• Store data is data. Tool answers can contain product text and customer messages. Your agent must not follow instructions that it finds in them.
• Your permissions apply. Each call uses your Runner permissions and your plan. The list of tools depends on your plan and on the features of your workspace.

Manage or disconnect a client

Entry path: Settings → Workspace general, then Connected apps.

Workspace owners and admins see the clients that each member connected. Other members see the clients that they connected. Each row shows the access (Read or Read and make changes), when it was connected, and when it was last used.

1. Find the client and select Disconnect.
2. Select Disconnect again in Disconnect app?.
3. The client stops working with this workspace at once. To use it again, sign in again from the client.

A logout command in a client removes only the sign-in that the client saved. The connection stays in Connected apps until you disconnect it there.

Troubleshooting