MCP-Server an Claude anbinden

TL;DR

Zwei Parameter gehören immer zusammen: mcp_servers deklariert die Verbindung, tools muss einen passenden mcp_toolset-Eintrag enthalten. Fehlt der zweite, wird die Anfrage als ungültig abgelehnt. Und die Authentifizierung läuft nicht über den Server-Eintrag, sondern über einen Tresor.

Der Aufruf

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[{
        "type": "url",
        "name": "ticketsystem",
        "url": "https://mcp.example.com/mcp",
    }],
    tools=[{
        "type": "mcp_toolset",
        "mcp_server_name": "ticketsystem",   # muss zum name oben passen
    }],
    messages=[{"role": "user", "content": "Welche Tickets sind offen?"}],
)

Beide Parameter sind Pflicht. Jeder Server in mcp_servers muss von genau einem mcp_toolset referenziert werden — sonst kommt ein Validierungsfehler. Das ist der häufigste Fehler beim Einstieg, und die Meldung ist nicht besonders sprechend.

Der Name ist frei wählbar und dient nur der Verknüpfung zwischen beiden Feldern.

Die Authentifizierung

Der Server-Eintrag hat kein Feld für Zugangsdaten. Das ist Absicht: Die Agentendefinition soll wiederverwendbar bleiben, Geheimnisse gehören woandershin.

Bei Managed Agents laufen sie über einen Tresor:

# 1. Agent deklariert nur die Verbindung
agent = client.beta.agents.create(
    name="Ticket-Agent",
    model="claude-opus-5",
    mcp_servers=[{"type": "url", "name": "ticketsystem",
                  "url": "https://mcp.example.com/mcp"}],
    tools=[
        {"type": "agent_toolset_20260401"},
        {"type": "mcp_toolset", "mcp_server_name": "ticketsystem"},
    ],
)

# 2. Sitzung hängt den Tresor mit den Zugangsdaten an
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=umgebung.id,
    vault_ids=[tresor.id],
)

Die Zuordnung erfolgt über die Server-Adresse. Anthropic sucht im Tresor ein Zugangsdatum, dessen Adresse zur angesprochenen passt, und setzt das Token ein. Die Details dazu stehen im Beitrag zu Tresor-Zugangsdaten.

Die Falle, die Stunden kostet

MCP-Token sind nicht die API-Schlüssel des Dienstes.

Gehostete MCP-Server verlangen typischerweise OAuth-Bearer-Token — nicht die nativen API-Schlüssel desselben Anbieters. Ein Integrationstoken, das gegen die REST-API eines Dienstes einwandfrei funktioniert, wird als Tresor-Zugangsdatum für dessen MCP-Server nicht funktionieren. Das sind verschiedene Authentifizierungssysteme beim selben Anbieter.

Wer das nicht weiß, prüft den Schlüssel gegen die REST-API, stellt fest, dass er gültig ist, und sucht den Fehler danach überall außer an der richtigen Stelle.

Wie Sie an ein OAuth-Token kommen, hängt am jeweiligen MCP-Server — das steht in dessen Dokumentation. Danach hinterlegen Sie Zugriffstoken, Erneuerungstoken und den Erneuerungsendpunkt im Tresor; die Erneuerung übernimmt Anthropic.

Netzwerkfreigabe nicht vergessen

Wenn Ihre Umgebung eingeschränkte Netzwerkregeln hat, kommt der Container ohne Freigabe nicht an den MCP-Server — und die Werkzeuge scheitern still:

{
  "networking": {
    "type": "limited",
    "allow_mcp_servers": true
  }
}

Entweder allow_mcp_servers: true setzen oder jede Server-Domäne einzeln in allowed_hosts aufnehmen. Ohne das eine oder andere sieht der Agent die Werkzeuge, kann sie aber nicht nutzen.

Ein ungültiges Zugangsdatum blockiert nichts

Verhalten, das man kennen sollte: Ein ungültiges Zugangsdatum verhindert nicht, dass die Sitzung angelegt wird. Die Sitzung startet, und der Authentifizierungsfehler erscheint später als session.error-Ereignis im Strom.

