---
lastModified: 2026-11-19
title: Connect an agent to your stores
description: 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.
sidebar:
  label: 'Quickstart: connect an agent'
---

| 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

**Codex CLI**

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

   ```bash
   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`:

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

**OpenCode**

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

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

**pi**

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

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

**Local-only client**

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.

```json
{
  "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`.

**A shell**

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

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

**My own agent**

Use an MCP SDK that supports OAuth, or do the sign-in yourself. [Sign-in and scopes](/en/build/sign-in-and-scopes) gives each step.

**Claude, ChatGPT, Gemini**

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](#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? [#troubleshooting]

For a sign-in that fails in the browser, read [If sign-in fails](/en/build/sign-in-and-scopes#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](/en/build/tools): what each tool does and how to call it.
- [Long jobs and confirmations](/en/build/tool-calls): how a client works with tools that run long or ask before they change data.
- [Manage or disconnect a client](/en/guides/apps-and-integrations/mcp-clients#manage-or-disconnect-a-client): see and remove connected clients in Runner settings.
