---
lastModified: 2026-11-13
title: Runner mit anderen MCP-Clients verbinden
description: Verbinden Sie OpenCode, Codex, pi oder Ihren eigenen Agenten über den MCP-Server von Runner mit Ihren Runner-Shops.
seo:
  description: "Verbinden Sie OpenCode, Codex, pi oder Ihren eigenen Agenten mit Ihren Runner-Shops. Fügen Sie eine Server-URL hinzu, melden Sie sich im Browser bei Runner an und wählen Sie, was der Client tun darf."
---

Runner hat einen MCP-Server. Ein MCP-Client ist eine KI-App oder ein Agent, der MCP-Server verwenden kann. Wenn Sie einen Client mit Runner verbinden, kann er die Tools des Runner-Chats für Ihre Shops verwenden. Er kann Produkte, Bestellungen und Berichte lesen. Mit Ihrer Erlaubnis kann er auch Produkte, Preise, Rabatte und den Onlineshop ändern.

Diese Anleitung gilt für andere MCP-Clients als Claude, ChatGPT und Gemini. Sie enthält die Schritte für OpenCode, Codex CLI und pi. Außerdem erfahren Sie, wie Sie andere Clients und selbst gebaute Agenten verbinden.

## Bevor Sie beginnen

Sie benötigen:

- ein Runner-Konto, das Mitglied eines Workspaces ist;
- einen MCP-Client, der sich über Streamable HTTP mit Remote-Servern verbindet und sich mit OAuth anmeldet, oder die Bridge `mcp-remote` für einen Client, der nur lokale Server ausführt; und
- einen Browser auf demselben Computer wie der Client. Nach der Anmeldung leitet Runner den Browser an eine Adresse auf diesem Computer zurück.

| Einstellung | Wert |
| --- | --- |
| Server-URL | `https://api.runnerai.com/mcp` |
| Transport | Streamable HTTP. Runner unterstützt den älteren SSE-Transport nicht. |
| Anmeldung | OAuth im Browser. Sie benötigen keinen API-Schlüssel. |
| Zugriff | `store:read` zum Lesen von Shopdaten. `store:write` für Änderungen. |

## So funktioniert die Verbindung

1. Sie fügen die Server-URL in Ihrem Client hinzu und starten die Anmeldung.
2. Der Client öffnet Runner in Ihrem Browser. Melden Sie sich bei Runner an, wenn Sie dazu aufgefordert werden.
3. Die Seite **KI-App mit Runner verbinden** öffnet sich. Sie zeigt den Namen des Clients.
4. Treffen Sie Ihre Auswahl unter **Workspace** und **Zugriff** und wählen Sie dann **Verbinden**.
5. Der Browser kehrt zum Client zurück. Der Client kann jetzt Runner-Tools verwenden.

| Steuerelement oder Meldung | Warum es nützlich ist | Was passiert danach |
| --- | --- | --- |
| **Zurück zu** | Zeigt die Adresse auf Ihrem Computer, die das Ergebnis der Anmeldung erhält. | Dort steht `localhost`, `127.0.0.1` oder `[::1]` mit einer Portnummer. |
| **Runner kann nicht bestätigen, um welche App es sich handelt. Verbinden Sie sie nur, wenn Sie die Verbindung selbst gestartet haben.** | Runner kann die Identität eines Clients, den Sie installiert oder gebaut haben, nicht prüfen. | Verbinden Sie nur, wenn Sie die Anmeldung selbst in Ihrem Client gestartet haben. |
| **Workspace** | Eine Verbindung gilt für die Shops eines Workspaces. | Der Client kann nur die Shops des Workspaces verwenden, den Sie wählen. |
| **Lesen** | Immer aktiv. Der Client kann Shopdaten wie Produkte, Bestellungen und Berichte sehen. | Sie können es nicht ausschalten. |
| **Änderungen vornehmen** | Erlaubt dem Client, Shopdaten wie Produkte, Preise und Rabatte zu ändern. | Ist anfangs ausgeschaltet. Wird nur angezeigt, wenn der Client Zugriff für Änderungen anfordert. |
| **Verbinden** | Gibt dem Client den Zugriff, den Sie gewählt haben. | Der Browser kehrt zum Client zurück. |
| **Abbrechen** | Bricht die Anmeldung ab. | Der Client erhält keinen Zugriff. |

