MCP-Connector

Claude Managed Agents unterstützt das Verbinden von Model Context Protocol (MCP)-Servern mit deinen Agents. Dadurch erhält der Agent über ein standardisiertes Protokoll Zugriff auf externe Tools, Datenquellen und Dienste.

Die MCP-Konfiguration ist in 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.

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

Gib MCP-Server im Array mcp_servers an, wenn du einen Agent 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 \
  --name "GitHub Assistant" \
  --model claude-opus-4-8 \
  --mcp-server '{type: url, name: github, url: "https://api.githubcopilot.com/mcp/"}' \
  --tool '{type: agent_toolset_20260401}' \
  --tool '{type: mcp_toolset, mcp_server_name: github}' \
  --transform id --raw-output)



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 dieselbe Struktur aus default_config und configs wie das integrierte Agent-Toolset, angewendet auf die Tools, die der MCP-Server bereitstellt. 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, lasse 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 Toolset konfigurieren für das allgemeine Muster aus default_config / configs und MCP-Toolset-Berechtigungen zum Festlegen von permission_policy für MCP-Tools und zum Umgang mit Bestätigungsanfragen.



Verarbeitung von MCP-Tool-Ausgaben

Wenn eine MCP-Tool-Ausgabe 100.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 eine Anmeldedaten-Eintrag enthalten, dessen mcp_server_url exakt mit der in mcp_servers deklarierten url übereinstimmt. Wenn keine Übereinstimmung vorliegt, wird die Verbindung ohne Authentifizierung versucht. Siehe Anmeldedaten hinzufügen für die Anmeldedatentypen 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 Interaktion 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