---
title: "Serveur MCP"
description: "Connectez Claude, ChatGPT, Cursor, VS Code, Codex ou n’importe quel client MCP à Beeuni via OAuth ou un jeton d’accès personnel. Une seule URL donne accès à tous les projets que vous pouvez ouvrir. Rien à installer."
---

> **Expérimental.** Ses outils peuvent changer sans préavis.

Beeuni dispose d’un serveur MCP hébergé :

```text
https://api.beeuni.ai/v1/mcp
```

Ajoutez cette URL une seule fois à un client MCP. Au premier appel, vous devrez vous connecter à Beeuni dans le navigateur. Ensuite, le client agit en votre nom, avec vos autorisations, sur tous les comptes et projets que vous pouvez ouvrir — comme avec la [CLI](/docs/fr/cli). L’URL ne désigne aucun projet : les outils prennent un `project_id` ou un `session_id`, et `list_projects` les répertorie. Rien à installer.

<a id="add-it-to-a-client"></a>

## Ajouter le serveur à un client

Tous les clients ci-dessous vous connectent via OAuth lors de la première utilisation, sauf si les instructions indiquent un jeton. Ne remplacez rien : l’URL est la même pour tous les projets.

### Claude Code

```bash
claude mcp add --transport http beeuni https://api.beeuni.ai/v1/mcp
```

Exécutez `/mcp` dans Claude Code et connectez-vous. Pour utiliser un jeton d’accès personnel à la place, ajoutez `--header "Authorization: Bearer $BEEUNI_TOKEN"` à la commande.

<a id="claude-desktop-and-claudeai"></a>

### Claude Desktop et claude.ai

**Settings → Connectors → Add custom connector**. Collez l’URL et connectez-vous.

### ChatGPT