Der Client bleibt angemeldet. Er erhält jede Stunde neuen Zugriff, ohne dass Sie etwas tun müssen. Wenn Sie den Client 30 Tage lang nicht verwenden, melden Sie sich erneut an.

Um die Shops eines zweiten Workspaces zu verwenden, fügen Sie den Server ein zweites Mal unter einem anderen Namen hinzu. Melden Sie sich dann mit diesem Namen an und wählen Sie den zweiten Workspace.

## OpenCode verbinden

1. Fügen Sie Runner zu `opencode.json` in Ihrem Projekt hinzu oder zu `~/.config/opencode/opencode.json` für alle Projekte:

   ```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. Führen Sie `opencode mcp auth runner` aus und verbinden Sie im Browser.
3. Führen Sie `opencode mcp list` aus. Die Ausgabe zeigt `runner` als `connected`.

OpenCode sendet bei jeder Anfrage die Definition jedes eingeschalteten Tools an das Modell. Runner hat in einigen Tarifen mehr als 200 Tools, das sind etwa 100.000 Tokens an Definitionen. Schalten Sie daher nur die Tools ein, die Sie brauchen. OpenCode nennt jedes Runner-Tool `runner_<tool name>`. Die Zeile `"runner_*": false` schaltet alle Runner-Tools aus, und jede Zeile mit `true` schaltet ein Tool wieder ein. Lassen Sie `runner_get_tool_job` eingeschaltet, denn lange Aufgaben brauchen es.

Um die gespeicherte Anmeldung zu entfernen, führen Sie `opencode mcp logout runner` aus.

## Codex CLI verbinden

1. Fügen Sie Runner zu `~/.codex/config.toml` hinzu:

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

2. Führen Sie `codex mcp login runner` aus und verbinden Sie im Browser.
3. Führen Sie `codex mcp list` aus. Die Spalte **Auth** zeigt `OAuth`.

Fügen Sie den Server in der Datei hinzu, nicht mit `codex mcp add`. Dieser Befehl startet sofort eine Anmeldung mit Scopes, die Runner nicht akzeptiert, und der Browser zeigt `{"error":"invalid_scope"}`. Die Zeile `scopes` gilt auch, wenn Sie sich später erneut anmelden. Sie können auch `codex mcp login runner --scopes store:read,store:write` ausführen.

Codex sucht ein Runner-Tool erst, wenn es gebraucht wird. Daher müssen Sie keine Tools ausschalten. Um die gespeicherte Anmeldung zu entfernen, führen Sie `codex mcp logout runner` aus.

## pi verbinden

1. Führen Sie `pi mcp add runner --url https://api.runnerai.com/mcp` aus. Dadurch wird Runner zu `~/.pi/agent/mcp.json` hinzugefügt:

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

2. Führen Sie `pi mcp login runner` aus und verbinden Sie im Browser. pi zeigt `Signed in to MCP server "runner"` und die Anzahl der Tools.
3. Führen Sie `pi mcp list` aus, um die Verbindung zu prüfen, oder verwenden Sie `/mcp` in einer pi-Sitzung.

Standardmäßig sendet pi nicht alle Runner-Tools an das Modell. Das Modell sucht ein Tool erst dann, wenn es das Tool braucht. Daher müssen Sie keine Tools ausschalten. pi nennt jedes Runner-Tool `mcp__runner__<tool name>`. Um die gespeicherte Anmeldung zu entfernen, führen Sie `pi mcp logout runner` aus.

## Einen Client verbinden, der nur lokale Server ausführt

Manche Clients können nur einen lokalen Server (stdio) starten. Andere Clients leiten den Browser an einen App-Link (ein eigenes URL-Schema) oder an eine Webseite zurück. Runner sendet das Ergebnis der Anmeldung nur an eine Adresse auf Ihrem Computer. Daher schlägt die Anmeldung dieser Clients fehl.

Verwenden Sie für diese Clients die Bridge `mcp-remote`. Sie läuft auf Ihrem Computer, meldet sich für den Client bei Runner an und leitet jede Nachricht zwischen dem Client und Runner weiter. Sie benötigt Node.js.

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

