Connecteur MCP

Claude Managed Agents prend en charge la connexion de serveurs « Model Context Protocol », ou MCP à vos agents. Cela donne à l'agent accès à des outils, sources de données et services externes via un protocole standardisé.

La configuration MCP est répartie en deux étapes :

1. La création de l'agent déclare les serveurs MCP auxquels l'agent se connecte, par nom et URL.
2. La création de la session fournit l'authentification pour ces serveurs en référençant un « vault » (coffre-fort) préenregistré (voir S'authentifier avec des vaults).

Cette séparation maintient les secrets hors des définitions d'agents réutilisables tout en permettant à chaque session de s'authentifier avec ses propres identifiants.

Déclarer les serveurs MCP sur l'agent

Spécifiez les serveurs MCP dans le tableau mcp_servers lors de la création d'un agent. Chaque serveur nécessite un type, un name unique et une url. Aucun jeton d'authentification n'est fourni à ce stade.

Chaque serveur déclaré nécessite également une entrée mcp_toolset correspondante dans le tableau tools. Le mcp_server_name du toolset doit correspondre au name du serveur.

ant apply github-assistant.md

---
name: GitHub Assistant
model: claude-opus-5-5
mcp_servers:
  - type: url
    name: github
    url: https://api.githubcopilot.com/mcp/
tools:
  - type: agent_toolset_20260401
  - type: mcp_toolset
    mcp_server_name: github
---

Référence du champ mcp_servers

Chaque entrée du tableau mcp_servers définit une connexion.

Contraintes :

• Un agent peut déclarer jusqu'à 20 serveurs MCP. Les noms de serveurs doivent être uniques au sein du tableau.
• Chaque entrée mcp_servers doit être référencée par un mcp_toolset dans le tableau tools, et chaque mcp_toolset doit référencer un serveur déclaré. L'API rejette les définitions d'agents comportant des serveurs non référencés ou des toolsets orphelins.

Configurer les outils MCP disponibles

L'entrée mcp_toolset prend en charge un objet default_config et un tableau configs, appliqués aux outils exposés par le serveur MCP. Chaque entrée configs accepte uniquement name, enabled et permission_policy. Contrairement aux entrées du toolset d'agent intégré, les entrées d'outils MCP ne prennent pas de champ type, et les paramètres web disponibles sur web_search et web_fetch ne s'appliquent pas aux outils MCP. Le name de chaque entrée configs est le nom brut de l'outil tel que rapporté par le serveur.

Par défaut, tous les outils exposés par le serveur MCP sont activés. Pour n'activer que des outils spécifiques, définissez default_config.enabled sur false et activez explicitement les outils souhaités :

{
  "type": "mcp_toolset",
  "mcp_server_name": "github",
  "default_config": { "enabled": false },
  "configs": [
    { "name": "get_issue", "enabled": true },
    { "name": "list_issues", "enabled": true },
    { "name": "add_issue_comment", "enabled": true }
  ]
}

Ce modèle est utile lorsqu'un serveur expose de nombreux outils mais que l'agent n'en a besoin que de quelques-uns, ou lorsque vous souhaitez que les outils ajoutés par l'opérateur du serveur restent désactivés jusqu'à ce que vous les ayez examinés.

Pour désactiver des outils spécifiques tout en gardant les autres activés, omettez default_config et définissez enabled: false sur les entrées individuelles :

{
  "type": "mcp_toolset",
  "mcp_server_name": "github",
  "configs": [{ "name": "delete_repository", "enabled": false }]
}

Consultez configurer le toolset pour le modèle général default_config / configs, et permissions du toolset MCP pour définir permission_policy sur les outils MCP et gérer les demandes de confirmation.

Gestion de la sortie des outils MCP

Lorsque la sortie d'un outil MCP dépasse 100 000 caractères (environ 25 000 tokens), elle est automatiquement écrite dans un fichier du sandbox. Le modèle reçoit un aperçu tronqué avec le chemin du fichier et peut lire le contenu complet à partir de là.

Fournir l'authentification à la création de la session

Lors du démarrage d'une session, transmettez vault_ids pour fournir les identifiants de vos serveurs MCP. Les vaults sont des collections d'identifiants que vous enregistrez une fois et référencez par ID. Consultez S'authentifier avec des vaults pour savoir comment créer des vaults et gérer les identifiants.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)

Les identifiants sont mis en correspondance par URL ; le vault doit donc contenir un identifiant dont le mcp_server_url désigne le même serveur que l'url déclarée dans mcp_servers. Les deux URL sont normalisées avant la mise en correspondance (schéma et hôte en minuscules, ports par défaut et barres obliques finales supprimés), de sorte que des différences de casse de l'hôte, un port par défaut ou une barre oblique finale n'empêchent pas la correspondance ; un chemin, un sous-domaine ou un port non standard différent l'empêche. Si aucun identifiant ne correspond, la connexion est tentée sans authentification. Consultez Ajouter un identifiant pour les types d'identifiants static_bearer et mcp_oauth.

Gérer les échecs de connexion et d'authentification

La création de la session ne valide ni la connectivité MCP ni les identifiants. Si un serveur MCP est inaccessible ou rejette l'identifiant fourni, la session démarre quand même et l'interaction reste possible. Un événement session.error est émis avec le mcp_server_name du serveur concerné et un retry_status :

Vous pouvez décider de bloquer toute interaction ultérieure en cas d'erreur, de déclencher une rotation des identifiants ou de laisser la session se poursuivre sans les outils du serveur concerné. La connexion est retentée lors de la prochaine transition de session.status_idle à session.status_running.

Étapes suivantes