Connecteur MCP

La fonctionnalité de connecteur Model Context Protocol (MCP) de Claude vous permet de vous connecter à des serveurs MCP distants directement à partir de l'API Messages sans client MCP séparé.

Fonctionnalités clés

• Intégration API directe : Connectez-vous à des serveurs MCP sans implémenter un client MCP
• Support des appels d'outils : Accédez aux outils MCP via l'API Messages
• Configuration flexible des outils : Activez tous les outils, créez une liste blanche d'outils spécifiques ou créez une liste noire d'outils indésirables
• Configuration par outil : Configurez les outils individuels avec des paramètres personnalisés
• Authentification OAuth : Support des jetons Bearer OAuth pour les serveurs authentifiés
• Serveurs multiples : Connectez-vous à plusieurs serveurs MCP dans une seule requête

Limitations

• De l'ensemble des fonctionnalités de la spécification MCP, seuls les appels d'outils sont actuellement pris en charge.
• Le serveur doit être exposé publiquement via HTTP (supporte à la fois les transports HTTP Streamable et SSE). Les serveurs STDIO locaux ne peuvent pas être connectés directement.
• Le connecteur MCP n'est actuellement pas pris en charge sur Amazon Bedrock et Google Vertex.

Utilisation du connecteur MCP dans l'API Messages

Le connecteur MCP utilise deux composants :

1. Définition du serveur MCP (tableau mcp_servers) : Définit les détails de connexion au serveur (URL, authentification)
2. Ensemble d'outils MCP (tableau tools) : Configure les outils à activer et comment les configurer

Exemple basique

Cet exemple active tous les outils d'un serveur MCP avec la configuration par défaut :

Configuration du serveur MCP

Chaque serveur MCP dans le tableau mcp_servers définit les détails de connexion :

{
  "type": "url",
  "url": "https://example-server.modelcontextprotocol.io/sse",
  "name": "example-mcp",
  "authorization_token": "YOUR_TOKEN"
}

Descriptions des champs

Configuration de l'ensemble d'outils MCP

L'MCPToolset se trouve dans le tableau tools et configure les outils du serveur MCP qui sont activés et comment ils doivent être configurés.

Structure basique

{
  "type": "mcp_toolset",
  "mcp_server_name": "example-mcp",
  "default_config": {
    "enabled": true,
    "defer_loading": false
  },
  "configs": {
    "specific_tool_name": {
      "enabled": true,
      "defer_loading": true
    }
  }
}

Descriptions des champs

Options de configuration des outils

Chaque outil (qu'il soit configuré dans default_config ou dans configs) prend en charge les champs suivants :

Fusion de configuration

Les valeurs de configuration fusionnent avec cette priorité (la plus élevée à la plus basse) :

1. Paramètres spécifiques à l'outil dans configs
2. default_config au niveau de l'ensemble
3. Valeurs par défaut du système

Exemple :

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "enabled": false
    }
  }
}

Résultat :

• search_events : enabled: false (de configs), defer_loading: true (de default_config)
• Tous les autres outils : enabled: true (valeur par défaut du système), defer_loading: true (de default_config)

Modèles de configuration courants

Activer tous les outils avec la configuration par défaut

Le modèle le plus simple - activez tous les outils d'un serveur :

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
}

Liste blanche - Activer uniquement des outils spécifiques

Définissez enabled: false comme valeur par défaut, puis activez explicitement des outils spécifiques :

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false
  },
  "configs": {
    "search_events": {
      "enabled": true
    },
    "create_event": {
      "enabled": true
    }
  }
}

Liste noire - Désactiver des outils spécifiques

Activez tous les outils par défaut, puis désactivez explicitement les outils indésirables :

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "configs": {
    "delete_all_events": {
      "enabled": false
    },
    "share_calendar_publicly": {
      "enabled": false
    }
  }
}

Mixte - Liste blanche avec configuration par outil

Combinez la liste blanche avec une configuration personnalisée pour chaque outil :

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false,
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "enabled": true,
      "defer_loading": false
    },
    "list_events": {
      "enabled": true
    }
  }
}

Dans cet exemple :

• search_events est activé avec defer_loading: false
• list_events est activé avec defer_loading: true (hérité de default_config)
• Tous les autres outils sont désactivés

Règles de validation

L'API applique ces règles de validation :

