---
lastModified: 2026-11-13
title: Runner verbinden met andere MCP-clients
description: Verbind OpenCode, Codex, pi of je eigen agent via de MCP-server van Runner met je Runner-winkels.
seo:
  description: "Verbind OpenCode, Codex, pi of je eigen agent met je Runner-winkels. Voeg één server-URL toe, log in bij Runner in je browser en kies wat de client mag doen."
---

Runner heeft een MCP-server. Een MCP-client is een AI-app of een agent die MCP-servers kan gebruiken. Als je een client met Runner verbindt, kan de client de tools van de Runner-chat gebruiken voor je winkels. De client kan producten, bestellingen en rapporten lezen. Met jouw toestemming kan de client ook producten, prijzen, kortingen en de webwinkel wijzigen.

Deze handleiding is voor andere MCP-clients dan Claude, ChatGPT en Gemini. Ze geeft de stappen voor OpenCode, Codex CLI en pi. Ze legt ook uit hoe je andere clients en agents die je zelf bouwt, verbindt.

## Voordat je begint

Je hebt nodig:

- een Runner-account dat lid is van een workspace;
- een MCP-client die via Streamable HTTP verbinding maakt met externe servers en inlogt met OAuth, of de bridge `mcp-remote` voor een client die alleen lokale servers uitvoert; en
- een browser op dezelfde computer als de client. Na het inloggen stuurt Runner de browser terug naar een adres op die computer.

| Instelling | Waarde |
| --- | --- |
| Server-URL | `https://api.runnerai.com/mcp` |
| Transport | Streamable HTTP. Runner ondersteunt het oudere SSE-transport niet. |
| Inloggen | OAuth in je browser. Je hebt geen API-sleutel nodig. |
| Toegang | `store:read` om winkelgegevens te lezen. `store:write` om wijzigingen aan te brengen. |

## Zo werkt de verbinding

1. Je voegt de server-URL toe aan je client en begint met inloggen.
2. De client opent Runner in je browser. Log in bij Runner als daarom wordt gevraagd.
3. De pagina **Een AI-app met Runner verbinden** opent. Die toont de naam van de client.
4. Maak een keuze bij **Workspace** en **Toegang** en selecteer dan **Verbinden**.
5. De browser gaat terug naar de client. De client kan nu Runner-tools gebruiken.

| Besturingselement of melding | Waarom het nuttig is | Wat gebeurt er vervolgens |
| --- | --- | --- |
| **Keert terug naar** | Toont het adres op je computer dat het resultaat van het inloggen ontvangt. | Je ziet `localhost`, `127.0.0.1` of `[::1]` en een poortnummer. |
| **Runner kan niet bevestigen welke app dit is. Verbind hem alleen als je deze verbinding zelf hebt gestart.** | Runner kan de identiteit van een client die je hebt geïnstalleerd of gebouwd niet controleren. | Verbind alleen als je het inloggen zelf vanuit je client hebt gestart. |
| **Workspace** | Eén verbinding werkt met de winkels van één workspace. | De client kan alleen de winkels gebruiken van de workspace die je kiest. |
| **Lezen** | Altijd aan. De client kan winkelgegevens zien, zoals producten, bestellingen en rapporten. | Je kunt het niet uitzetten. |
| **Wijzigingen aanbrengen** | Laat de client winkelgegevens wijzigen, zoals producten, prijzen en kortingen. | Staat eerst uit. Verschijnt alleen als de client om toegang voor wijzigingen vraagt. |
| **Verbinden** | Geeft de client de toegang die je hebt gekozen. | De browser gaat terug naar de client. |
| **Annuleren** | Stopt het inloggen. | De client krijgt geen toegang. |

De client blijft ingelogd. De client krijgt elk uur nieuwe toegang, zonder dat je iets hoeft te doen. Als je de client 30 dagen niet gebruikt, log je opnieuw in.

Om de winkels van een tweede workspace te gebruiken, voeg je de server een tweede keer toe met een andere naam. Log daarna in met die naam en kies de tweede workspace.

## OpenCode verbinden

