# Serveur MCP Agent Builder

Agent Builder expose un **serveur MCP** (Model Context Protocol) authentifié : des clients IA externes et agents de code — Claude Code, Claude Desktop, Codex, ou tout client compatible MCP — peuvent créer, inspecter, déboguer et tester des workflows dans votre espace de travail, et gérer des credentials, depuis l'extérieur de l'application.

- **Endpoint** : `<url-de-votre-backend>/api/v1/mcp-server`
- **Transport** : MCP streamable HTTP (JSON-RPC sans état)
- **Authentification** : `Authorization: Bearer <token>` — un token API personnel (recommandé) ou un JWT de connexion

## 1. Créer un token API personnel

Les tokens API sont des identifiants longue durée liés à votre compte. Créez-en un (le secret n'est affiché qu'**une seule fois**) :

```bash
curl -X POST <backend>/api/v1/api-tokens/ \
  -H "Authorization: Bearer <votre-JWT-de-connexion>" \
  -H "Content-Type: application/json" \
  -d '{"name": "claude-code", "expires_in_days": 90}'
```

La réponse contient `"token": "abp_…"` — conservez-le en lieu sûr. Vous pouvez lister vos tokens (`GET /api/v1/api-tokens/`, métadonnées uniquement) et en révoquer un à tout moment (`DELETE /api/v1/api-tokens/{public_id}`).

## 2. Connecter un client

**Claude Code** (CLI) :

```bash
claude mcp add --transport http agent-builder \
  <backend>/api/v1/mcp-server \
  --header "Authorization: Bearer abp_…"
```

ou avec un fichier `.mcp.json` de projet (à garder hors de git — il contient votre token) :

```json
{
  "mcpServers": {
    "agent-builder": {
      "type": "http",
      "url": "<backend>/api/v1/mcp-server",
      "headers": { "Authorization": "Bearer abp_…" }
    }
  }
}
```

Tout autre client MCP fonctionne de la même façon : endpoint streamable HTTP + l'en-tête Authorization. Pour travailler dans un **espace d'équipe**, envoyez aussi l'en-tête `X-Workspace-Team : <public-id-de-l-équipe>`.

## 3. Outils disponibles

| Domaine | Outils |
| --- | --- |
| Workflows | `list_workflows`, `get_workflow`, `create_workflow`, `update_workflow`, `validate_workflow`, `test_workflow` |
| Exécutions | `list_executions`, `get_execution` |
| Connaissance plateforme | `list_node_types`, `get_node_type`, `search_docs` |
| Credentials | `list_credentials`, `create_credential`, `start_credential_oauth`, `assign_credential_to_node`, `test_credential` |

Les graphes utilisent le format de l'éditeur : `nodes: [{id, type, position, data}]` et `edges: [{source, target, sourceHandle?}]`. Interrogez le serveur lui-même pour les détails : `search_docs("templates")`, `get_node_type("agent")`.

## 4. Exemple

Demandez par exemple à votre agent connecté :

> « Crée un workflow qui surveille les emails de support entrants, classe chaque demande, génère une réponse suggérée et envoie les urgences sur Slack. Crée les credentials manquants et dis-moi quelles étapes d'autorisation je dois compléter. »

L'agent inspectera le registre de nœuds, construira et validera le workflow dans votre espace, créera les fiches credentials, et vous donnera les liens d'autorisation OAuth à terminer dans votre navigateur.

## Modèle de sécurité

- **Authentification obligatoire** — chaque appel exige un Bearer token valide ; sans lui : 401.
- **Tokens hachés au repos** (SHA-256). Le secret n'est montré qu'à la création ; ensuite seul un préfixe d'affichage est conservé. Les tokens supportent une date d'expiration et la révocation immédiate.
- **Isolation des espaces** — le serveur n'opère que sur les workflows et credentials accessibles à l'utilisateur authentifié ; les espaces d'équipe appliquent les rôles d'équipe.
- **Les secrets ne sortent jamais du serveur** — les outils credentials ne renvoient que des métadonnées (nom, provider, statut, expiration, usage). Les valeurs secrètes sont en écriture seule : chiffrées à l'arrivée (Vault ou Fernet) et jamais resérialisées, ni vers les clients MCP ni vers qui que ce soit.
- **OAuth reste côté serveur** — `start_credential_oauth` renvoie une URL d'autorisation à ouvrir dans le navigateur ; les tokens d'accès et de refresh sont stockés côté serveur, jamais transmis au client MCP.
- **Auditabilité** — les opérations sur les credentials sont tracées dans le journal d'audit.

Recommandations : exposez le backend en **HTTPS** en production, créez un token par client avec expiration, révoquez les tokens inutilisés, et ne committez jamais un token (ajoutez `.mcp.json` au `.gitignore`).

---

*Source: https://agentbuilder.systalink.sn/docs/mcp-server — human documentation.*
*Other language: [/docs-md/en/mcp-server.md](/docs-md/en/mcp-server.md).*
*Machine-readable index: [/llms.txt](/llms.txt).*