Panduan

MCP dalam SDK

Perluas Claude Code dengan alat kustom menggunakan server Model Context Protocol

Ikhtisar

Server Model Context Protocol (MCP) memperluas Claude Code dengan alat dan kemampuan kustom. MCP dapat berjalan sebagai proses eksternal, terhubung melalui HTTP/SSE, atau dieksekusi langsung dalam aplikasi SDK Anda.

Konfigurasi

Konfigurasi Dasar

Konfigurasikan server MCP dalam .mcp.json di root proyek Anda:

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"
      }
    }
  }
}

Menggunakan Server MCP dalam SDK

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: ["@modelcontextprotocol/server-filesystem"],
        env: {
          ALLOWED_PATHS: "/Users/me/projects"
        }
      }
    },
    allowedTools: ["mcp__filesystem__list_files"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Jenis Transport

Server stdio

Proses eksternal yang berkomunikasi melalui stdin/stdout:

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

Server HTTP/SSE

Server jarak jauh dengan komunikasi jaringan:

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

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

Server MCP SDK

Server dalam proses yang berjalan dalam aplikasi Anda. Untuk informasi detail tentang membuat alat kustom, lihat panduan Alat Kustom:

Manajemen Sumber Daya

Server MCP dapat mengekspos sumber daya yang dapat didaftar dan dibaca oleh Claude:

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

// List available resources
for await (const message of query({
  prompt: "What resources are available from the database server?",
  options: {
    mcpServers: {
      "database": {
        command: "npx",
        args: ["@modelcontextprotocol/server-database"]
      }
    },
    allowedTools: ["mcp__list_resources", "mcp__read_resource"]
  }
})) {
  if (message.type === "result") console.log(message.result);
}

Autentikasi

Variabel Lingkungan

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

// Set environment variables
process.env.API_TOKEN = "your-token";
process.env.API_KEY = "your-key";

Autentikasi OAuth2

Autentikasi MCP OAuth2 dalam klien saat ini tidak didukung.

Penanganan Error

Tangani kegagalan koneksi MCP dengan baik:

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") {
    // Check MCP server status
    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");
  }
}

Sumber Daya Terkait

Panduan Alat Kustom - Panduan detail tentang membuat server MCP SDK
Referensi SDK TypeScript
Referensi SDK Python
Izin SDK
Alur Kerja Umum