Connecteur MCP

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

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

1. La création de l'agent déclare à quels serveurs MCP 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 coffre-fort préenregistré (voir S'authentifier avec des coffres-forts).

Cette séparation permet de garder les secrets hors des définitions d'agent réutilisables tout en laissant chaque session s'authentifier avec ses propres identifiants.



Déclarer des 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.

AGENT_ID=$(ant beta:agents create --transform id --raw-output < github-assistant.agent.yaml)

name: GitHub Assistant
model:
  id: claude-opus-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'agent comportant des serveurs non référencés ou des toolsets orphelins.



Configurer quels outils MCP sont 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 dans 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 activer uniquement 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 examiniez.

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 des sorties d'outils MCP

Lorsqu'une sortie d'outil MCP dépasse 100 000 caractères (environ 25 000 tokens), elle est automatiquement écrite dans un fichier du bac à sable. 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, passez vault_ids pour fournir les identifiants de vos serveurs MCP. Les coffres-forts sont des collections d'identifiants que vous enregistrez une fois et référencez par ID. Consultez S'authentifier avec des coffres-forts pour savoir comment créer des coffres-forts 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, donc le coffre-fort doit contenir un identifiant dont le mcp_server_url fait référence au 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 mis en minuscules, ports par défaut et barres obliques finales supprimés), de sorte que les 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 aucune correspondance n'est trouvée, 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 session ne valide pas 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 supplémentaire suite à cette erreur, de déclencher une rotation des identifiants, ou de laisser la session continuer sans les outils du serveur concerné. La connexion est retentée lors de la prochaine transition de session.status_idle à session.status_running.



Prochaines étapes