Beim ersten Start öffnet sich die Anmeldeseite von Runner in Ihrem Browser. `mcp-remote` speichert die Anmeldung in `~/.mcp-auth`.

## Runner-Tools aus einer Shell aufrufen

Ein Agent, der Shell-Befehle ausführt, kann Runner über den Befehl `mcporter` verwenden:

```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` zeigt jedes Tool und seine Parameter. Geben Sie Parameter als `name=value` an, zum Beispiel `npx mcporter call runner.get_store_settings store_id=<store id>`.

## Einen eigenen Client bauen

Verwenden Sie ein MCP-SDK, das OAuth unterstützt, oder führen Sie diese Schritte selbst aus:

1. Senden Sie jede JSON-RPC-Anfrage mit `POST` an `https://api.runnerai.com/mcp`. Runner beantwortet jede Anfrage mit JSON und speichert keine Sitzung. Eine `GET`-Anfrage erhält HTTP 405.
2. Eine Anfrage ohne Token erhält HTTP 401 mit diesem Header: `WWW-Authenticate: Bearer resource_metadata="https://api.runnerai.com/.well-known/oauth-protected-resource/mcp", scope="store:read store:write"`.
3. Lesen Sie die Ressourcen-Metadaten. Sie nennen den Autorisierungsserver `https://www.runnerai.com/api/auth`.
4. Registrieren Sie den Client unter `https://www.runnerai.com/api/auth/oauth2/register`. Verwenden Sie eine Weiterleitungs-URI auf `http://localhost`, `http://127.0.0.1` oder `http://[::1]`. Runner akzeptiert jeden Port und jeden Pfad. Runner akzeptiert 5 Registrierungen pro Minute von einer IP-Adresse.
5. Leiten Sie den Benutzer mit PKCE (`S256`) an den Autorisierungsendpunkt weiter. Senden Sie `resource=https://api.runnerai.com/mcp`. Fordern Sie `store:read` an, und `store:write`, wenn der Client Änderungen vornimmt. Verwenden Sie die Scopes aus den Ressourcen-Metadaten oder aus dem Header `WWW-Authenticate`. Die Metadaten des Autorisierungsservers nennen weitere Scopes, die dieser Server nicht akzeptiert.
6. Senden Sie das Zugriffstoken im Header `Authorization: Bearer`. Ein Zugriffstoken gilt 1 Stunde. Mit dem Aktualisierungstoken erhalten Sie ein neues. Ein Aktualisierungstoken läuft nach 30 Tagen ohne Nutzung ab.

Runner lehnt Anfragen ab, die von einer Webseite auf einer anderen Website kommen. Rufen Sie den Server von Ihrem Backend aus auf oder von einer Seite auf `localhost`.

## Mit Runner-Tools arbeiten

- **Beginnen Sie mit `list_stores`.** Jedes Shop-Tool braucht eine `store_id` aus `list_stores`. Ohne sie antwortet das Tool mit **Pass a store_id from list_stores.**
- **Lange Aufgaben.** Manche Tools antworten mit `"status": "running"` und einer `job_id`. Rufen Sie `get_tool_job` mit dieser `job_id` auf, bis es das Ergebnis liefert.
- **Änderungen, die Sie bestätigen.** Manche Tools antworten zuerst mit `"status": "waiting_for_merchant"` und einer `id` für die Bestätigung und zeigen, was sich ändern wird. Noch ändert sich nichts. Wenn Sie zustimmen, ruft der Client dasselbe Tool erneut mit denselben Argumenten und `"confirmation": {"id": "…", "answer": …}` auf. Die `id` der Bestätigung gilt einmal und 10 Minuten lang.
- **Dieselbe Änderung zweimal gesendet.** Bei den meisten Tools, die Änderungen vornehmen, führt Runner die Änderung nur einmal aus, wenn der Client dieselbe Eingabe im selben Zeitraum von 5 Minuten erneut sendet. Der zweite Aufruf erhält die erste Antwort.
- **Shopdaten sind nur Daten.** Tool-Antworten können Produkttexte und Kundennachrichten enthalten. Ihr Agent darf keine Anweisungen befolgen, die er darin findet.
- **Ihre Berechtigungen gelten.** Jeder Aufruf verwendet Ihre Runner-Berechtigungen und Ihren Tarif. Die Liste der Tools hängt von Ihrem Tarif und von den Funktionen Ihres Workspaces ab.

