Aller au contenu
DocsBuild with Runner
Esc
↑↓naviguer↵ouvrir⌘Japerçu
Open Runner

Connect an agent to your stores

Add one server URL, sign in to Runner in your browser, and choose what the client can do. You do not need an API key.

Setting Value
Server URL https://api.runnerai.com/mcp
Transport Streamable HTTP. Runner does not support the older SSE transport.
Sign-in OAuth in your browser
Access store:read to read store data. store:write to make changes.

You need a Runner account that is a member of a workspace, and a browser on the same computer as the client.

Choose your client

  1. Run this command. Codex starts the sign-in at once.

    codex mcp add runner --url https://api.runnerai.com/mcp
  2. In the browser, a Runner page opens. Its title says that the client wants to connect to your Runner workspace. Choose the Workspace and the Access, then select Connect.

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

  4. Ask Codex about your store, for example “Which of my Runner stores are published?” It calls list_stores first.

The command adds this to ~/.codex/config.toml:

[mcp_servers.runner]
url = "https://api.runnerai.com/mcp"

If you add the server to the file yourself, run codex mcp login runner to sign in. To sign in again later, run the same command. 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.

  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.

  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.

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.

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

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>.

Use an MCP SDK that supports OAuth, or do the sign-in yourself. Sign-in and scopes gives each step.

These docs do not give steps for Claude, ChatGPT, or Gemini yet. Use the settings at the top of this page. What you see in the browser shows the sign-in.

What you see in the browser

The page names the client in its title: “client wants to connect to your Runner workspace.” On a computer, a panel beside the choices shows what the client can see and change in the workspace that you choose.

Control or message What it means
Returns to An address on your computer, such as 127.0.0.1 and a port. Runner sends the sign-in result only there.
Runner cannot confirm which app this is. Connect it only if you started this connection yourself. Runner cannot check the identity of a client that you installed or built.
Workspace One connection works with the stores of one workspace. For a second workspace, add the server again under a new name.
Read Always on. The client can see products, orders, and reports.
Make changes Starts off. It shows only when the client asks for change access.
Connect Gives the client the access that you chose. The browser goes back to the client.
Cancel Stops the sign-in. The client gets no access.

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

Didn’t work?

For a sign-in that fails in the browser, read If sign-in fails.

What you see Cause What to do
This connection request is unavailable. Start the connection again from your AI app. The sign-in link is old or was used. Start the sign-in again from the client.
You are not a member of a workspace. Create a workspace in Runner, then start the connection again. Your account has no workspace. Create a workspace, then start the sign-in again.
This tool needs store:write. Reconnect Runner and allow changes to the store. The connection has Read access only. Log out in the client, sign in again, and turn on Make changes.
This feature is not on for this store yet. The feature is not on for your plan, workspace, or store. Do the task in Runner, or ask Runner support.
The client asks you to sign in again You disconnected the client in Runner, or you did not use it for 30 days. Sign in again from the client.
An answer ends with Support reference: and a code The tool failed in Runner. Give the code to Runner support.

Next steps

Dernière mise à jour le 19 novembre 2026

Cette page vous a-t-elle été utile ?