MCP-Connector

Claude Managed Agents unterstützt die Anbindung von Model Context Protocol (MCP)-Servern an deine 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. Agent-Erstellung deklariert, mit welchen MCP-Servern sich der Agent verbindet, anhand von Name und URL.
2. Session-Erstellung liefert die Authentifizierung für diese Server, indem auf einen vorab registrierten Vault verwiesen wird (siehe Authentifizierung mit Vaults).

Diese Trennung hält Secrets aus wiederverwendbaren Agent-Definitionen heraus und ermöglicht es gleichzeitig jeder Session, sich mit eigenen Anmeldedaten zu authentifizieren.



MCP-Server am Agenten deklarieren

Gib MCP-Server im Array mcp_servers an, wenn du einen Agenten erstellst. Jeder Server benötigt einen type, einen eindeutigen name und eine url. In diesem Schritt werden keine Authentifizierungs-Token angegeben.

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 einen deklarierten Server referenzieren. 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 haben MCP-Tool-Einträge kein type-Feld, und die Web-Einstellungen, die für web_search und web_fetch verfügbar sind, 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 den Rest 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 Setzen von permission_policy bei MCP-Tools und zum Umgang mit Bestätigungsanfragen.



Verarbeitung von MCP-Tool-Ausgaben

Wenn eine MCP-Tool-Ausgabe 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 Authentifizierung mit Vaults, 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 eine Anmeldedaten-Eintragung 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 einen Abgleich 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 Anmeldedaten-Typen static_bearer und mcp_oauth.



Verbindungs- und Authentifizierungsfehler behandeln

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