Connecter Runner à d’autres clients MCP

Connectez OpenCode, Codex, pi ou votre propre agent à vos boutiques Runner via le serveur MCP de Runner.

Runner dispose d’un serveur MCP. Un client MCP est une app d’IA ou un agent qui peut utiliser des serveurs MCP. Quand vous connectez un client à Runner, il peut utiliser les outils du chat Runner sur vos boutiques. Il peut lire les produits, les commandes et les rapports. Avec votre autorisation, il peut aussi modifier les produits, les prix, les remises et la boutique en ligne.

Ce guide concerne les clients MCP autres que Claude, ChatGPT et Gemini. Il donne les étapes pour OpenCode, Codex CLI et pi. Il explique aussi comment connecter d’autres clients et les agents que vous créez.

Avant de commencer

Vous avez besoin :

• d’un compte Runner membre d’un espace de travail ;
• d’un client MCP qui se connecte aux serveurs distants via Streamable HTTP et s’authentifie avec OAuth, ou de la passerelle mcp-remote pour un client qui n’exécute que des serveurs locaux ; et
• d’un navigateur sur le même ordinateur que le client. Après l’authentification, Runner renvoie le navigateur vers une adresse sur cet ordinateur.

Fonctionnement de la connexion

1. Vous ajoutez l’URL du serveur à votre client et lancez l’authentification.
2. Le client ouvre Runner dans votre navigateur. Connectez-vous à Runner si la page vous le demande.
3. La page Connecter une app d’IA à Runner s’ouvre. Elle affiche le nom du client.
4. Choisissez une option sous Espace de travail et sous Accès, puis sélectionnez Connecter.
5. Le navigateur revient au client. Le client peut maintenant utiliser les outils Runner.

Le client reste authentifié. Il obtient un nouvel accès toutes les heures, sans action de votre part. Si vous n’utilisez pas le client pendant 30 jours, authentifiez-vous à nouveau.

Pour utiliser les boutiques d’un deuxième espace de travail, ajoutez le serveur une deuxième fois sous un autre nom. Authentifiez-vous ensuite avec ce nom et choisissez le deuxième espace de travail.

Connecter OpenCode