Die Wiederholung erfolgt beim nächsten Übergang von Leerlauf auf Laufend. Praktisch heißt das: Wer nur auf den Rückgabewert von sessions.create() schaut, merkt einen kaputten Zugang nicht. Beobachten Sie den Ereignisstrom.

Große Werkzeugausgaben

Ein Detail, das bei datenintensiven MCP-Servern zählt: Liefert ein Werkzeug mehr als etwa 100.000 Zeichen zurück, wird die Ausgabe automatisch in eine Datei in der Sandbox ausgelagert. Der Agent bekommt eine gekürzte Vorschau plus den Dateipfad und kann den vollständigen Inhalt bei Bedarf lesen.

Die Schwelle liegt in Zeichen, nicht in Token, und gilt auch für die eingebauten Werkzeuge. Konfigurieren müssen Sie dafür nichts.

Wann MCP nicht der richtige Weg ist

MCP lohnt sich, wenn ein Dienst bereits einen Server anbietet oder mehrere Anwendungen dieselben Werkzeuge brauchen. Für eine einzelne Anbindung an ein internes System ist ein eigenes Werkzeug oft der kürzere Weg — weniger bewegliche Teile, keine Tresorverwaltung.

Wenn Sie umgekehrt einen eigenen MCP-Server für interne Systeme betreiben wollen, ist das ein anderes Vorhaben; die Systematik samt Berechtigungsprüfung je Werkzeug steht im Beitrag zum eigenen MCP-Server.

Häufig gestellte Fragen

Warum wird meine MCP-Anfrage als ungültig abgelehnt?

Weil vermutlich der mcp_toolset-Eintrag im Feld tools fehlt. mcp_servers allein reicht nicht — jeder deklarierte Server muss von genau einem Werkzeugsatz referenziert werden, wobei mcp_server_name exakt dem name des Servers entsprechen muss.

Kann ich den API-Schlüssel des Dienstes als MCP-Zugangsdatum nutzen?

In der Regel nicht. Gehostete MCP-Server verlangen typischerweise OAuth-Bearer-Token, nicht die nativen API-Schlüssel desselben Anbieters — das sind verschiedene Authentifizierungssysteme. Ein Token, das gegen die REST-API funktioniert, scheitert als MCP-Zugangsdatum, ohne dass die Fehlermeldung darauf hinweist.

Warum scheitern die MCP-Werkzeuge still?

Häufig an der Netzwerkfreigabe. Bei eingeschränkten Netzwerkregeln muss entweder allow_mcp_servers: true gesetzt oder jede Server-Domäne in allowed_hosts aufgenommen sein. Ohne das erreicht der Container den Server nicht, während die Werkzeuge in der Konfiguration weiterhin sichtbar sind.

Blockiert ein falsches Zugangsdatum das Anlegen der Sitzung?

Nein. Die Sitzung wird angelegt, und der Authentifizierungsfehler erscheint erst als session.error-Ereignis im Strom; die Wiederholung erfolgt beim nächsten Übergang von Leerlauf auf Laufend. Wer nur den Rückgabewert von sessions.create() prüft, bemerkt einen kaputten Zugang nicht.

Was passiert bei sehr großen Werkzeugausgaben?

Ab etwa 100.000 Zeichen wird die Ausgabe automatisch in eine Datei in der Sandbox ausgelagert; der Agent erhält eine gekürzte Vorschau und den Dateipfad und kann den vollständigen Inhalt bei Bedarf nachlesen. Die Schwelle gilt in Zeichen, nicht in Token, und betrifft auch die eingebauten Werkzeuge.

Der nächste Schritt

Prüfen Sie vor der Anbindung, welche Art von Token der MCP-Server tatsächlich erwartet — OAuth oder API-Schlüssel. Diese eine Frage vorab spart die häufigste und ärgerlichste Fehlersuche im gesamten Einrichtungsvorgang. Bei der Anbindung unterstützen wir gern.