Diese Seite behandelt die MCP-Konfiguration für das Agent SDK. Um MCP-Server zur Claude Code CLI hinzuzufügen, damit sie in jedem Projekt geladen werden, siehe MCP-Installationsbereiche.
Schnellstart
Dieses Beispiel verbindet sich mit dem Claude Code-Dokumentations-MCP-Server unter Verwendung von HTTP-Transport und verwendetallowedTools mit einem Platzhalter, um alle Tools vom Server zuzulassen.
Einen MCP-Server hinzufügen
Sie können MCP-Server im Code beim Aufrufen vonquery() konfigurieren oder in einer .mcp.json-Datei, die über settingSources geladen wird.
Im Code
Übergeben Sie MCP-Server direkt in dermcpServers-Option:
Aus einer Konfigurationsdatei
Erstellen Sie eine.mcp.json-Datei im Stammverzeichnis Ihres Projekts. Die Datei wird aufgegriffen, wenn die project-Einstellungsquelle aktiviert ist, was sie für Standard-query()-Optionen ist. Wenn Sie settingSources explizit festlegen, fügen Sie "project" ein, damit diese Datei geladen wird:
MCP-Tools zulassen
MCP-Tools erfordern explizite Genehmigung, bevor Claude sie verwenden kann. Ohne Genehmigung sieht Claude, dass Tools verfügbar sind, kann sie aber nicht aufrufen.Tool-Benennungskonvention
MCP-Tools folgen dem Benennungsmustermcp__<server-name>__<tool-name>. Beispielsweise wird ein GitHub-Server mit dem Namen "github" mit einem list_issues-Tool zu mcp__github__list_issues.
Automatische Genehmigung mit allowedTools
Verwenden SieallowedTools, um bestimmte MCP-Tools automatisch zu genehmigen, damit Claude sie ohne Genehmigungsaufforderung verwenden kann:
*) ermöglichen es Ihnen, alle Tools von einem Server zuzulassen, ohne jedes einzeln aufzulisten.
Bevorzugen Sie
allowedTools gegenüber Berechtigungsmodi für MCP-Zugriff. permissionMode: "acceptEdits" genehmigt MCP-Tools nicht automatisch (nur Dateibearbeitungen und Filesystem-Bash-Befehle). permissionMode: "bypassPermissions" genehmigt MCP-Tools automatisch, deaktiviert aber auch alle anderen Sicherheitsaufforderungen, was breiter ist als nötig. Ein Platzhalter in allowedTools gewährt genau den MCP-Server, den Sie möchten, und nichts mehr. Siehe Berechtigungsmodi für einen vollständigen Vergleich.Verfügbare Tools entdecken
Um zu sehen, welche Tools ein MCP-Server bereitstellt, überprüfen Sie die Dokumentation des Servers oder verbinden Sie sich mit dem Server und inspizieren Sie diesystem-Init-Nachricht:
Transporttypen
MCP-Server kommunizieren mit Ihrem Agenten über verschiedene Transportprotokolle. Überprüfen Sie die Dokumentation des Servers, um zu sehen, welchen Transport er unterstützt:- Wenn die Dokumentation Ihnen einen Befehl zum Ausführen gibt (wie
npx @modelcontextprotocol/server-github), verwenden Sie stdio - Wenn die Dokumentation Ihnen eine URL gibt, verwenden Sie HTTP oder SSE
- Wenn Sie Ihre eigenen Tools im Code erstellen, verwenden Sie einen SDK MCP-Server
stdio-Server
Lokale Prozesse, die über stdin/stdout kommunizieren. Verwenden Sie dies für MCP-Server, die Sie auf demselben Computer ausführen:- Im Code
- .mcp.json
HTTP/SSE-Server
Verwenden Sie HTTP oder SSE für Cloud-gehostete MCP-Server und Remote-APIs:- Im Code
- .mcp.json
"type": "http". In .mcp.json und anderen JSON-Konfigurationsdateien wird "streamable-http" als Alias für "http" akzeptiert. Die programmgesteuerte mcpServers-Option akzeptiert nur "http".
SDK MCP-Server
Definieren Sie benutzerdefinierte Tools direkt in Ihrem Anwendungscode, anstatt einen separaten Serverprozess auszuführen. Siehe das Leitfaden für benutzerdefinierte Tools für Implementierungsdetails.MCP-Tool-Suche
Wenn Sie viele MCP-Tools konfiguriert haben, können Tool-Definitionen einen erheblichen Teil Ihres Kontextfensters verbrauchen. Die Tool-Suche löst dies, indem Tool-Definitionen aus dem Kontext zurückgehalten und nur die Tools geladen werden, die Claude für jeden Durchgang benötigt. Die Tool-Suche ist standardmäßig aktiviert. Siehe Tool-Suche für Konfigurationsoptionen und Details. Für weitere Details, einschließlich Best Practices und Verwendung der Tool-Suche mit benutzerdefinierten SDK-Tools, siehe das Tool-Suche-Leitfaden.Authentifizierung
Die meisten MCP-Server erfordern Authentifizierung, um auf externe Dienste zuzugreifen. Übergeben Sie Anmeldedaten über Umgebungsvariablen in der Serverkonfiguration.Anmeldedaten über Umgebungsvariablen übergeben
Verwenden Sie dasenv-Feld, um API-Schlüssel, Token und andere Anmeldedaten an den MCP-Server zu übergeben:
- Im Code
- .mcp.json
HTTP-Header für Remote-Server
Für HTTP- und SSE-Server übergeben Sie Authentifizierungs-Header direkt in der Serverkonfiguration:- Im Code
- .mcp.json
OAuth2-Authentifizierung
Die MCP-Spezifikation unterstützt OAuth 2.1 für Autorisierung. Das SDK verarbeitet OAuth-Flows nicht automatisch, aber Sie können Zugriffs-Token über Header übergeben, nachdem Sie den OAuth-Flow in Ihrer Anwendung abgeschlossen haben:Beispiele
Probleme aus einem Repository auflisten
Dieses Beispiel verbindet sich mit dem GitHub MCP-Server, um aktuelle Probleme aufzulisten. Das Beispiel enthält Debug-Protokollierung, um die MCP-Verbindung und Tool-Aufrufe zu überprüfen. Erstellen Sie vor dem Ausführen ein GitHub-Persönliches Zugriffs-Token mitrepo-Bereich und legen Sie es als Umgebungsvariable fest:
Eine Datenbank abfragen
Dieses Beispiel verwendet den Postgres MCP-Server, um eine Datenbank abzufragen. Die Verbindungszeichenfolge wird als Argument an den Server übergeben. Der Agent entdeckt automatisch das Datenbankschema, schreibt die SQL-Abfrage und gibt die Ergebnisse zurück:Fehlerbehandlung
MCP-Server können aus verschiedenen Gründen keine Verbindung herstellen: Der Serverprozess ist möglicherweise nicht installiert, Anmeldedaten könnten ungültig sein, oder ein Remote-Server könnte unerreichbar sein. Das SDK sendet einesystem-Nachricht mit dem Subtyp init am Anfang jeder Abfrage. Diese Nachricht enthält den Verbindungsstatus für jeden MCP-Server. Überprüfen Sie das status-Feld, um Verbindungsfehler zu erkennen, bevor der Agent mit der Arbeit beginnt:
Fehlerbehebung
Server zeigt Status „fehlgeschlagen”
Überprüfen Sie dieinit-Nachricht, um zu sehen, welche Server keine Verbindung herstellen konnten:
- Fehlende Umgebungsvariablen: Stellen Sie sicher, dass erforderliche Token und Anmeldedaten festgelegt sind. Überprüfen Sie für stdio-Server, dass das
env-Feld dem entspricht, was der Server erwartet. - Server nicht installiert: Überprüfen Sie für
npx-Befehle, dass das Paket vorhanden ist und Node.js in Ihrem PATH ist. - Ungültige Verbindungszeichenfolge: Überprüfen Sie für Datenbankserver das Format der Verbindungszeichenfolge und dass die Datenbank zugänglich ist.
- Netzwerkprobleme: Überprüfen Sie für Remote-HTTP/SSE-Server, dass die URL erreichbar ist und Firewalls die Verbindung zulassen.
Tools werden nicht aufgerufen
Wenn Claude Tools sieht, sie aber nicht verwendet, überprüfen Sie, dass Sie die Berechtigung mitallowedTools gewährt haben:
Verbindungs-Timeouts
Das MCP SDK hat ein Standard-Timeout von 60 Sekunden für Serververbindungen. Wenn Ihr Server länger zum Starten benötigt, schlägt die Verbindung fehl. Für Server, die mehr Startzeit benötigen, erwägen Sie:- Verwendung eines leichteren Servers, falls verfügbar
- Vorwärmung des Servers vor dem Starten Ihres Agenten
- Überprüfung von Serverprotokollen auf langsame Initialisierungsursachen
Verwandte Ressourcen
- Leitfaden für benutzerdefinierte Tools: Erstellen Sie Ihren eigenen MCP-Server, der in-process mit Ihrer SDK-Anwendung ausgeführt wird
- Berechtigungen: Kontrollieren Sie, welche MCP-Tools Ihr Agent mit
allowedToolsunddisallowedToolsverwenden kann - TypeScript SDK-Referenz: Vollständige API-Referenz einschließlich MCP-Konfigurationsoptionen
- Python SDK-Referenz: Vollständige API-Referenz einschließlich MCP-Konfigurationsoptionen
- MCP-Server-Verzeichnis: Durchsuchen Sie verfügbare MCP-Server für Datenbanken, APIs und mehr