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
-
Run this command. Codex starts the sign-in at once.
codex mcp add runner --url https://api.runnerai.com/mcp -
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.
-
Run
codex mcp list. The Auth column showsOAuth. -
Ask Codex about your store, for example “Which of my Runner stores are published?” It calls
list_storesfirst.
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.
-
Add Runner to
opencode.jsonin your project, or to~/.config/opencode/opencode.jsonfor 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 } } -
Run
opencode mcp auth runnerand connect in the browser. -
Run
opencode mcp list. It showsrunnerasconnected.
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.
-
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" } } } -
Run
pi mcp login runnerand connect in the browser. pi showsSigned in to MCP server "runner"and the number of tools. -
Run
pi mcp listto check the connection, or use/mcpin 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_storesmcporter 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
- All tools: what each tool does and how to call it.
- Long jobs and confirmations: how a client works with tools that run long or ask before they change data.
- Manage or disconnect a client: see and remove connected clients in Runner settings.