Runner verbinden met andere MCP-clients

Verbind OpenCode, Codex, pi of je eigen agent via de MCP-server van Runner met je Runner-winkels.

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.

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.

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:

   {
     "$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:

   [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:

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

{
  "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:

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