Runner mit anderen MCP-Clients verbinden

Verbinden Sie OpenCode, Codex, pi oder Ihren eigenen Agenten über den MCP-Server von Runner mit Ihren Runner-Shops.

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.

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.

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:

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

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

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

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

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