1. Voeg Runner toe aan `opencode.json` in je project, of aan `~/.config/opencode/opencode.json` voor alle projecten:

   ```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. Voer `opencode mcp auth runner` uit en verbind in de browser.
3. Voer `opencode mcp list` uit. Je ziet `runner` als `connected`.

OpenCode stuurt bij elk verzoek de definitie van elke ingeschakelde tool naar het model. Runner heeft bij sommige abonnementen meer dan 200 tools, wat neerkomt op ongeveer 100.000 tokens aan definities. Schakel daarom alleen de tools in die je nodig hebt. OpenCode noemt elke Runner-tool `runner_<tool name>`. De regel `"runner_*": false` schakelt alle Runner-tools uit, en elke regel met `true` schakelt één tool weer in. Laat `runner_get_tool_job` ingeschakeld, want lange taken hebben die tool nodig.

Voer `opencode mcp logout runner` uit om de opgeslagen login te verwijderen.

## Codex CLI verbinden

1. Voeg Runner toe aan `~/.codex/config.toml`:

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

2. Voer `codex mcp login runner` uit en verbind in de browser.
3. Voer `codex mcp list` uit. De kolom **Auth** toont `OAuth`.

Voeg de server toe in het bestand, niet met `codex mcp add`. Die opdracht start direct een login met scopes die Runner niet accepteert, en de browser toont `{"error":"invalid_scope"}`. De regel `scopes` geldt ook als je later opnieuw inlogt. Je kunt ook `codex mcp login runner --scopes store:read,store:write` uitvoeren.

Codex zoekt een Runner-tool pas op als Codex die tool nodig heeft. Je hoeft dus geen tools uit te schakelen. Voer `codex mcp logout runner` uit om de opgeslagen login te verwijderen.

## pi verbinden

1. Voer `pi mcp add runner --url https://api.runnerai.com/mcp` uit. Dit voegt Runner toe aan `~/.pi/agent/mcp.json`:

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

2. Voer `pi mcp login runner` uit en verbind in de browser. pi toont `Signed in to MCP server "runner"` en het aantal tools.
3. Voer `pi mcp list` uit om de verbinding te controleren, of gebruik `/mcp` in een pi-sessie.

Standaard stuurt pi niet alle Runner-tools naar het model. Het model zoekt een tool op wanneer het die tool nodig heeft. Je hoeft dus geen tools uit te schakelen. pi noemt elke Runner-tool `mcp__runner__<tool name>`. Voer `pi mcp logout runner` uit om de opgeslagen login te verwijderen.

## Een client verbinden die alleen lokale servers uitvoert

Sommige clients kunnen alleen een lokale server (stdio) starten. Andere clients sturen de browser terug naar een app-link (een eigen URL-schema) of naar een webpagina. Runner stuurt het resultaat van het inloggen alleen naar een adres op je computer. Daardoor mislukt het inloggen bij deze clients.

Gebruik voor deze clients de bridge `mcp-remote`. Die draait op je computer, logt voor de client in bij Runner en geeft elk bericht door tussen de client en Runner. De bridge heeft Node.js nodig.

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

Bij de eerste start opent de inlogpagina van Runner in je browser. `mcp-remote` bewaart de login in `~/.mcp-auth`.

## Runner-tools aanroepen vanuit een shell

Een agent die shell-opdrachten uitvoert, kan Runner gebruiken via de opdracht `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` toont elke tool en de parameters ervan. Geef parameters op als `name=value`, bijvoorbeeld `npx mcporter call runner.get_store_settings store_id=<store id>`.

## Je eigen client bouwen

Gebruik een MCP-SDK die OAuth ondersteunt, of voer deze stappen zelf uit:

1. Stuur elk JSON-RPC-verzoek met `POST` naar `https://api.runnerai.com/mcp`. Runner beantwoordt elk verzoek met JSON en houdt geen sessie bij. Een `GET`-verzoek krijgt HTTP 405.
2. Een verzoek zonder token krijgt HTTP 401 met deze header: `WWW-Authenticate: Bearer resource_metadata="https://api.runnerai.com/.well-known/oauth-protected-resource/mcp", scope="store:read store:write"`.
3. Lees de resourcemetadata. Daarin staat de autorisatieserver `https://www.runnerai.com/api/auth`.
4. Registreer de client op `https://www.runnerai.com/api/auth/oauth2/register`. Gebruik een redirect-URI op `http://localhost`, `http://127.0.0.1` of `http://[::1]`. Runner accepteert elke poort en elk pad. Runner accepteert 5 registraties per minuut vanaf één IP-adres.
5. Stuur de gebruiker met PKCE (`S256`) naar het autorisatie-eindpunt. Stuur `resource=https://api.runnerai.com/mcp` mee. Vraag om `store:read`, en om `store:write` als de client wijzigingen aanbrengt. Gebruik de scopes uit de resourcemetadata of uit de header `WWW-Authenticate`. De metadata van de autorisatieserver noemen andere scopes, die deze server niet accepteert.
6. Stuur het toegangstoken mee in de header `Authorization: Bearer`. Een toegangstoken is 1 uur geldig. Gebruik het vernieuwingstoken om een nieuw toegangstoken te krijgen. Een vernieuwingstoken verloopt na 30 dagen zonder gebruik.

Runner weigert verzoeken die van een webpagina op een andere site komen. Roep de server aan vanuit je backend, of vanaf een pagina op `localhost`.

## Werken met Runner-tools