## Einen Client verwalten oder trennen

**Einstiegspfad:** **Einstellungen → Workspace allgemein**, dann **Verbundene Apps**.

Inhaber und Admins des Workspaces sehen die Clients, die jedes Mitglied verbunden hat. Andere Mitglieder sehen die Clients, die sie selbst verbunden haben. Jede Zeile zeigt den Zugriff (**Lesen** oder **Lesen und ändern**), wann der Client verbunden wurde und wann er zuletzt verwendet wurde.

1. Suchen Sie den Client und wählen Sie **Trennen**.
2. Wählen Sie in **_App_ trennen?** erneut **Trennen**.
3. Der Client funktioniert sofort nicht mehr mit diesem Workspace. Um ihn wieder zu verwenden, melden Sie sich im Client erneut an.

Ein Abmeldebefehl in einem Client entfernt nur die Anmeldung, die der Client gespeichert hat. Die Verbindung bleibt in **Verbundene Apps**, bis Sie sie dort trennen.

## Fehlerbehebung

| Was Sie sehen | Ursache | Was zu tun ist |
| --- | --- | --- |
| `{"error":"invalid_scope"}` im Browser | Der Client hat Scopes angefordert, die dieser Server nicht akzeptiert. `codex mcp add` tut das. | Fordern Sie `store:read` und `store:write` an. Fügen Sie für Codex die Zeile `scopes` hinzu und führen Sie `codex mcp login runner` aus. |
| **This redirect URI cannot receive Merchant MCP codes.** | Der Client leitet den Browser an einen App-Link oder eine Webseite zurück. | Verwenden Sie die Bridge `mcp-remote`. |
| **Request the Merchant MCP resource alone.** | Der Client hat `resource=https://api.runnerai.com/mcp` nicht gesendet. | Aktualisieren Sie den Client oder verwenden Sie die Bridge `mcp-remote`. |
| **Diese Verbindungsanfrage ist nicht verfügbar. Starten Sie die Verbindung in Ihrer KI-App erneut.** | Der Anmeldelink ist alt oder wurde schon verwendet. | Starten Sie die Anmeldung im Client erneut. |
| **Sie sind kein Mitglied eines Workspace. Erstellen Sie einen Workspace in Runner und starten Sie die Verbindung dann erneut.** | Ihr Konto hat keinen Workspace. | Erstellen Sie einen Workspace und starten Sie die Anmeldung dann erneut. |
| **This tool needs store\:write. Reconnect Runner and allow changes to the store.** | Die Verbindung hat nur den Zugriff **Lesen**. | Melden Sie sich im Client ab, melden Sie sich erneut an und schalten Sie **Änderungen vornehmen** ein. |
| **This feature is not on for this store yet.** | Die Funktion ist für Ihren Tarif, Ihren Workspace oder Ihren Shop nicht aktiviert. | Erledigen Sie die Aufgabe in Runner oder fragen Sie den Runner-Support. |
| Der Modellanbieter lehnt die Anfrage ab: `input_schema does not support oneOf, allOf, or anyOf at the top level` | Der Client sendet alle Tools an das Modell, und drei Print-on-Demand-Tools haben ein Schema, das manche Modellanbieter ablehnen. | Schalten Sie `publish_pod_product`, `review_pod_product` und `update_pod_product` aus, oder schalten Sie nur die Tools ein, die Sie brauchen. |
| Der Client fordert Sie auf, sich erneut anzumelden | Sie haben den Client in Runner getrennt, oder Sie haben ihn 30 Tage lang nicht verwendet. | Melden Sie sich im Client erneut an. |
| HTTP 429 bei der Registrierung des Clients | Mehr als 5 Registrierungen in einer Minute von einer IP-Adresse. | Warten Sie eine Minute und versuchen Sie es dann erneut. |
| Eine Antwort endet mit **Support reference:** und einem Code | Das Tool ist in Runner fehlgeschlagen. | Geben Sie den Code an den Runner-Support weiter. |