MCP-Connector

Claude Managed Agents unterstützt das Verbinden von „Model Context Protocol“-Servern, oder MCP-Servern, 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).

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 an. Jeder Server benötigt einen type, einen eindeutigen name und eine url. In dieser Phase werden keine Authentifizierungstoken bereitgestellt.

Jeder deklarierte Server benötigt außerdem einen passenden mcp_toolset-Eintrag im Array tools. Der mcp_server_name des Toolsets muss mit dem name des Servers übereinstimmen.

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

Feldreferenz für mcp_servers

Jeder Eintrag im Array mcp_servers definiert eine Verbindung.

Einschränkungen:

• Ein Agent kann bis zu 20 MCP-Server deklarieren. Servernamen müssen innerhalb des Arrays eindeutig sein.
• Jeder mcp_servers-Eintrag muss von einem mcp_toolset im Array tools referenziert werden, und jedes mcp_toolset muss auf einen deklarierten Server verweisen. Die API lehnt Agent-Definitionen mit nicht referenzierten Servern oder verwaisten Toolsets ab.

Konfigurieren, welche MCP-Tools verfügbar sind

Der mcp_toolset-Eintrag unterstützt ein default_config-Objekt und ein configs-Array, die auf die vom MCP-Server bereitgestellten Tools angewendet werden. Jeder configs-Eintrag akzeptiert nur name, enabled und permission_policy. Anders als Einträge im integrierten Agent-Toolset nehmen MCP-Tool-Einträge kein type-Feld an, und die für web_search und web_fetch verfügbaren Web-Einstellungen gelten nicht für MCP-Tools. Der name in jedem 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:

{
  "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:

{
  "type": "mcp_toolset",
  "mcp_server_name": "github",
  "configs": [{ "name": "delete_repository", "enabled": false }]
}

Siehe Konfigurieren des Toolsets für das allgemeine default_config-/configs-Muster und MCP-Toolset-Berechtigungen zum Festlegen von permission_policy für MCP-Tools und zum 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, 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, um zu erfahren, wie du Vaults erstellst und Anmeldedaten verwaltest.

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 auf denselben Server verweist wie die in mcp_servers deklarierte 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 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. Wenn ein MCP-Server nicht erreichbar ist oder die bereitgestellten Anmeldedaten ablehnt, startet die Session trotzdem und eine Interaktion bleibt möglich. Ein session.error-Event wird mit dem mcp_server_name des betroffenen Servers und einem retry_status ausgegeben:

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