--- title: Connecteur MCP url: https://platform.claude.com/docs/fr/managed-agents/mcp-connector description: Connectez des serveurs MCP à vos agents pour accéder à des outils et à des sources de données externes. featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- Claude Managed Agents prend en charge la connexion de serveurs [« Model Context Protocol », ou MCP](https://modelcontextprotocol.io) à 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](https://platform.claude.com/docs/fr/managed-agents/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` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) lors de la création d'un agent. Chaque serveur nécessite un `type` (csharp, go: `Type`), un `name` (csharp, go: `Name`) unique et une `url` (csharp: `Url`; go: `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` (csharp, go: `Tools`). Le `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) du toolset doit correspondre au `name` (csharp, go: `Name`) du serveur. ```bash cURL curl -sS --fail-with-body https://api.anthropic.com/v1/agents \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ -d '{ "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"} ] }' ``` ```bash CLI ant apply github-assistant.md ``` ```markdown --- 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 --- ``` ```python Python agent = client.beta.agents.create( 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"}, ], ) ``` ```typescript TypeScript const agent = await client.beta.agents.create({ 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" } ] }); ``` ```csharp C# var agent = await client.Beta.Agents.Create(new() { Name = "GitHub Assistant", Model = BetaManagedAgentsModel.ClaudeOpus5_5, McpServers = [ new() { Type = "url", Name = "github", Url = "https://api.githubcopilot.com/mcp/" }, ], Tools = [ new BetaManagedAgentsAgentToolset20260401Params { Type = "agent_toolset_20260401", }, new BetaManagedAgentsMcpToolsetParams { Type = "mcp_toolset", McpServerName = "github" }, ], }); ``` ```go Go agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ Name: "GitHub Assistant", Model: anthropic.BetaManagedAgentsModelConfigParams{ ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5, }, MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{{ Type: anthropic.BetaManagedAgentsURLMCPServerParamsTypeURL, Name: "github", URL: "https://api.githubcopilot.com/mcp/", }}, Tools: []anthropic.BetaAgentNewParamsToolUnion{ { OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, }, }, { OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{ Type: anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset, MCPServerName: "github", }, }, }, }) if err != nil { panic(err) } ``` ```java Java var agent = client.beta().agents().create( AgentCreateParams.builder() .name("GitHub Assistant") .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5) .addMcpServer( BetaManagedAgentsUrlMcpServerParams.builder() .type(BetaManagedAgentsUrlMcpServerParams.Type.URL) .name("github") .url("https://api.githubcopilot.com/mcp/") .build() ) .addTool( BetaManagedAgentsAgentToolset20260401Params.builder() .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) .build() ) .addTool( BetaManagedAgentsMcpToolsetParams.builder() .type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET) .mcpServerName("github") .build() ) .build() ); ``` ```php PHP $agent = $client->beta->agents->create( name: 'GitHub Assistant', model: 'claude-opus-5-5', mcpServers: [ BetaManagedAgentsURLMCPServerParams::with( type: 'url', name: 'github', url: 'https://api.githubcopilot.com/mcp/', ), ], tools: [ BetaManagedAgentsAgentToolset20260401Params::with( type: 'agent_toolset_20260401', ), BetaManagedAgentsMCPToolsetParams::with( type: 'mcp_toolset', mcpServerName: 'github', ), ], ); ``` ```ruby Ruby agent = client.beta.agents.create( 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"} ] ) ``` Le toolset MCP utilise par défaut une politique de permission `always_ask`, qui exige l'approbation de l'utilisateur avant chaque appel d'outil. Consultez les [politiques de permission](https://platform.claude.com/docs/fr/managed-agents/permission-policies) pour configurer ce comportement. ### Référence du champ `mcp_servers` Chaque entrée du tableau `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) définit une connexion. | Champ | Description | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` (csharp, go: `Type`) | Obligatoire. Doit être `"url"`. | | `name` (csharp, go: `Name`) | Obligatoire. Un nom unique pour ce serveur au sein de l'agent (1 à 255 caractères). Utilisé comme `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) dans le tableau `tools` (csharp, go: `Tools`) et exposé dans les événements d'outils MCP du [flux d'événements de session](https://platform.claude.com/docs/fr/managed-agents/events-and-streaming). | | `url` (csharp: `Url`; go: `URL`) | Obligatoire. Le point de terminaison du serveur MCP distant (jusqu'à 2 048 caractères). Consultez [Types de serveurs MCP pris en charge](https://platform.claude.com/docs/fr/managed-agents/reference#supported-mcp-server-types) pour les exigences de transport. | 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` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) doit être référencée par un `mcp_toolset` dans le tableau `tools` (csharp, go: `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` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`) et un tableau `configs` (csharp, go: `Configs`), appliqués aux outils exposés par le serveur MCP. Chaque entrée `configs` (csharp, go: `Configs`) accepte uniquement `name` (csharp, go: `Name`), `enabled` (csharp, go: `Enabled`) et `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`). Contrairement aux entrées du toolset d'agent intégré, les entrées d'outils MCP n'acceptent pas de champ `type` (csharp, go: `Type`), et les [paramètres web](https://platform.claude.com/docs/fr/managed-agents/tools-web-restrictions#settings) disponibles sur `web_search` et `web_fetch` ne s'appliquent pas aux outils MCP. Le `name` (csharp, go: `Name`) de chaque entrée `configs` (csharp, go: `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 : ```json { "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 : ```json { "type": "mcp_toolset", "mcp_server_name": "github", "configs": [{ "name": "delete_repository", "enabled": false }] } ``` Consultez [configuration de l'ensemble d'outils](https://platform.claude.com/docs/fr/managed-agents/tools#configuring-the-toolset) pour le modèle général `default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`) / `configs` (csharp, go: `Configs`), et [autorisations des ensembles d'outils MCP](https://platform.claude.com/docs/fr/managed-agents/permission-policies#mcp-toolset-permissions) pour définir `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`) 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` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`) pour fournir les identifiants de vos serveurs MCP. Les vaults sont des collections d'identifiants que vous enregistrez une seule fois et référencez par ID. Consultez [S'authentifier avec des coffres-forts](https://platform.claude.com/docs/fr/managed-agents/vaults) pour savoir comment créer des vaults et gérer les identifiants. Avec un [environnement](https://platform.claude.com/docs/fr/managed-agents/environments#networking) `limited`, la création de la session échoue avec une erreur 400 lorsque l'agent déclare un serveur MCP dont l'hôte ne figure pas dans `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). Définir `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) sur `true` dans la configuration réseau de l'environnement désactive cette vérification. ```bash cURL curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ -d '{ "agent": "'"$agent_id"'", "environment_id": "'"$environment_id"'", "vault_ids": ["'"$vault_id"'"] }' ``` ```bash CLI ant beta:sessions create \ --agent "$AGENT_ID" \ --environment-id "$ENVIRONMENT_ID" \ --vault-id "$VAULT_ID" ``` ```python Python session = client.beta.sessions.create( agent=agent.id, environment_id=environment.id, vault_ids=[vault.id], ) ``` ```typescript TypeScript const session = await client.beta.sessions.create({ agent: agent.id, environment_id: environment.id, vault_ids: [vault.id] }); ``` ```csharp C# var session = await client.Beta.Sessions.Create(new() { Agent = agent.ID, EnvironmentID = environment.ID, VaultIds = [vault.ID], }); ``` ```go Go session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{ Agent: anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)}, EnvironmentID: environment.ID, VaultIDs: []string{vault.ID}, }) if err != nil { panic(err) } ``` ```java Java var session = client.beta().sessions().create( SessionCreateParams.builder() .agent(agent.id()) .environmentId(environment.id()) .addVaultId(vault.id()) .build() ); ``` ```php PHP $session = $client->beta->sessions->create( agent: $agent->id, environmentID: $environment->id, vaultIDs: [$vault->id], ); ``` ```ruby Ruby session = client.beta.sessions.create( agent: agent.id, environment_id: environment.id, vault_ids: [vault.id] ) ``` Les identifiants sont associés par URL : le vault doit donc contenir un identifiant dont le `mcp_server_url` (java: `mcpServerUrl`; php: `mcpServerURL`; csharp: `McpServerUrl`; go: `MCPServerURL`) désigne le même serveur que l'`url` (csharp: `Url`; go: `URL`) déclarée dans `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`). Les deux URL sont normalisées avant la comparaison (schéma et hôte mis en minuscules, ports par défaut et barres obliques finales supprimés) : des différences de casse de l'hôte, un port par défaut ou une barre oblique finale n'empêchent donc pas la correspondance, contrairement à un chemin, un sous-domaine ou un port non standard différent. Si aucun identifiant ne correspond, la connexion est tentée sans authentification. Consultez [Ajouter un identifiant](https://platform.claude.com/docs/fr/managed-agents/vaults#add-a-credential) 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. Elle vérifie en revanche l'hôte de chaque serveur déclaré par rapport à la configuration réseau de l'environnement : avec un environnement `limited`, la création de la session échoue avec une erreur 400 lorsqu'un hôte n'est pas autorisé, comme décrit dans [Fournir l'authentification à la création de la session](https://platform.claude.com/docs/fr/managed-agents/mcp-connector#provide-authentication-at-session-creation). Si un serveur MCP est injoignable ou rejette l'identifiant fourni, la session démarre tout de même et l'interaction reste possible. Un événement [`session.error`](https://platform.claude.com/docs/fr/managed-agents/reference#event-types) est émis avec le `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) du serveur concerné et un `retry_status` (java, php: `retryStatus`; csharp, go: `RetryStatus`) : | Type d'erreur | Signification | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `mcp_connection_failed_error` | Le serveur MCP n'a pas pu être atteint (erreur réseau, délai d'attente dépassé ou échec HTTP non lié à l'authentification). | | `mcp_authentication_failed_error` | L'authentification auprès du serveur MCP a échoué : le serveur a rejeté l'identifiant du vault attaché, a exigé une authentification alors qu'aucun identifiant correspondant n'était configuré, ou le renouvellement d'un jeton OAuth a échoué. | 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 Contrôlez quand les outils d'agent et MCP s'exécutent. Envoyez des événements, diffusez les réponses en streaming, et interrompez ou redirigez votre session en cours d'exécution. Exigences de transport pour les serveurs MCP distants.