# Mode client

Le mode client est le miroir du [mode serveur](/fr/docs/mcp-server) : au lieu qu'un assistant extérieur interroge vos données, ce sont vos propres [agents](/fr/docs/ai-agents) qui appellent des outils hébergés ailleurs — recherche web, récupération de documents, ou tout ce qu'un serveur MCP externe publie.

Contrairement au mode serveur, celui-ci **requiert `AI_PROVIDER`**. Sovrium est ici l'appelant : un modèle doit donc tourner de votre côté pour décider quand un outil vaut la peine d'être invoqué.

## Déclarer les serveurs externes

Les serveurs relèvent de l'opérateur, pas du schéma — une URL et un identifiant sont des faits de déploiement. `MCP_CLIENT_SERVERS` est une liste séparée par des virgules, et l'authentification de chaque entrée est configurée par sa **position, indexée à partir de 1**, dans cette liste :

```bash
MCP_CLIENT_SERVERS=https://search.example.com/mcp,https://docs.example.com/mcp

MCP_AUTH_TYPE_1=bearer
MCP_AUTH_TOKEN_1=sk-...

MCP_AUTH_TYPE_2=header
MCP_AUTH_HEADER_2=X-Api-Key
MCP_AUTH_TOKEN_2=...
```

| Variable              | Valeurs                       | Signification                                                     |
| --------------------- | ----------------------------- | ----------------------------------------------------------------- |
| `MCP_CLIENT_SERVERS`  | URL séparées par des virgules | Les serveurs externes. Non définie, le mode client est désactivé. |
| `MCP_AUTH_TYPE_{N}`   | `bearer`, `header`, `none`    | Comment s'authentifier au serveur _N_. Vaut `none` par défaut.    |
| `MCP_AUTH_TOKEN_{N}`  | chaîne                        | Le secret envoyé au serveur _N_.                                  |
| `MCP_AUTH_HEADER_{N}` | nom d'en-tête                 | Quel en-tête le porte, quand le type vaut `header`.               |

:::callout
**L'index est positionnel : réordonner la liste redirige vos secrets.** Insérer un serveur en tête de `MCP_CLIENT_SERVERS` décale d'un cran tous les suffixes `_{N}` suivants, envoyant silencieusement le jeton du serveur 1 vers une autre origine. Ajoutez en fin de liste plutôt que d'insérer, et revérifiez la numérotation à chaque modification.
:::

## Restreindre un agent

Le bloc `mcp` d'un agent est une liste blanche appliquée au catalogue d'outils découvert. Il répond à « lesquels _cet_ agent peut-il utiliser », pas à « quels serveurs existent ».

```yaml
agents:
  - name: research-agent
    role: analyst
    systemPrompt: Research topics using approved external tools. Always cite sources.
    tools:
      tables: [findings]
      actions: [record.create, record.read]
    mcp:
      allowedTools: [web-search]
```

| Propriété          | Effet                                                                                   |
| ------------------ | --------------------------------------------------------------------------------------- |
| `mcp.allowedTools` | Noms d'outils externes que cet agent peut invoquer. Omis, tout le catalogue est permis. |

Deux listes blanches entrent alors en jeu et elles ne se recouvrent pas. `tools` délimite ce que l'agent peut faire **à l'intérieur** de Sovrium — ses tables et ses [actions](/fr/docs/agent-tools). `mcp.allowedTools` délimite ce qu'il peut atteindre **à l'extérieur**. Un agent peut être en lecture seule en interne et chercher malgré tout sur le web, ou l'inverse.

:::callout
**Un nom d'outil non reconnu est ignoré, pas rejeté.** `allowedTools` est filtré contre le catalogue découvert : une faute de frappe — `web_search` pour `web-search` — produit silencieusement un agent sans aucun outil externe plutôt qu'une erreur de validation. Confirmez les noms réels via `/api/ai/mcp/client/tools` avant de vous fier à une liste.
:::

## Inspecter ce qui est disponible

Deux points de terminaison en lecture seule permettent de vérifier le câblage sans solliciter de modèle. Les deux répondent `404` avec `{ "enabled": false }` quand `MCP_CLIENT_SERVERS` n'est pas définie : « désactivé » se distingue donc de « route absente ».

```bash
curl https://votre-app.example.com/api/ai/mcp/client/status
```

```json
{
  "enabled": true,
  "servers": [
    { "url": "https://search.example.com/mcp", "authType": "bearer", "status": "connecting" }
  ]
}
```

Les jetons ne sont jamais renvoyés — le résumé porte l'URL, le _type_ d'authentification et le nom d'en-tête, et rien de secret.

```bash
curl https://votre-app.example.com/api/ai/mcp/client/tools
```

Le catalogue d'outils démarre avec `web-search` et `document-fetch`, et la véritable découverte par `tools/list` le remplace dès qu'un serveur configuré est joignable. Ce sont ces noms initiaux qu'une entrée `allowedTools` doit reprendre aujourd'hui.

## Appeler un agent

`POST /api/agents/{name}/chat` transmet un message au fournisseur avec le catalogue d'outils filtré de cet agent, et renvoie une enveloppe `{ "reply": … }`. L'exécution est délibérément tolérante : si un serveur externe est injoignable ou qu'un appel d'outil échoue, le modèle répond quand même en texte plutôt que de faire échouer la requête. Un agent dépendant d'un serveur instable se dégrade en une réponse moins bonne, pas en une erreur 500.

## Pages associées

- [Présentation de MCP](/fr/docs/mcp-integration) — mode serveur ou mode client.
- [Présentation des agents](/fr/docs/ai-agents) — les agents qui appellent.
- [Outils](/fr/docs/agent-tools) — la liste blanche interne que celle-ci complète.
- [Fournisseurs d'IA](/fr/docs/ai-providers) — l'`AI_PROVIDER` dont le mode client a besoin.
- [Mode serveur](/fr/docs/mcp-server) — le sens inverse.