Leitfäden

MCP im SDK

Erweitern Sie Claude Code mit benutzerdefinierten Tools unter Verwendung von Model Context Protocol Servern

Überblick

Model Context Protocol (MCP) Server erweitern Claude Code mit benutzerdefinierten Tools und Funktionen. MCPs können als externe Prozesse ausgeführt werden, über HTTP/SSE verbinden oder direkt innerhalb Ihrer SDK-Anwendung ausgeführt werden.

Konfiguration

Grundkonfiguration

Konfigurieren Sie MCP-Server in .mcp.json im Stammverzeichnis Ihres Projekts:

TypeScript

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

Python

{
  "mcpServers": {
    "filesystem": {
      "command": "python",
      "args": ["-m", "mcp_server_filesystem"],
      "env": {
        "ALLOWED_PATHS": "/Users/me/projects"
      }
    }
  }
}

Verwendung von MCP-Servern im SDK

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

for await (const message of query({
  prompt: "Liste Dateien in meinem Projekt auf",
  options: {
    mcpConfig: ".mcp.json",
    allowedTools: ["mcp__filesystem__list_files"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Transport-Typen

stdio Server

Externe Prozesse, die über stdin/stdout kommunizieren:

// .mcp.json Konfiguration
{
  "mcpServers": {
    "my-tool": {
      "command": "node",
      "args": ["./my-mcp-server.js"],
      "env": {
        "DEBUG": "${DEBUG:-false}"
      }
    }
  }
}

HTTP/SSE Server

Remote-Server mit Netzwerkkommunikation:

// SSE Server-Konfiguration
{
  "mcpServers": {
    "remote-api": {
      "type": "sse",
      "url": "https://api.example.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

// HTTP Server-Konfiguration
{
  "mcpServers": {
    "http-service": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "X-API-Key": "${API_KEY}"
      }
    }
  }
}

SDK MCP Server

In-Process-Server, die innerhalb Ihrer Anwendung laufen. Für detaillierte Informationen zur Erstellung benutzerdefinierter Tools siehe den Custom Tools Leitfaden:

Ressourcenverwaltung

MCP-Server können Ressourcen bereitstellen, die Claude auflisten und lesen kann:

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

// Verfügbare Ressourcen auflisten
for await (const message of query({
  prompt: "Welche Ressourcen sind vom Datenbankserver verfügbar?",
  options: {
    mcpConfig: ".mcp.json",
    allowedTools: ["mcp__list_resources", "mcp__read_resource"]
  }
})) {
  if (message.type === "result") console.log(message.result);
}

Authentifizierung

Umgebungsvariablen

// .mcp.json mit Umgebungsvariablen
{
  "mcpServers": {
    "secure-api": {
      "type": "sse",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}",
        "X-API-Key": "${API_KEY:-default-key}"
      }
    }
  }
}

// Umgebungsvariablen setzen
process.env.API_TOKEN = "your-token";
process.env.API_KEY = "your-key";

OAuth2 Authentifizierung

OAuth2 MCP-Authentifizierung im Client wird derzeit nicht unterstützt.

Fehlerbehandlung

Behandeln Sie MCP-Verbindungsfehler elegant:

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

for await (const message of query({
  prompt: "Daten verarbeiten",
  options: {
    mcpServers: {
      "data-processor": dataServer
    }
  }
})) {
  if (message.type === "system" && message.subtype === "init") {
    // MCP-Server-Status überprüfen
    const failedServers = message.mcp_servers.filter(
      s => s.status !== "connected"
    );
    
    if (failedServers.length > 0) {
      console.warn("Verbindung fehlgeschlagen:", failedServers);
    }
  }
  
  if (message.type === "result" && message.subtype === "error_during_execution") {
    console.error("Ausführung fehlgeschlagen");
  }
}

MCP im SDK

Erweitern Sie Claude Code mit benutzerdefinierten Tools unter Verwendung von Model Context Protocol Servern

Überblick

Konfiguration

Grundkonfiguration

Konfigurieren Sie MCP-Server in .mcp.json im Stammverzeichnis Ihres Projekts:

TypeScript

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

Python

{
  "mcpServers": {
    "filesystem": {
      "command": "python",
      "args": ["-m", "mcp_server_filesystem"],
      "env": {
        "ALLOWED_PATHS": "/Users/me/projects"
      }
    }
  }
}

Verwendung von MCP-Servern im SDK

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

for await (const message of query({
  prompt: "Liste Dateien in meinem Projekt auf",
  options: {
    mcpConfig: ".mcp.json",
    allowedTools: ["mcp__filesystem__list_files"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Transport-Typen

stdio Server

Externe Prozesse, die über stdin/stdout kommunizieren:

// .mcp.json Konfiguration
{
  "mcpServers": {
    "my-tool": {
      "command": "node",
      "args": ["./my-mcp-server.js"],
      "env": {
        "DEBUG": "${DEBUG:-false}"
      }
    }
  }
}

HTTP/SSE Server

Remote-Server mit Netzwerkkommunikation:

// SSE Server-Konfiguration
{
  "mcpServers": {
    "remote-api": {
      "type": "sse",
      "url": "https://api.example.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

// HTTP Server-Konfiguration
{
  "mcpServers": {
    "http-service": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "X-API-Key": "${API_KEY}"
      }
    }
  }
}

SDK MCP Server

In-Process-Server, die innerhalb Ihrer Anwendung laufen. Für detaillierte Informationen zur Erstellung benutzerdefinierter Tools siehe den Custom Tools Leitfaden:

Ressourcenverwaltung

MCP-Server können Ressourcen bereitstellen, die Claude auflisten und lesen kann:

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

// Verfügbare Ressourcen auflisten
for await (const message of query({
  prompt: "Welche Ressourcen sind vom Datenbankserver verfügbar?",
  options: {
    mcpConfig: ".mcp.json",
    allowedTools: ["mcp__list_resources", "mcp__read_resource"]
  }
})) {
  if (message.type === "result") console.log(message.result);
}

Authentifizierung

Umgebungsvariablen

// .mcp.json mit Umgebungsvariablen
{
  "mcpServers": {
    "secure-api": {
      "type": "sse",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}",
        "X-API-Key": "${API_KEY:-default-key}"
      }
    }
  }
}

// Umgebungsvariablen setzen
process.env.API_TOKEN = "your-token";
process.env.API_KEY = "your-key";

OAuth2 Authentifizierung

OAuth2 MCP-Authentifizierung im Client wird derzeit nicht unterstützt.

Fehlerbehandlung

Behandeln Sie MCP-Verbindungsfehler elegant:

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

for await (const message of query({
  prompt: "Daten verarbeiten",
  options: {
    mcpServers: {
      "data-processor": dataServer
    }
  }
})) {
  if (message.type === "system" && message.subtype === "init") {
    // MCP-Server-Status überprüfen
    const failedServers = message.mcp_servers.filter(
      s => s.status !== "connected"
    );
    
    if (failedServers.length > 0) {
      console.warn("Verbindung fehlgeschlagen:", failedServers);
    }
  }
  
  if (message.type === "result" && message.subtype === "error_during_execution") {
    console.error("Ausführung fehlgeschlagen");
  }
}

Überblick

Konfiguration

Grundkonfiguration

Verwendung von MCP-Servern im SDK

Transport-Typen

stdio Server

HTTP/SSE Server

SDK MCP Server

Ressourcenverwaltung

Authentifizierung

Umgebungsvariablen

OAuth2 Authentifizierung

Fehlerbehandlung

Verwandte Ressourcen

Überblick

Konfiguration

Grundkonfiguration

Verwendung von MCP-Servern im SDK

Transport-Typen

stdio Server

HTTP/SSE Server

SDK MCP Server

Ressourcenverwaltung

Authentifizierung

Umgebungsvariablen

OAuth2 Authentifizierung

Fehlerbehandlung

Verwandte Ressourcen