Mit MCP zu externen Tools verbinden

Das Model Context Protocol (MCP) ist ein offener Standard für die Verbindung von KI-Agenten mit externen Tools und Datenquellen. Mit MCP kann Ihr Agent Datenbanken abfragen, sich mit APIs wie Slack und GitHub integrieren und sich mit anderen Diensten verbinden, ohne benutzerdefinierte Tool-Implementierungen zu schreiben.

MCP-Server können als lokale Prozesse ausgeführt werden, sich über HTTP verbinden oder direkt in Ihrer SDK-Anwendung ausgeführt werden.

Schnellstart

Dieses Beispiel verbindet sich mit dem Claude Code-Dokumentations-MCP-Server unter Verwendung von HTTP-Transport und verwendet allowedTools mit einem Platzhalter, um alle Tools vom Server zuzulassen.

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Use the docs MCP server to explain what hooks are in Claude Code",
  options: {
    mcpServers: {
      "claude-code-docs": {
        type: "http",
        url: "https://code.claude.com/docs/mcp"
      }
    },
    allowedTools: ["mcp__claude-code-docs__*"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Der Agent verbindet sich mit dem Dokumentationsserver, sucht nach Informationen über Hooks und gibt die Ergebnisse zurück.

MCP-Server hinzufügen

Sie können MCP-Server im Code beim Aufrufen von query() konfigurieren oder in einer .mcp.json-Datei, die das SDK automatisch lädt.

Im Code

Übergeben Sie MCP-Server direkt in der mcpServers-Option:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "List files in my project",
  options: {
    mcpServers: {
      "filesystem": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
      }
    },
    allowedTools: ["mcp__filesystem__*"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Aus einer Konfigurationsdatei

Erstellen Sie eine .mcp.json-Datei im Stammverzeichnis Ihres Projekts. Das SDK lädt diese automatisch:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    }
  }
}

MCP-Tools zulassen

MCP-Tools erfordern explizite Berechtigung, bevor Claude sie verwenden kann. Ohne Berechtigung sieht Claude, dass Tools verfügbar sind, kann sie aber nicht aufrufen.

Tool-Benennungskonvention

MCP-Tools folgen dem Benennungsmuster mcp__<server-name>__<tool-name>. Beispielsweise wird ein GitHub-Server namens "github" mit einem list_issues-Tool zu mcp__github__list_issues.

Zugriff mit allowedTools gewähren

Verwenden Sie allowedTools, um anzugeben, welche MCP-Tools Claude verwenden kann:

options: {
  mcpServers: { /* your servers */ },
  allowedTools: [
    "mcp__github__*",              // All tools from the github server
    "mcp__db__query",              // Only the query tool from db server
    "mcp__slack__send_message"     // Only send_message from slack server
  ]
}

Platzhalter (*) ermöglichen es Ihnen, alle Tools von einem Server zuzulassen, ohne jedes einzelne aufzulisten.

Alternative: Ändern Sie den Berechtigungsmodus

Anstatt zulässige Tools aufzulisten, können Sie den Berechtigungsmodus ändern, um umfassenderen Zugriff zu gewähren:

• permissionMode: "acceptEdits": Genehmigt die Tool-Nutzung automatisch (fordert dennoch für destruktive Operationen auf)
• permissionMode: "bypassPermissions": Überspringt alle Sicherheitsaufforderungen, einschließlich destruktiver Operationen wie Dateilöschung oder Ausführung von Shell-Befehlen. Mit Vorsicht verwenden, besonders in der Produktion. Dieser Modus wird an Subagenten weitergegeben, die vom Task-Tool erzeugt werden.

options: {
  mcpServers: { /* your servers */ },
  permissionMode: "acceptEdits"  // No need for allowedTools
}

Weitere Details zu Berechtigungsmodi finden Sie unter Berechtigungen.

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 überprüfen Sie die system-Init-Nachricht:

for await (const message of query({ prompt: "...", options })) {
  if (message.type === "system" && message.subtype === "init") {
    console.log("Available MCP tools:", message.mcp_servers);
  }
}

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:

HTTP/SSE-Server

Verwenden Sie HTTP oder SSE für Cloud-gehostete MCP-Server und Remote-APIs:

Für HTTP (nicht-Streaming) verwenden Sie stattdessen "type": "http".

SDK-MCP-Server

Definieren Sie benutzerdefinierte Tools direkt in Ihrem Anwendungscode, anstatt einen separaten Server-Prozess auszuführen. Weitere Implementierungsdetails finden Sie im Leitfaden für benutzerdefinierte Tools.

MCP-Tool-Suche

Wenn Sie viele MCP-Tools konfiguriert haben, können Tool-Definitionen einen erheblichen Teil Ihres Kontextfensters verbrauchen. Die MCP-Tool-Suche löst dies, indem Tools bei Bedarf dynamisch geladen werden, anstatt alle vorab zu laden.

Wie es funktioniert

Die Tool-Suche läuft standardmäßig im Auto-Modus. Sie wird aktiviert, wenn Ihre MCP-Tool-Beschreibungen mehr als 10% des Kontextfensters verbrauchen würden. Wenn ausgelöst:

1. MCP-Tools werden mit defer_loading: true markiert, anstatt vorab in den Kontext geladen zu werden
2. Claude verwendet ein Such-Tool, um relevante MCP-Tools bei Bedarf zu entdecken
3. Nur die Tools, die Claude tatsächlich benötigt, werden in den Kontext geladen

