SpyBara
Go Premium

agent-sdk/mcp.md 2026-06-16 21:57 UTC to 2026-06-17 17:02 UTC

80 added, 28 removed.

2026
Sat 27 01:01 Fri 26 23:00 Thu 25 23:58 Wed 24 22:02 Tue 23 22:00 Mon 22 23:59 Fri 19 22:58 Thu 18 22:00 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

Mit MCP zu externen Tools verbinden

Konfigurieren Sie MCP-Server, um Ihren Agenten mit externen Tools zu erweitern. Behandelt Transporttypen, Tool-Suche für große Tool-Sets, Authentifizierung und Fehlerbehandlung.

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.

Einen MCP-Server hinzufügen

Sie können MCP-Server im Code beim Aufrufen von query() konfigurieren oder in einer .mcp.json-Datei, die über settingSources geladen wird.

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

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

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 Benennungsmuster mcp__<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 Sie allowedTools, um bestimmte MCP-Tools automatisch zu genehmigen, damit Claude sie ohne Genehmigungsaufforderung verwenden kann:

const _ = {
  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 einzeln aufzulisten.

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

const _ = {
options: {
mcpServers: {
github: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-github"],
env: {
GITHUB_TOKEN: process.env.GITHUB_TOKEN
}
}
},
allowedTools: ["mcp__github__list_issues", "mcp__github__search_issues"]
}
};

HTTP/SSE-Server

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

const _ = {
options: {
mcpServers: {
"remote-api": {
type: "sse",
url: "https://api.example.com/mcp/sse",
headers: {
Authorization: `Bearer ${process.env.API_TOKEN}`
}
}
},
allowedTools: ["mcp__remote-api__*"]
}
};

Verwenden Sie für den streamfähigen HTTP-Transport stattdessen "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.

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 das env-Feld, um API-Schlüssel, Token und andere Anmeldedaten an den MCP-Server zu übergeben:

const _ = {
options: {
mcpServers: {
github: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-github"],
env: {
GITHUB_TOKEN: process.env.GITHUB_TOKEN
}
}
},
allowedTools: ["mcp__github__list_issues"]
}
};

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

const _ = {
options: {
mcpServers: {
"secure-api": {
type: "http",
url: "https://api.example.com/mcp",
headers: {
Authorization: `Bearer ${process.env.API_TOKEN}`
}
}
},
allowedTools: ["mcp__secure-api__*"]
}
};

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-Persönliches Zugriffs-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.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 Serverprozess 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 Status „fehlgeschlagen"

Ü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 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 mit allowedTools gewährt haben:

const _ = {
  options: {
    mcpServers: {
      // your servers
    },
    allowedTools: ["mcp__servername__*"] // Auto-approve calls from this server
  }
};

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