Les connecteurs MCP personnalisés nécessitent le mode développeur. Selon le [guide du mode développeur](https://developers.openai.com/api/docs/guides/developer-mode) d’OpenAI, activez le **Developer mode** dans **Settings → Security and login**, puis créez une application en mode développeur depuis la page des plugins ChatGPT (bouton plus). Saisissez l’URL et choisissez l’authentification **OAuth**. OpenAI indique les forfaits et les noms des menus, qui peuvent changer : suivez ce guide si un libellé diffère.

### Cursor

Utilisez le bouton **Add to Cursor** dans **Connect MCP**, ou ajoutez le serveur à `~/.cursor/mcp.json` (tous les projets) ou à `.cursor/mcp.json` (un seul projet) :

```json
{ "mcpServers": { "beeuni": { "url": "https://api.beeuni.ai/v1/mcp" } } }
```

### VS Code

Ajoutez le serveur à `.vscode/mcp.json`. VS Code utilise `servers`, et non `mcpServers`, et nécessite `type` :

```json
{ "servers": { "beeuni": { "type": "http", "url": "https://api.beeuni.ai/v1/mcp" } } }
```

### Codex

```bash
codex mcp add beeuni --url https://api.beeuni.ai/v1/mcp
codex mcp login beeuni
```

Vous pouvez aussi modifier `~/.codex/config.toml`. Pour utiliser un jeton d’accès personnel, indiquez la variable d’environnement qui le contient :

```toml
[mcp_servers.beeuni]
url = "https://api.beeuni.ai/v1/mcp"
bearer_token_env_var = "BEEUNI_TOKEN"
```

<a id="other-clients"></a>

### Autres clients

Ajoutez un serveur MCP distant (Streamable HTTP) avec l’URL. Un client qui ne prend pas en charge OAuth envoie un jeton d’accès personnel dans un en-tête (ci-dessous).

Ouvrez le menu de l’espace de travail (le nom du projet, en haut à gauche) et sélectionnez **Connect MCP** pour copier l’URL et les instructions pour Claude, Claude Code, Cursor et Codex.

<a id="sign-in"></a>

## Connexion

Le serveur utilise le flux OAuth 2.1 défini par la spécification MCP. Le client le gère sans configuration :

1. Un appel sans jeton reçoit `401` avec `WWW-Authenticate: Bearer resource_metadata="…", scope="beeuni"`.
2. Le client lit le document RFC 9728 à l’adresse `/.well-known/oauth-protected-resource/v1/mcp`. Il y est indiqué que Beeuni est le serveur d’autorisation.
3. Le client s’enregistre à `POST /v1/oauth/register` (RFC 7591). Il obtient un client public qui s’authentifie uniquement avec PKCE.
4. Vous autorisez le client sur l’écran de consentement Beeuni. Un client auto-enregistré est marqué **Unverified app**, avec l’hôte vers lequel il vous redirige. Ne l’autorisez que si vous le connectez vous-même.
5. Le client échange le code contre un jeton d’accès `beeuni_oat_` (1 heure) et un jeton d’actualisation (30 jours, renouvelé à chaque utilisation). Lorsque le jeton d’accès expire, le client l’actualise sans vous le redemander.

<a id="revoke-a-client"></a>

### Révoquer un client

**Settings → Personal access keys → Connected apps** répertorie toutes les applications que vous avez autorisées, sur l’ensemble de vos comptes : leur nom, leur méthode de connexion et la date de leur dernière activité. Un client MCP auto-enregistré est marqué **Unverified app**. **Revoke access** supprime votre autorisation et révoque ses jetons : sa prochaine requête échoue et il doit vous demander à nouveau l’autorisation. Depuis un terminal : `beeuni tokens apps ls` et `beeuni tokens apps rm <client-id>`. Les deux commandes ne fonctionnent que depuis une session de navigateur ou avec un jeton d’accès personnel, jamais avec le jeton propre à une application.

<a id="what-a-connected-app-cannot-do"></a>

### Ce qu’une application connectée ne peut pas faire

La portée `beeuni` lui permet d’agir en votre nom : une application connectée peut lire et modifier ce que vous pouvez lire et modifier. Elle ne peut pas créer un identifiant qui reste valide après la révocation de son propre jeton. Ces routes répondent `403` pour un jeton `beeuni_oat_` :

- les jetons d’accès personnels (`POST /v1/accounts/tokens`) et les jetons CLI de projet ;
- les clés de passerelle ;
- les jetons SCIM ;
- les clients OAuth et la rotation de leurs secrets ;
- les comptes de service ;
- la liste des applications connectées et leur révocation (`/v1/oauth/grants`).

Révoquez un client et son accès prend fin. Un jeton d’accès personnel est différent : il n’expire pas, sauf si vous indiquez `--expires`, et la révocation d’une application ne le révoque pas.

<a id="personal-access-token"></a>

### Jeton d’accès personnel

Un client sans OAuth, ou un script, envoie plutôt un jeton `beeuni_pat_` — celui utilisé par la CLI. Créez-en un avec `beeuni tokens new <name>` ou dans **Settings → Personal access keys**, puis envoyez-le dans un en-tête :

```json
{ "mcpServers": { "beeuni": { "url": "https://api.beeuni.ai/v1/mcp", "headers": { "Authorization": "Bearer beeuni_pat_…" } } } }
```

<a id="tools"></a>

## Outils

`tools/list` renvoie 23 outils. Les paramètres marqués d’un * sont obligatoires.

| Outil | Paramètres | Fonction |
| --- | --- | --- |
| `list_projects` | aucun | Répertorie tous les projets que vous pouvez ouvrir, sur l’ensemble de vos comptes, avec leur `project_id` et votre rôle. |
| `start_session` | `project_id`*, `prompt`*, `name`, `agent` | Démarre une session dans un projet avec un premier prompt. Renvoie le `session_id`. |
| `send_message` | `session_id`*, `text`* | Met un message en file d’attente pour une session et la démarre si elle est arrêtée. |
| `read_session` | `session_id`*, `limit`, `wait_seconds` | Renvoie l’état d’une session, indique si son tour est `idle`, `booting`, `running` ou `queued`, ainsi que ses messages les plus récents avec les entrées et sorties de chaque appel d’outil. `limit` est de 10 par défaut et de 100 au maximum. `wait_seconds` (jusqu’à 45) attend la fin du tour. |
| `list_sessions` | `project_id`*, `limit`, `cursor` | Répertorie les sessions visibles dans un projet : identifiant, titre, état, agent, propriétaire, branche et dates. `limit` est de 20 par défaut et de 200 au maximum. |
| `run_command` | `session_id`*, `command`, `cwd`, `timeout_seconds`, `job_id`, `cancel` | Exécute une commande bash dans le bac à sable d’une session et renvoie stdout, stderr et le code de sortie. Une commande longue renvoie un `job_id` sur lequel continuer d’attendre. |
| `read_file` | `path`*, `session_id`, `project_id`, `ref`, `offset`, `limit` | Lit un fichier du bac à sable d’une session ou du dépôt git d’un projet à `ref`. Les images sont renvoyées sous forme d’images. |
| `write_file` | `session_id`*, `path`*, `content`*, `encoding` | Écrit un fichier dans le bac à sable d’une session et crée ses répertoires parents. `encoding` est `utf8` (par défaut) ou `base64`. |
| `list_files` | `path`, `session_id`, `project_id`, `ref`, `offset` | Répertorie un répertoire du bac à sable d’une session ou tous les fichiers du dépôt d’un projet sous un chemin donné. |
| `read_skill` | `name`, `file`, `project_id` | Répertorie les guides de la plateforme Beeuni ou renvoie un guide (`name`) ou l’un de ses fichiers de référence (`file`). Avec `project_id`, les compétences propres au projet sont répertoriées en premier, et une compétence de projet `name` renvoie son `SKILL.md` et les chemins de ses fichiers de référence. |
| `list_connectors` | `project_id`*, `connector` | Répertorie les connecteurs d’un projet : slug, fournisseur, disponibilité de chacun (`connected`, utilisable par vous maintenant), nombre d’actions et comptes. Avec `connector`, répertorie tous les comptes de ce connecteur. |
| `search_connector_actions` | `project_id`*, `query`, `connector`, `limit` | Recherche des actions de connecteur par objectif. Renvoie `tool` (`<connector>.<action>`), `risk` et une description en une ligne. Ne renvoie jamais de schémas. |
| `describe_connector_action` | `project_id`*, `tool`* | Renvoie le schéma JSON d’entrée, le niveau de risque et la description d’une action. |
| `call_connector` | `project_id`*, `tool`*, `args`, `account`, `reason` | Exécute une action en votre nom. Renvoie les données et le `account` qui l’a exécutée, un résultat `pending_approval` avec le lien d’approbation, ou un refus accompagné de son motif. |
| `upload_connector_attachment` | `project_id`*, `connector`*, `filename`*, `content_base64` ou `session_id` + `path` | Prépare un fichier et renvoie la référence `{"$beeuni_attachment": "<id>"}` à insérer dans `args`. |
| `connect_connector` | `project_id`*, `connector`*, `owner`, `label` | Renvoie le lien qu’une personne ouvre pour connecter le compte du connecteur. |
| `search_connector_apps` | `project_id`*, `query`*, `limit`, `cursor` | Recherche dans le catalogue des applications gérées auxquelles un connecteur peut être ajouté. |
| `add_connector` | `project_id`*, `app` ou `provider` + `slug`, `name`, `url`, `transport`, `endpoint`, `spec`, `base_url` | Ajoute immédiatement un connecteur au projet (validé dans `beeuni.yaml` sur `main`, puis synchronisé). |
| `remove_connector` | `project_id`*, `connector`* | Supprime un connecteur du projet. |
| `beeuni` | `args`*, `project_id`, `session_id` | Exécute la véritable interface en ligne de commande `beeuni` en votre nom et renvoie `exit_code`, `stdout` (ou `json` pour la sortie `--json`) et `stderr`. Voir [Exécuter n’importe quelle commande CLI](#run-any-cli-command). |
| `search_api` | `query`*, `limit` | Recherche les routes de l’API Beeuni par mot-clé. |
| `describe_api` | `method`*, `path`* | Renvoie les paramètres, le corps de la requête et le schéma de réponse d’une route. |
| `call_api` | `method`*, `path`*, `project_id`, `query`, `body` | Appelle n’importe quelle route `/v1/` en votre nom. `project_id` renseigne `{projectId}` dans le chemin. |

`search_api`, `describe_api` et `call_api` couvrent tout ce que font l’application Web et la
[CLI](/docs/fr/cli), car elles sont toutes deux clientes de la même API. `call_api`
refuse `/v1/oauth/*` ainsi que tout chemin menant à un point de terminaison MCP. Renseignez vous-même chaque autre `{placeholder}` dans le chemin. Chaque appel applique la même autorisation et le même audit qu’une requête provenant de l’application Web. L’audit consigne chaque appel avec `credential_kind: "oauth_app"` et le nom de l’application connectée, car l’API consigne l’identifiant d’authentification utilisé, et non une étiquette envoyée par le client.

<a id="run-any-cli-command"></a>

### Exécuter n’importe quelle commande CLI

L’outil `beeuni` exécute la véritable [CLI `beeuni`](/docs/fr/cli) en votre nom. Toutes les commandes CLI fonctionnent avec cet outil : le serveur MCP dispose donc des mêmes capacités qu’un terminal, notamment pour les secrets, les déclencheurs, `cr`, `review`, les rappels, les agents, les modèles, la passerelle, les fournisseurs, les canaux, les bacs à sable, les applications, la marketplace, les fichiers, l’accès, les rôles, les autorisations, l’audit, les autorisations accordées, les membres, les groupes, les jetons, la facturation, les projets, les sessions et `system-skills`. Un seul outil remplace environ 200 outils de sous-commandes, qui dépasseraient la limite d’outils de clients comme Cursor.

`args` correspond aux arguments après `beeuni`, avec un élément de tableau par argument. Ce n’est jamais une ligne de commande shell.

```json
{ "name": "beeuni", "arguments": { "args": ["--help"] } }
{ "name": "beeuni", "arguments": { "args": ["secrets", "ls", "--json"], "project_id": "<project_id>" } }
{ "name": "beeuni", "arguments": { "args": ["triggers", "ls", "--json"], "project_id": "<project_id>" } }
{ "name": "beeuni", "arguments": { "args": ["system-skills"] } }
```

- Découvrez les commandes avec `["--help"]` et `["<group>", "--help"]`. Ajoutez `--json` aux sorties que vous analysez.
- `project_id` définit le projet d’une commande liée à un projet. `session_id` définit la session d’une commande qui agit sur une session.
- Le résultat est au format JSON : `exit_code`, `stdout`, `stderr`. Avec `--json`, la sortie de la commande est renvoyée sous forme de valeur JSON dans `json` au lieu de `stdout`. Les sorties trop volumineuses sont tronquées et marquées `truncated` ; un JSON tronqué n’est pas valide, réduisez donc la portée de la commande. Un `exit_code` non nul est une erreur MCP. Chaque flux est limité à 24 000 caractères (stdout) et 8 000 caractères (stderr), et le résultat l’indique dans `truncated`.
- Toute commande qui s’exécute pendant plus d’environ 45 secondes est arrêtée. Le résultat contient `timed_out`.
- Le serveur exécute au maximum 4 commandes CLI simultanément. Un cinquième appel renvoie `Busy` : réessayez.
- Les sessions, les fichiers du bac à sable et les connecteurs disposent d’outils dédiés (`start_session`, `run_command`, `read_file`, `call_connector`). Privilégiez-les.

La CLI s’exécute sur le serveur avec votre propre jeton et interroge cette API. Elle n’a accès à aucun identifiant du serveur : son environnement ne contient que votre jeton, l’URL de l’API, les identifiants du projet et de la session, ainsi qu’un répertoire personnel temporaire et un répertoire de travail vides. Le serveur supprime ces deux répertoires après l’exécution de la commande. L’autorisation et l’audit relèvent de l’API : le jeton d’un utilisateur externe bénéficie des mêmes `403` que depuis un terminal.

Ces commandes sont refusées avant toute exécution. L’erreur indique le motif et la solution de remplacement.

| Commande | Pourquoi | À utiliser à la place |
| --- | --- | --- |
| n’importe quel indicateur `--host` ou `--host=`, `hosts` | Dirige la CLI vers un autre serveur et lui enverrait votre jeton. | Ce serveur agit déjà en votre nom. |
| `login`, `logout` | Connexion via navigateur et jetons stockés. | Vous êtes connecté via la connexion MCP. |
| `init`, `ship`, `deploy` | Lire ou écrire dans un répertoire local. | `run_command` dans un bac à sable de session, là où se trouve le code source. |
| `tools` | Lit et modifie un `beeuni.yaml` local, et le serveur n’a pas de copie de travail du projet. | `run_command` dans un bac à sable de session : exécutez `beeuni tools ls` à cet endroit. |
| `apps deploy` | Déploie un répertoire local, que le serveur ne possède pas. | `run_command` dans un bac à sable de session : exécutez `beeuni apps deploy <path>` à cet endroit. |
| `env pull`, `env push` | Écrire ou lire un fichier local. | `secrets ls`, `secrets set KEY=value`. |
| `token`, `whoami --token-only` | Afficher le jeton d’accès brut. | `whoami --json`. |
| `update`, `uninstall` | Changer la machine qui exécute la CLI. | Aucun. |
| `tui`, `t`, `connect`, `attach`, `sessions connect|shell|forward` | Nécessitent un terminal interactif. | `start_session`, `send_message`, `read_session`, `run_command`. |
| `chat` et `sessions chat` sans `--prompt` | Ouvrir une discussion interactive. | `start_session`, `send_message`, ou ajoutez `--prompt "<text>"`. |

L’audit consigne une commande CLI avec le même identifiant d’authentification que tous les autres appels
sur la connexion (`credential_kind: "oauth_app"`). Il ne peut pas distinguer l’outil `beeuni`
de `call_api` : les deux accèdent à l’API avec votre jeton.

<a id="project-skills"></a>

### Compétences du projet

`read_skill` avec un `project_id` répertorie les compétences propres au projet (les
fichiers `skills/<slug>/SKILL.md` du dépôt, ou le répertoire hérité
`.beeuni/opencode/skills/`) avant les guides de la plateforme. Passez le `name` de la compétence
pour lire son `SKILL.md` et les chemins de ses fichiers de référence, puis `file` pour lire
une référence. Vous voyez les compétences autorisées par votre rôle et vos droits d’accès.

<a id="use-your-connectors"></a>

### Utiliser vos connecteurs

Les outils des connecteurs sont les outils MCP de la CLI [`beeuni connectors`](/docs/fr/connect/connectors). Ils appellent les mêmes routes d’API que la CLI et le SDK ; les politiques des connecteurs, les approbations et les audits fonctionnent donc de la même façon sur toutes les interfaces.

1. `list_connectors` indique ce qui est connecté. Un connecteur avec
   `connected: false` ne peut pas exécuter d’actions : appelez `connect_connector`, ouvrez le
   lien renvoyé, puis relancez l’énumération.
2. `search_connector_actions` recherche une action par intention, par exemple
   `send an email`. `describe_connector_action` renvoie ses arguments.
3. `call_connector` l’exécute. Le résultat indique le `account` qui a effectué l’appel.
   Un connecteur associé à plusieurs comptes et sans compte par défaut nécessite `account`.
4. Passez `reason` pour une écriture dont les arguments ne sont que des identifiants (`send_draft`,
   suppression par identifiant). La personne chargée de l’approbation le voit à côté des arguments réels.

Une politique peut suspendre un appel en attente d’approbation. `call_connector` renvoie alors
`status: "pending_approval"` avec un `approval_url`. Une personne l’ouvre et
l’approuve. Rappelez le même outil, avec les mêmes arguments et le même compte dans les 15 minutes : l’appel approuvé s’exécute une fois. Un refus `policy_block` est définitif.

Un résultat de plus d’environ 40 000 caractères est renvoyé sous forme d’aperçu signalé
(`data_truncated`). Réduisez les arguments et rappelez l’outil. Pour joindre un fichier,
préparez-le avec `upload_connector_attachment` et placez la référence renvoyée dans
`args`. Les connecteurs utilisant le fournisseur `composio` n’acceptent pas les références de pièces jointes.

<a id="result-size-and-paging"></a>

### Taille des résultats et pagination

- Le résultat d’un outil est tronqué à 60 000 caractères et se termine par
  `…[truncated at 60000 chars]`.
- `read_file` renvoie les fichiers texte longs par pages d’environ 50 000
  caractères au maximum. Un résultat tronqué se termine par le `offset` qui permet de poursuivre. `offset`
  ignore des lignes et `limit` limite le nombre de lignes renvoyées. Un fichier binaire n’est pas
  renvoyé sous forme de texte : lisez-le avec `run_command`.
- `list_files` tronque les longues listes de la même façon. Passez le `offset` qu’il indique.
- `list_sessions` renvoie `next_cursor` lorsqu’il existe d’autres sessions. Renvoyez-le
  en tant que `cursor`.
- `read_session` renvoie les derniers messages `limit`. Il tronque chaque entrée
  et sortie d’outil, et supprime les messages les plus anciens lorsque le résultat ne tient pas
  (`omitted_older`). `last_turn_error` indique un tour qui a échoué.
- Une requête MCP reçoit une réponse en 55 secondes. `read_session` avec
  `wait_seconds` et un bac à sable encore en cours de démarrage s’arrêtent tous deux avant ce délai :
  rappelez l’outil.

<a id="sandboxes"></a>

### Bacs à sable

`run_command`, `read_file`, `write_file` et `list_files` avec un `session_id`
accèdent au bac à sable actif de la session, comme le font le terminal Web et le panneau des fichiers. Les chemins relatifs sont résolus sous `/workspace`, la copie de travail Git de la session. Un bac à sable arrêté démarre lors du premier appel. La CLI `beeuni` dans le bac à sable est connectée en tant que session. Avec un `project_id` et sans `session_id`, `read_file`
et `list_files` lisent le dépôt Git du projet sans démarrer de bac à sable.

Une commande peut s’exécuter pendant plusieurs minutes. Un appel d’outil attend environ 50 secondes. Si la commande est toujours en cours à ce moment-là, `run_command` renvoie `status: running`, un `job_id` et la sortie obtenue jusque-là. Appelez `run_command` avec ce `job_id` pour continuer à attendre, ou avec `cancel: true` pour arrêter la commande. `timeout_seconds` (valeur par défaut : 600, maximum : 86400) arrête une commande qui s’exécute trop longtemps, avec le code de sortie `124`. La sortie est conservée dans `~/.cache/beeuni-mcp/jobs/<job_id>/` dans le bac à sable ; le résultat de l’outil affiche les 24 000 derniers octets de chaque flux. Si un bac à sable s’arrête, les commandes en cours s’arrêtent aussi.

Le serveur est sans état : il répond à `POST` avec du JSON, et à `GET` et `DELETE` avec `405`.