Die Tool-Suche erfordert Modelle, die tool_reference-Blöcke unterstützen: Sonnet 4 und später oder Opus 4 und später. Haiku-Modelle unterstützen die Tool-Suche nicht.

Tool-Suche konfigurieren

Steuern Sie das Verhalten der Tool-Suche mit der Umgebungsvariablen ENABLE_TOOL_SEARCH:

Legen Sie den Wert in der env-Option fest:

const options = {
  mcpServers: { /* your MCP servers */ },
  env: {
    ENABLE_TOOL_SEARCH: "auto:5"  // Enable at 5% threshold
  }
};

Authentifizierung

Die meisten MCP-Server erfordern Authentifizierung, um auf externe Dienste zuzugreifen. Übergeben Sie Anmeldedaten über Umgebungsvariablen in der Server-Konfiguration.

Anmeldedaten über Umgebungsvariablen übergeben

Verwenden Sie das env-Feld, um API-Schlüssel, Token und andere Anmeldedaten an den MCP-Server zu übergeben:

Siehe Probleme aus einem Repository auflisten für ein vollständiges funktionierendes Beispiel mit Debug-Protokollierung.

HTTP-Header für Remote-Server

Für HTTP- und SSE-Server übergeben Sie Authentifizierungs-Header direkt in der Server-Konfiguration:

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:

// After completing OAuth flow in your app
const accessToken = await getAccessTokenFromOAuthFlow();

const options = {
  mcpServers: {
    "oauth-api": {
      type: "http",
      url: "https://api.example.com/mcp",
      headers: {
        Authorization: `Bearer ${accessToken}`
      }
    }
  },
  allowedTools: ["mcp__oauth-api__*"]
};

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-Personal-Access-Token mit repo-Bereich und legen Sie es als Umgebungsvariable fest:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "List the 3 most recent issues in anthropics/claude-code",
  options: {
    mcpServers: {
      "github": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          GITHUB_TOKEN: process.env.GITHUB_TOKEN
        }
      }
    },
    allowedTools: ["mcp__github__list_issues"]
  }
})) {
  // Verify MCP server connected successfully
  if (message.type === "system" && message.subtype === "init") {
    console.log("MCP servers:", message.mcp_servers);
  }

  // Log when Claude calls an MCP tool
  if (message.type === "assistant") {
    for (const block of message.content) {
      if (block.type === "tool_use" && block.name.startsWith("mcp__")) {
        console.log("MCP tool called:", block.name);
      }
    }
  }

  // Print the final result
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

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:

import { query } from "@anthropic-ai/claude-agent-sdk";

// Connection string from environment variable
const connectionString = process.env.DATABASE_URL;

for await (const message of query({
  // Natural language query - Claude writes the SQL
  prompt: "How many users signed up last week? Break it down by day.",
  options: {
    mcpServers: {
      "postgres": {
        command: "npx",
        // Pass connection string as argument to the server
        args: ["-y", "@modelcontextprotocol/server-postgres", connectionString]
      }
    },
    // Allow only read queries, not writes
    allowedTools: ["mcp__postgres__query"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Fehlerbehandlung

MCP-Server können aus verschiedenen Gründen keine Verbindung herstellen: Der Server-Prozess ist möglicherweise nicht installiert, Anmeldedaten könnten ungültig sein, oder ein Remote-Server könnte unerreichbar sein.

Das SDK sendet eine system-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:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Process data",
  options: {
    mcpServers: {
      "data-processor": dataServer
    }
  }
})) {
  if (message.type === "system" && message.subtype === "init") {
    const failedServers = message.mcp_servers.filter(
      s => s.status !== "connected"
    );

    if (failedServers.length > 0) {
      console.warn("Failed to connect:", failedServers);
    }
  }

  if (message.type === "result" && message.subtype === "error_during_execution") {
    console.error("Execution failed");
  }
}

Fehlerbehebung

Server zeigt "failed"-Status

Überprüfen Sie die init-Nachricht, um zu sehen, welche Server keine Verbindung herstellen konnten:

if (message.type === "system" && message.subtype === "init") {
  for (const server of message.mcp_servers) {
    if (server.status === "failed") {
      console.error(`Server ${server.name} failed to connect`);
    }
  }
}

Häufige Ursachen:

• Fehlende Umgebungsvariablen: Stellen Sie sicher, dass erforderliche Token und Anmeldedaten gesetzt 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 existiert 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 mit allowedTools gewährt haben oder durch Ändern des Berechtigungsmodus:

options: {
  mcpServers: { /* your servers */ },
  allowedTools: ["mcp__servername__*"]  // Required for Claude to use the tools
}

Verbindungs-Timeouts

Das MCP-SDK hat ein Standard-Timeout von 60 Sekunden für Server-Verbindungen. Wenn Ihr Server länger zum Starten benötigt, schlägt die Verbindung fehl. Für Server, die mehr Startzeit benötigen, sollten Sie folgende Optionen in Betracht ziehen:

• Verwenden Sie einen leichteren Server, falls verfügbar
• Wärmen Sie den Server vor, bevor Sie Ihren Agenten starten
• Überprüfen Sie Server-Protokolle 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: Steuern Sie, welche MCP-Tools Ihr Agent mit allowedTools und disallowedTools verwenden 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