• Le serveur doit exister : Le mcp_server_name dans un MCPToolset doit correspondre à un serveur défini dans le tableau mcp_servers
• Le serveur doit être utilisé : Chaque serveur MCP défini dans mcp_servers doit être référencé par exactement un MCPToolset
• Ensemble d'outils unique par serveur : Chaque serveur MCP ne peut être référencé que par un seul MCPToolset
• Noms d'outils inconnus : Si un nom d'outil dans configs n'existe pas sur le serveur MCP, un avertissement backend est enregistré mais aucune erreur n'est retournée (les serveurs MCP peuvent avoir une disponibilité d'outils dynamique)

Types de contenu de réponse

Lorsque Claude utilise des outils MCP, la réponse inclura deux nouveaux types de blocs de contenu :

Bloc d'utilisation d'outil MCP

{
  "type": "mcp_tool_use",
  "id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "name": "echo",
  "server_name": "example-mcp",
  "input": { "param1": "value1", "param2": "value2" }
}

Bloc de résultat d'outil MCP

{
  "type": "mcp_tool_result",
  "tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "is_error": false,
  "content": [
    {
      "type": "text",
      "text": "Hello"
    }
  ]
}

Serveurs MCP multiples

Vous pouvez vous connecter à plusieurs serveurs MCP en incluant plusieurs définitions de serveur dans mcp_servers et un MCPToolset correspondant pour chacun dans le tableau tools :

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "user",
      "content": "Use tools from both mcp-server-1 and mcp-server-2 to complete this task"
    }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example1.com/sse",
      "name": "mcp-server-1",
      "authorization_token": "TOKEN1"
    },
    {
      "type": "url",
      "url": "https://mcp.example2.com/sse",
      "name": "mcp-server-2",
      "authorization_token": "TOKEN2"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-1"
    },
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-2",
      "default_config": {
        "defer_loading": true
      }
    }
  ]
}

Authentification

Pour les serveurs MCP qui nécessitent une authentification OAuth, vous devrez obtenir un jeton d'accès. Le bêta du connecteur MCP prend en charge le passage d'un paramètre authorization_token dans la définition du serveur MCP. Les consommateurs d'API sont censés gérer le flux OAuth et obtenir le jeton d'accès avant d'effectuer l'appel API, ainsi que d'actualiser le jeton selon les besoins.

Obtention d'un jeton d'accès pour les tests

L'inspecteur MCP peut vous guider tout au long du processus d'obtention d'un jeton d'accès à des fins de test.

1. Exécutez l'inspecteur avec la commande suivante. Vous devez avoir Node.js installé sur votre machine.

   npx @modelcontextprotocol/inspector

2. Dans la barre latérale de gauche, pour "Type de transport", sélectionnez soit "SSE" soit "Streamable HTTP".

3. Entrez l'URL du serveur MCP.

4. Dans la zone de droite, cliquez sur le bouton "Open Auth Settings" après "Need to configure authentication?".

5. Cliquez sur "Quick OAuth Flow" et autorisez sur l'écran OAuth.

6. Suivez les étapes de la section "OAuth Flow Progress" de l'inspecteur et cliquez sur "Continue" jusqu'à atteindre "Authentication complete".

7. Copiez la valeur access_token.

Utilisation du jeton d'accès

Une fois que vous avez obtenu un jeton d'accès en utilisant l'un des flux OAuth ci-dessus, vous pouvez l'utiliser dans votre configuration de serveur MCP :

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "authenticated-server",
      "authorization_token": "YOUR_ACCESS_TOKEN_HERE"
    }
  ]
}

Pour des explications détaillées du flux OAuth, consultez la section Autorisation dans la spécification MCP.

Guide de migration

Si vous utilisez l'en-tête bêta dépréciée mcp-client-2025-04-04, suivez ce guide pour migrer vers la nouvelle version.

Changements clés

1. Nouvel en-tête bêta : Passez de mcp-client-2025-04-04 à mcp-client-2025-11-20
2. Configuration des outils déplacée : La configuration des outils se trouve maintenant dans le tableau tools en tant qu'objets MCPToolset, et non dans la définition du serveur MCP
3. Configuration plus flexible : Le nouveau modèle prend en charge la liste blanche, la liste noire et la configuration par outil

Étapes de migration

Avant (dépréciée) :

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1000,
  "messages": [...],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["tool1", "tool2"]
      }
    }
  ]
}

Après (actuelle) :

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1000,
  "messages": [...],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "example-mcp",
      "default_config": {
        "enabled": false
      },
      "configs": {
        "tool1": {
          "enabled": true
        },
        "tool2": {
          "enabled": true
        }
      }
    }
  ]
}

Modèles de migration courants

Version dépréciée : mcp-client-2025-04-04

La version précédente du connecteur MCP incluait la configuration des outils directement dans la définition du serveur MCP :

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["example_tool_1", "example_tool_2"]
      }
    }
  ]
}

Descriptions des champs dépréciés

Collez-la dans le champ authorization_token de votre configuration de serveur MCP.