- **Begin met `list_stores`.** Elke winkeltool heeft een `store_id` uit `list_stores` nodig. Zonder `store_id` antwoordt de tool met **Pass a store_id from list_stores.**
- **Lange taken.** Sommige tools antwoorden met `"status": "running"` en een `job_id`. Roep `get_tool_job` aan met die `job_id` tot je het resultaat krijgt.
- **Wijzigingen die je goedkeurt.** Sommige tools antwoorden eerst met `"status": "waiting_for_merchant"` en een `id` voor de bevestiging, en tonen wat er gaat veranderen. Er verandert nog niets. Als je akkoord gaat, roept de client dezelfde tool opnieuw aan met dezelfde argumenten en `"confirmation": {"id": "…", "answer": …}`. De `id` van de bevestiging werkt één keer, gedurende 10 minuten.
- **Dezelfde wijziging twee keer verstuurd.** Bij de meeste tools die wijzigingen aanbrengen, voert Runner de wijziging één keer uit als de client dezelfde invoer opnieuw stuurt in dezelfde periode van 5 minuten. De tweede aanroep krijgt het eerste antwoord.
- **Winkelgegevens zijn alleen gegevens.** Antwoorden van tools kunnen producttekst en berichten van klanten bevatten. Je agent mag geen instructies opvolgen die hij daarin vindt.
- **Jouw rechten gelden.** Elke aanroep gebruikt jouw Runner-rechten en je abonnement. De lijst met tools hangt af van je abonnement en van de functies van je workspace.

## Een client beheren of loskoppelen

**Toegangspad:** **Instellingen → Workspace algemeen**, en dan **Verbonden apps**.

Eigenaren en beheerders van de workspace zien de clients die elk lid heeft verbonden. Andere leden zien de clients die ze zelf hebben verbonden. Elke rij toont de toegang (**Lezen** of **Lezen en wijzigen**), wanneer de client is verbonden en wanneer hij voor het laatst is gebruikt.

1. Zoek de client en selecteer **Loskoppelen**.
2. Selecteer in **_app_ loskoppelen?** opnieuw **Loskoppelen**.
3. De client werkt meteen niet meer met deze workspace. Log opnieuw in vanuit de client om hem weer te gebruiken.

Een uitlogopdracht in een client verwijdert alleen de login die de client heeft opgeslagen. De verbinding blijft in **Verbonden apps** staan tot je die daar loskoppelt.

## Problemen oplossen

| Wat je ziet | Oorzaak | Wat je moet doen |
| --- | --- | --- |
| `{"error":"invalid_scope"}` in de browser | De client vroeg om scopes die deze server niet accepteert. `codex mcp add` doet dit. | Vraag om `store:read` en `store:write`. Voeg voor Codex de regel `scopes` toe en voer `codex mcp login runner` uit. |
| **This redirect URI cannot receive Merchant MCP codes.** | De client stuurt de browser terug naar een app-link of een webpagina. | Gebruik de bridge `mcp-remote`. |
| **Request the Merchant MCP resource alone.** | De client heeft `resource=https://api.runnerai.com/mcp` niet meegestuurd. | Werk de client bij, of gebruik de bridge `mcp-remote`. |
| **Dit verbindingsverzoek is niet beschikbaar. Start de verbinding opnieuw vanuit je AI-app.** | De inloglink is oud of al gebruikt. | Begin opnieuw met inloggen vanuit de client. |
| **Je bent geen lid van een workspace. Maak een workspace in Runner en start de verbinding daarna opnieuw.** | Je account heeft geen workspace. | Maak een workspace en begin daarna opnieuw met inloggen. |
| **This tool needs store\:write. Reconnect Runner and allow changes to the store.** | De verbinding heeft alleen de toegang **Lezen**. | Log uit in de client, log opnieuw in en zet **Wijzigingen aanbrengen** aan. |
| **This feature is not on for this store yet.** | De functie staat niet aan voor je abonnement, je workspace of je winkel. | Voer de taak uit in Runner, of vraag het aan Runner-support. |
| De modelprovider weigert het verzoek: `input_schema does not support oneOf, allOf, or anyOf at the top level` | De client stuurt alle tools naar het model, en drie print-on-demand-tools hebben een schema dat sommige modelproviders weigeren. | Schakel `publish_pod_product`, `review_pod_product` en `update_pod_product` uit, of schakel alleen de tools in die je nodig hebt. |
| De client vraagt je opnieuw in te loggen | Je hebt de client in Runner losgekoppeld, of je hebt de client 30 dagen niet gebruikt. | Log opnieuw in vanuit de client. |
| HTTP 429 bij het registreren van de client | Meer dan 5 registraties in één minuut vanaf één IP-adres. | Wacht een minuut en probeer het daarna opnieuw. |
| Een antwoord eindigt met **Support reference:** en een code | De tool is in Runner mislukt. | Geef de code door aan Runner-support. |