--- title: MCP-Connector url: https://platform.claude.com/docs/de/managed-agents/mcp-connector description: Verbinde MCP-Server mit deinen Agenten, um auf externe Tools und Datenquellen zuzugreifen. 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 unterstützt das Verbinden von [„Model Context Protocol“-Servern, oder MCP-Servern](https://modelcontextprotocol.io), mit deinen Agenten. Dadurch erhält der Agent über ein standardisiertes Protokoll Zugriff auf externe Tools, Datenquellen und Dienste. Die MCP-Konfiguration ist auf zwei Schritte aufgeteilt: 1. **Die Agent-Erstellung** deklariert anhand von Name und URL, mit welchen MCP-Servern sich der Agent verbindet. 2. **Die Session-Erstellung** liefert die Authentifizierung für diese Server, indem sie auf einen vorab registrierten Vault verweist (siehe [Mit Vaults authentifizieren](https://platform.claude.com/docs/de/managed-agents/vaults)). Diese Trennung hält Geheimnisse aus wiederverwendbaren Agent-Definitionen heraus und ermöglicht es gleichzeitig jeder Session, sich mit ihren eigenen Anmeldedaten zu authentifizieren. ## MCP-Server auf dem Agenten deklarieren Gib MCP-Server beim Erstellen eines Agenten im Array `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) an. Jeder Server benötigt einen `type` (csharp, go: `Type`), einen eindeutigen `name` (csharp, go: `Name`) und eine `url` (csharp: `Url`; go: `URL`). In diesem Schritt werden keine Authentifizierungstoken bereitgestellt. Jeder deklarierte Server benötigt außerdem einen passenden `mcp_toolset`-Eintrag im Array `tools` (csharp, go: `Tools`). Der `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) des Toolsets muss mit dem `name` (csharp, go: `Name`) des Servers übereinstimmen. ```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"} ] ) ``` Das MCP-Toolset verwendet standardmäßig die Berechtigungsrichtlinie `always_ask`, die vor jedem Tool-Aufruf eine Genehmigung durch den Benutzer erfordert. Siehe [Berechtigungsrichtlinien](https://platform.claude.com/docs/de/managed-agents/permission-policies), um dieses Verhalten zu konfigurieren. ### Feldreferenz für `mcp_servers` Jeder Eintrag im Array `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) definiert eine Verbindung. | Feld | Beschreibung | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` (csharp, go: `Type`) | Erforderlich. Muss `"url"` sein. | | `name` (csharp, go: `Name`) | Erforderlich. Ein innerhalb des Agenten eindeutiger Name für diesen Server (1–255 Zeichen). Wird als `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) im Array `tools` (csharp, go: `Tools`) verwendet und bei MCP-Tool-Events im [Session-Event-Stream](https://platform.claude.com/docs/de/managed-agents/events-and-streaming) angezeigt. | | `url` (csharp: `Url`; go: `URL`) | Erforderlich. Der Endpunkt des entfernten MCP-Servers (bis zu 2.048 Zeichen). Siehe [Unterstützte MCP-Servertypen](https://platform.claude.com/docs/de/managed-agents/reference#supported-mcp-server-types) für Transportanforderungen. | Einschränkungen: * Ein Agent kann bis zu 20 MCP-Server deklarieren. Servernamen müssen innerhalb des Arrays eindeutig sein. * Jeder Eintrag in `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) muss von einem `mcp_toolset` im Array `tools` (csharp, go: `Tools`) referenziert werden, und jedes `mcp_toolset` muss auf einen deklarierten Server verweisen. Die API lehnt Agentendefinitionen mit nicht referenzierten Servern oder verwaisten Toolsets ab. ## Konfigurieren, welche MCP-Tools verfügbar sind Der `mcp_toolset`-Eintrag unterstützt ein `default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`)-Objekt und ein `configs` (csharp, go: `Configs`)-Array, die auf die vom MCP-Server bereitgestellten Tools angewendet werden. Jeder `configs` (csharp, go: `Configs`)-Eintrag akzeptiert nur `name` (csharp, go: `Name`), `enabled` (csharp, go: `Enabled`) und `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`). Anders als Einträge im integrierten Agent-Toolset haben MCP-Tool-Einträge kein `type` (csharp, go: `Type`)-Feld, und die für `web_search` und `web_fetch` verfügbaren [Web-Einstellungen](https://platform.claude.com/docs/de/managed-agents/tools-web-restrictions#settings) gelten nicht für MCP-Tools. Der `name` (csharp, go: `Name`) in jedem `configs` (csharp, go: `Configs`)-Eintrag ist der reine Tool-Name, wie er vom Server gemeldet wird. Standardmäßig sind alle vom MCP-Server bereitgestellten Tools aktiviert. Um nur bestimmte Tools zu aktivieren, setze `default_config.enabled` auf `false` und aktiviere explizit die gewünschten Tools: ```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 } ] } ``` Dieses Muster ist nützlich, wenn ein Server viele Tools bereitstellt, der Agent aber nur wenige benötigt, oder wenn du möchtest, dass vom Serverbetreiber hinzugefügte Tools deaktiviert bleiben, bis du sie überprüft hast. Um bestimmte Tools zu deaktivieren und die übrigen aktiviert zu lassen, lass `default_config` weg und setze `enabled: false` bei einzelnen Einträgen: ```json { "type": "mcp_toolset", "mcp_server_name": "github", "configs": [{ "name": "delete_repository", "enabled": false }] } ``` Siehe [Konfigurieren des Toolsets](https://platform.claude.com/docs/de/managed-agents/tools#configuring-the-toolset) für das allgemeine `default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`) / `configs` (csharp, go: `Configs`)-Muster und [MCP-Toolset-Berechtigungen](https://platform.claude.com/docs/de/managed-agents/permission-policies#mcp-toolset-permissions) für das Festlegen von `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`) bei MCP-Tools und den Umgang mit Bestätigungsanfragen. ### Umgang mit MCP-Tool-Ausgaben Wenn die Ausgabe eines MCP-Tools 100.000 Zeichen (etwa 25.000 Token) überschreitet, wird sie automatisch in eine Datei in der Sandbox geschrieben. Das Modell erhält eine gekürzte Vorschau mit dem Dateipfad und kann den vollständigen Inhalt von dort lesen. ## Authentifizierung bei der Session-Erstellung bereitstellen Übergib beim Starten einer Session `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`), um Anmeldedaten für deine MCP-Server bereitzustellen. Vaults sind Sammlungen von Anmeldedaten, die du einmal registrierst und per ID referenzierst. Siehe [Mit Vaults authentifizieren](https://platform.claude.com/docs/de/managed-agents/vaults), um zu erfahren, wie du Vaults erstellst und Anmeldedaten verwaltest. Bei einer `limited`-[Umgebung](https://platform.claude.com/docs/de/managed-agents/environments#networking) schlägt die Session-Erstellung mit einem 400-Fehler fehl, wenn der Agent einen MCP-Server deklariert, dessen Host nicht in `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) enthalten ist. Wenn du `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) in den Netzwerkeinstellungen der Umgebung auf `true` setzt, wird diese Prüfung deaktiviert. ```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] ) ``` Anmeldedaten werden anhand der URL zugeordnet, daher muss der Vault Anmeldedaten enthalten, deren `mcp_server_url` (java: `mcpServerUrl`; php: `mcpServerURL`; csharp: `McpServerUrl`; go: `MCPServerURL`) auf denselben Server verweist wie die in `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) deklarierte `url` (csharp: `Url`; go: `URL`). Beide URLs werden vor dem Abgleich normalisiert (Schema und Host in Kleinbuchstaben, Standardports und abschließende Schrägstriche entfernt), sodass Unterschiede in der Groß-/Kleinschreibung des Hosts, ein Standardport oder ein abschließender Schrägstrich eine Übereinstimmung nicht verhindern; ein anderer Pfad, eine andere Subdomain oder ein Nicht-Standardport hingegen schon. Wenn keine Übereinstimmung gefunden wird, wird die Verbindung ohne Authentifizierung versucht. Siehe [Anmeldedaten hinzufügen](https://platform.claude.com/docs/de/managed-agents/vaults#add-a-credential) für die Anmeldedatentypen `static_bearer` und `mcp_oauth`. ### Umgang mit Verbindungs- und Authentifizierungsfehlern Die Session-Erstellung validiert weder die MCP-Konnektivität noch die Anmeldedaten. Sie prüft jedoch den Host jedes deklarierten Servers anhand der Netzwerkeinstellungen der Umgebung: Bei einer `limited`-Umgebung schlägt die Session-Erstellung mit einem 400-Fehler fehl, wenn ein Host nicht erlaubt ist, wie unter [Authentifizierung bei der Session-Erstellung bereitstellen](https://platform.claude.com/docs/de/managed-agents/mcp-connector#provide-authentication-at-session-creation) beschrieben. Wenn ein MCP-Server nicht erreichbar ist oder die bereitgestellten Anmeldedaten ablehnt, startet die Session trotzdem und eine Interaktion bleibt möglich. Es wird ein [`session.error`](https://platform.claude.com/docs/de/managed-agents/reference#event-types)-Event mit dem `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) des betroffenen Servers und einem `retry_status` (java, php: `retryStatus`; csharp, go: `RetryStatus`) ausgegeben: | Fehlertyp | Bedeutung | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mcp_connection_failed_error` | Der MCP-Server konnte nicht erreicht werden (Netzwerkfehler, Timeout oder ein nicht authentifizierungsbezogener HTTP-Fehler). | | `mcp_authentication_failed_error` | Die Authentifizierung beim MCP-Server ist fehlgeschlagen: Der Server hat die Anmeldedaten aus dem angehängten Vault abgelehnt, eine Authentifizierung verlangt, obwohl keine passenden Anmeldedaten konfiguriert waren, oder die Aktualisierung eines OAuth-Tokens ist fehlgeschlagen. | Du kannst entscheiden, ob du bei diesem Fehler weitere Interaktionen blockierst, eine Rotation der Anmeldedaten auslöst oder die Session ohne die Tools des betroffenen Servers fortsetzen lässt. Die Verbindung wird beim nächsten Übergang von `session.status_idle` zu `session.status_running` erneut versucht. ## Nächste Schritte Steuere, wann Agent- und MCP-Tools ausgeführt werden. Sende Events, streame Antworten und unterbrich oder lenke deine Session während der Ausführung um. Transportanforderungen für entfernte MCP-Server.