---
type: how-to
title: Utiliser le serveur MCP
summary: Connecte un agent IA à Caputchin via le serveur MCP, authentifie-le avec un jeton d'accès, et pilote l'API de gestion en langage naturel, avec un exemple concret.
---

Le serveur MCP de Caputchin permet à un agent IA (Claude, Cursor, ou tout client [Model Context Protocol](https://modelcontextprotocol.io)) de gérer ton compte en appelant la même [API de gestion](/docs/automation/management-api) que le tableau de bord utilise. Le serveur est une fine enveloppe de transport et d'authentification : il expose un outil MCP par opération de gestion et relaie chaque appel vers l'API. Donc l'agent peut faire tout ce que tu peux, hors facturation, en langage naturel.

## Génère un jeton d'accès [#mint-an-access-token]

Le serveur s'authentifie avec un jeton d'accès depuis la variable d'environnement `CAPUTCHIN_TOKEN`. Les deux types fonctionnent (voir [authentification de l'API](/docs/automation/management-api#mint-an-access-token)) :

- un [Personal Access Token](/docs/account-management/personal-access-token) pour le contrôle pleine-compte, ou
- un [Troop Access Token](/docs/troops/tokens) pour limiter l'agent à certaines équipes avec le moindre privilège, ce qui est le défaut plus sûr quand tu confies l'accès à un agent autonome.

Copie le jeton à la création ; il n'est montré qu'une fois.

## Deux façons de se connecter

Il y a deux transports, et ils exposent les **mêmes outils** adossés à la même API de gestion. Choisis selon la façon dont ton client se connecte :

| | Local (stdio) | Hébergé (HTTP) |
|---|---|---|
| Ce que c'est | Le paquet `@caputchin/mcp`, exécuté sur ta machine | Un point de terminaison distant sur `api.caputchin.com/mcp` |
| Le client doit | Lancer un processus local (stdio) | Se connecter à un serveur MCP distant (HTTP) |
| Auth | `CAPUTCHIN_TOKEN` dans l'environnement du processus | En-tête `Authorization: Bearer` sur la connexion |
| Idéal quand | Dev local, un client de bureau, pas de réseau entrant | Un agent hébergé, pas de processus local à lancer |

### Local : le serveur npx (stdio)

Le serveur est publié sous `@caputchin/mcp` sur npm. D'ordinaire tu ne le lances pas à la main ; tu le câbles dans la config de ton client MCP et il est lancé via stdio, avec le jeton dans son environnement :

```json
{
  "mcpServers": {
    "caputchin": {
      "command": "npx",
      "args": ["-y", "@caputchin/mcp"],
      "env": { "CAPUTCHIN_TOKEN": "cpt_pat_..." }
    }
  }
}
```

Pour vérifier qu'il tourne, lance-le directement ; il parle MCP via stdio et sort avec une erreur si le jeton manque :

```bash
CAPUTCHIN_TOKEN=cpt_pat_... npx -y @caputchin/mcp
```

### Hébergé : le point de terminaison HTTP

Pour les clients qui se connectent à un serveur MCP distant plutôt que d'en lancer un local, Caputchin héberge le même serveur sur :

```
https://api.caputchin.com/mcp
```

Il s'authentifie avec ton jeton comme en-tête `Bearer` sur la connexion (le même identifiant, juste passé par HTTP plutôt que par l'environnement) :

```json
{
  "mcpServers": {
    "caputchin": {
      "url": "https://api.caputchin.com/mcp",
      "headers": { "Authorization": "Bearer cpt_pat_..." }
    }
  }
}
```

La forme exacte de la config dépend de ton client MCP ; ce qui compte, c'est l'URL et l'en-tête `Authorization: Bearer`. Rien à installer, et pas de processus local ; le compromis est que le jeton voyage vers le point de terminaison hébergé à chaque requête plutôt que de rester dans l'environnement d'un processus local.

## Les outils

Chaque outil est nommé `caputchin_<verb>_<noun>` et correspond à une opération de gestion, par exemple `caputchin_list_troops`, `caputchin_create_site`, `caputchin_rotate_site_secret`, `caputchin_add_troop_member`, `caputchin_site_stats`. L'agent découvre l'ensemble complet et les paramètres de chaque outil automatiquement via MCP, donc tu décris le but et l'agent choisit les outils.

## Un exemple concret

Avec le serveur câblé dans ton client, tu peux demander à l'agent en langage simple :

> « Crée une clé de site appelée shop-frontend dans mon équipe shop-team, puis active le gate de jeu dessus. »

L'agent résout ça en une suite d'appels d'outils : `caputchin_list_troops` pour trouver l'id de l'équipe, `caputchin_create_site` avec ce `troop_id`, puis `caputchin_update_site_security` pour exiger un jeu. Chaque appel atteint l'API de gestion sous ton jeton, et sur Apex chacun atterrit dans ton [journal d'audit](/docs/audit-logs/overview) attribué au jeton, donc les actions d'un agent sont aussi traçables que celles d'une personne.

Parce que l'agent agit avec toute la portée de ton jeton, préfère un jeton d'équipe limité quand tu peux, et révoque-le dès que la tâche est faite.

## La référence complète

Pour la liste complète des outils, chacun avec une description en une ligne et la permission que son jeton doit détenir, vois la [référence des outils MCP](/docs/automation/mcp-tools). Les outils reflètent l'API de gestion un pour un, donc la [référence interactive de l'API](/docs/api-reference) est la description faisant autorité des paramètres et de la réponse de chaque opération : lis la description MCP d'un outil pour le résumé côté agent, et la référence de l'API pour le schéma exact.

## Voir aussi

- [Référence des outils MCP](/docs/automation/mcp-tools) : chaque outil, sa description et la permission qu'il requiert.
- [Gérer Caputchin depuis l'API](/docs/automation/management-api) : l'API HTTP que chaque outil appelle.
- [Utiliser Terraform ou OpenTofu](/docs/automation/terraform) : la surface infrastructure-as-code.
- [Personal Access Token](/docs/account-management/personal-access-token) et [jetons d'équipe](/docs/troops/tokens) : les identifiants que le serveur utilise.