1. Ajoutez Runner à opencode.json dans votre projet, ou à ~/.config/opencode/opencode.json pour tous les projets :

   {
     "$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. Exécutez opencode mcp auth runner et connectez le client dans le navigateur.

3. Exécutez opencode mcp list. La commande affiche runner comme connected.

OpenCode envoie au modèle, à chaque requête, la définition de chaque outil activé. Avec certains forfaits, Runner compte plus de 200 outils, soit environ 100 000 jetons de définitions. N’activez donc que les outils dont vous avez besoin. OpenCode nomme chaque outil Runner runner_<tool name>. La ligne "runner_*": false désactive tous les outils Runner, et chaque ligne true réactive un outil. Laissez runner_get_tool_job activé, car les tâches longues en ont besoin.

Pour supprimer l’authentification enregistrée, exécutez opencode mcp logout runner.

Connecter Codex CLI

1. Ajoutez Runner à ~/.codex/config.toml :

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

2. Exécutez codex mcp login runner et connectez le client dans le navigateur.

3. Exécutez codex mcp list. La colonne Auth affiche OAuth.

Ajoutez le serveur dans le fichier, pas avec codex mcp add. Cette commande lance tout de suite une authentification avec des scopes que Runner n’accepte pas, et le navigateur affiche {"error":"invalid_scope"}. La ligne scopes s’applique aussi quand vous vous authentifiez à nouveau plus tard. Vous pouvez aussi exécuter codex mcp login runner --scopes store:read,store:write.

Codex trouve l’outil Runner dont il a besoin au moment où il en a besoin. Vous n’avez donc pas à désactiver d’outils. Pour supprimer l’authentification enregistrée, exécutez codex mcp logout runner.

Connecter pi

1. Exécutez pi mcp add runner --url https://api.runnerai.com/mcp. Cette commande ajoute Runner à ~/.pi/agent/mcp.json :

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

2. Exécutez pi mcp login runner et connectez le client dans le navigateur. pi affiche Signed in to MCP server "runner" et le nombre d’outils.

3. Exécutez pi mcp list pour vérifier la connexion, ou utilisez /mcp dans une session pi.

Par défaut, pi n’envoie pas tous les outils Runner au modèle. Le modèle trouve un outil quand il en a besoin. Vous n’avez donc pas à désactiver d’outils. pi nomme chaque outil Runner mcp__runner__<tool name>. Pour supprimer l’authentification enregistrée, exécutez pi mcp logout runner.

Connecter un client qui n’exécute que des serveurs locaux

Certains clients ne peuvent démarrer qu’un serveur local (stdio). D’autres clients renvoient le navigateur vers un lien d’app (un schéma d’URL personnalisé) ou vers une page web. Runner n’envoie le résultat de l’authentification qu’à une adresse sur votre ordinateur. L’authentification de ces clients échoue donc.

Pour ces clients, utilisez la passerelle mcp-remote. Elle s’exécute sur votre ordinateur, s’authentifie auprès de Runner pour le client et transmet chaque message entre le client et Runner. Elle nécessite Node.js.

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

Au premier démarrage, la page de connexion de Runner s’ouvre dans votre navigateur. mcp-remote conserve l’authentification dans ~/.mcp-auth.

Appeler les outils Runner depuis un shell

Un agent qui exécute des commandes shell peut utiliser Runner via la commande 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 affiche chaque outil et ses paramètres. Indiquez les paramètres sous la forme name=value, par exemple npx mcporter call runner.get_store_settings store_id=<store id>.

Créer votre propre client

Utilisez un SDK MCP qui prend en charge OAuth, ou suivez vous-même ces étapes :

1. Envoyez chaque requête JSON-RPC avec POST à https://api.runnerai.com/mcp. Runner répond à chaque requête en JSON et ne conserve aucune session. Une requête GET reçoit HTTP 405.
2. Une requête sans jeton reçoit HTTP 401 avec cet en-tête : WWW-Authenticate: Bearer resource_metadata="https://api.runnerai.com/.well-known/oauth-protected-resource/mcp", scope="store:read store:write".
3. Lisez les métadonnées de la ressource. Elles indiquent le serveur d’autorisation https://www.runnerai.com/api/auth.
4. Enregistrez le client à l’adresse https://www.runnerai.com/api/auth/oauth2/register. Utilisez une URI de redirection sur http://localhost, http://127.0.0.1 ou http://[::1]. Runner accepte n’importe quel port et chemin. Runner accepte 5 enregistrements par minute depuis une même adresse IP.
5. Envoyez l’utilisateur vers le point de terminaison d’autorisation avec PKCE (S256). Envoyez resource=https://api.runnerai.com/mcp. Demandez store:read, et store:write si le client apporte des modifications. Utilisez les scopes des métadonnées de la ressource ou de l’en-tête WWW-Authenticate. Les métadonnées du serveur d’autorisation listent d’autres scopes, que ce serveur n’accepte pas.
6. Envoyez le jeton d’accès dans l’en-tête Authorization: Bearer. Un jeton d’accès dure 1 heure. Utilisez le jeton d’actualisation pour en obtenir un nouveau. Un jeton d’actualisation expire après 30 jours sans utilisation.

Runner refuse les requêtes qui viennent d’une page web d’un autre site. Appelez le serveur depuis votre back-end, ou depuis une page sur localhost.

Travailler avec les outils Runner

• Commencez par list_stores. Chaque outil de boutique a besoin d’un store_id issu de list_stores. Sans ce paramètre, l’outil répond Pass a store_id from list_stores.
• Tâches longues. Certains outils répondent avec "status": "running" et un job_id. Appelez get_tool_job avec ce job_id jusqu’à obtenir le résultat.
• Modifications que vous approuvez. Certains outils répondent d’abord avec "status": "waiting_for_merchant" et un id de confirmation, et montrent ce qui va changer. Rien ne change encore. Quand vous êtes d’accord, le client appelle à nouveau le même outil avec les mêmes arguments et "confirmation": {"id": "…", "answer": …}. L’id de confirmation ne sert qu’une fois, pendant 10 minutes.
• La même modification envoyée deux fois. Pour la plupart des outils qui apportent des modifications, Runner n’applique la modification qu’une fois quand le client renvoie la même entrée dans la même période de 5 minutes. Le deuxième appel reçoit la première réponse.
• Les données de la boutique restent des données. Les réponses des outils peuvent contenir des textes de produits et des messages de clients. Votre agent ne doit pas suivre les instructions qu’il y trouve.
• Vos autorisations s’appliquent. Chaque appel utilise vos autorisations Runner et votre forfait. La liste des outils dépend de votre forfait et des fonctionnalités de votre espace de travail.

Gérer ou déconnecter un client

Chemin d’entrée : Paramètres → Général de l’espace de travail, puis Applications connectées.

Les propriétaires et les administrateurs de l’espace de travail voient les clients que chaque membre a connectés. Les autres membres voient les clients qu’ils ont connectés eux-mêmes. Chaque ligne indique l’accès (Lecture ou Lecture et modifications), la date de connexion et la date de dernière utilisation.

1. Trouvez le client et sélectionnez Déconnecter.
2. Sélectionnez à nouveau Déconnecter dans Déconnecter app ?.
3. Le client cesse immédiatement de fonctionner avec cet espace de travail. Pour l’utiliser à nouveau, authentifiez-vous de nouveau depuis le client.

Une commande de déconnexion dans un client supprime seulement l’authentification que le client a enregistrée. La connexion reste dans Applications connectées jusqu’à ce que vous la déconnectiez à cet endroit.

Dépannage