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é.

Cette séparation permet de garder les secrets hors des définitions d'agent réutilisables tout en permettant à chaque session de 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 \
  --name "GitHub Assistant" \
  --model claude-opus-4-8 \
  --mcp-server '{type: url, name: github, url: "https://api.githubcopilot.com/mcp/"}' \
  --tool '{type: agent_toolset_20260401}' \
  --tool '{type: mcp_toolset, mcp_server_name: github}' \
  --transform id --raw-output)



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 la même structure default_config et configs que le toolset d'agent intégré, appliquée aux outils exposés par le serveur 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 configuration du 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 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 lors de la création de session

Lors du démarrage d'une session, passez vault_ids pour fournir des identifiants à 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 correspond exactement à l'url déclarée dans mcp_servers. Si aucun 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 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 ultérieure 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.



Étapes suivantes