---
lastModified: 2026-11-13
title: Connecter Runner à d’autres clients MCP
description: Connectez OpenCode, Codex, pi ou votre propre agent à vos boutiques Runner via le serveur MCP de Runner.
seo:
  description: "Connectez OpenCode, Codex, pi ou votre propre agent à vos boutiques Runner. Ajoutez une URL de serveur, connectez-vous à Runner dans votre navigateur et choisissez ce que le client peut faire."
---

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.

| Paramètre | Valeur |
| --- | --- |
| URL du serveur | `https://api.runnerai.com/mcp` |
| Transport | Streamable HTTP. Runner ne prend pas en charge l’ancien transport SSE. |
| Authentification | OAuth dans votre navigateur. Vous n’avez pas besoin de clé API. |
| Accès | `store:read` pour lire les données de la boutique. `store:write` pour apporter des modifications. |

## 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.

| Contrôle ou message | Pourquoi c’est utile | Que se passe-t-il ensuite |
| --- | --- | --- |
| **Retour vers** | Affiche l’adresse sur votre ordinateur qui reçoit le résultat de l’authentification. | Elle indique `localhost`, `127.0.0.1` ou `[::1]` et un numéro de port. |
| **Runner ne peut pas confirmer de quelle app il s’agit. Connectez-la uniquement si vous avez lancé cette connexion vous-même.** | Runner ne peut pas vérifier l’identité d’un client que vous avez installé ou créé. | Connectez le client uniquement si vous avez lancé l’authentification depuis votre client. |
| **Espace de travail** | Une connexion fonctionne avec les boutiques d’un seul espace de travail. | Le client ne peut utiliser que les boutiques de l’espace de travail que vous choisissez. |
| **Lecture** | Toujours activée. Le client peut voir les données de la boutique, comme les produits, les commandes et les rapports. | Vous ne pouvez pas la désactiver. |
| **Apporter des modifications** | Permet au client de modifier les données de la boutique, comme les produits, les prix et les remises. | Désactivée au départ. Elle n’apparaît que si le client demande un accès en modification. |
| **Connecter** | Donne au client l’accès que vous avez choisi. | Le navigateur revient au client. |
| **Annuler** | Arrête l’authentification. | Le client n’obtient aucun accès. |

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 :

   ```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. 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` :

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

   ```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.

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

```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` 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

| Ce que vous voyez | Cause | Que faire |
| --- | --- | --- |
| `{"error":"invalid_scope"}` dans le navigateur | Le client a demandé des scopes que ce serveur n’accepte pas. `codex mcp add` le fait. | Demandez `store:read` et `store:write`. Pour Codex, ajoutez la ligne `scopes` et exécutez `codex mcp login runner`. |
| **This redirect URI cannot receive Merchant MCP codes.** | Le client renvoie le navigateur vers un lien d’app ou une page web. | Utilisez la passerelle `mcp-remote`. |
| **Request the Merchant MCP resource alone.** | Le client n’a pas envoyé `resource=https://api.runnerai.com/mcp`. | Mettez à jour le client, ou utilisez la passerelle `mcp-remote`. |
| **Cette demande de connexion est indisponible. Relancez la connexion depuis votre app d’IA.** | Le lien d’authentification est ancien ou a déjà servi. | Relancez l’authentification depuis le client. |
| **Vous n’êtes membre d’aucun espace de travail. Créez un espace de travail dans Runner, puis relancez la connexion.** | Votre compte n’a aucun espace de travail. | Créez un espace de travail, puis relancez l’authentification. |
| **This tool needs store\:write. Reconnect Runner and allow changes to the store.** | La connexion n’a que l’accès **Lecture**. | Déconnectez-vous dans le client, authentifiez-vous à nouveau et activez **Apporter des modifications**. |
| **This feature is not on for this store yet.** | La fonctionnalité n’est pas activée pour votre forfait, votre espace de travail ou votre boutique. | Effectuez la tâche dans Runner, ou demandez au support Runner. |
| Le fournisseur du modèle refuse la requête : `input_schema does not support oneOf, allOf, or anyOf at the top level` | Le client envoie tous les outils au modèle, et trois outils d’impression à la demande ont un schéma que certains fournisseurs de modèles refusent. | Désactivez `publish_pod_product`, `review_pod_product` et `update_pod_product`, ou n’activez que les outils dont vous avez besoin. |
| Le client vous demande de vous authentifier à nouveau | Vous avez déconnecté le client dans Runner, ou vous ne l’avez pas utilisé pendant 30 jours. | Authentifiez-vous à nouveau depuis le client. |
| HTTP 429 lors de l’enregistrement du client | Plus de 5 enregistrements en une minute depuis une même adresse IP. | Attendez une minute, puis réessayez. |
| Une réponse se termine par **Support reference:** et un code | L’outil a échoué dans Runner. | Communiquez le code au support Runner. |