​
Panoramica

I server Model Context Protocol (MCP) estendono Claude Code con strumenti e capacità personalizzate. Gli MCP possono essere eseguiti come processi esterni, connettersi tramite HTTP/SSE, o essere eseguiti direttamente all’interno della tua applicazione SDK.

​
Configurazione

​
Configurazione di Base

Configura i server MCP in .mcp.json nella radice del tuo progetto: 
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem"],
      "env": {
        "ALLOWED_PATHS": "/Users/me/projects"
      }
    }
  }
}

​
Utilizzo dei Server MCP nell’SDK

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

for await (const message of query({
  prompt: "Elenca i file nel mio progetto",
  options: {
    mcpConfig: ".mcp.json",
    allowedTools: ["mcp__filesystem__list_files"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

​
Tipi di Trasporto

​
Server stdio

Processi esterni che comunicano tramite stdin/stdout: 
// configurazione .mcp.json
{
  "mcpServers": {
    "my-tool": {
      "command": "node",
      "args": ["./my-mcp-server.js"],
      "env": {
        "DEBUG": "${DEBUG:-false}"
      }
    }
  }
}

​
Server HTTP/SSE

Server remoti con comunicazione di rete: 
// configurazione server SSE
{
  "mcpServers": {
    "remote-api": {
      "type": "sse",
      "url": "https://api.example.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

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

​
Server MCP SDK

Server in-process che vengono eseguiti all’interno della tua applicazione. Per informazioni dettagliate sulla creazione di strumenti personalizzati, consulta la guida agli Strumenti Personalizzati:

​
Gestione delle Risorse

I server MCP possono esporre risorse che Claude può elencare e leggere: 
import { query } from "@anthropic-ai/claude-agent-sdk";

// Elenca le risorse disponibili
for await (const message of query({
  prompt: "Quali risorse sono disponibili dal server del database?",
  options: {
    mcpConfig: ".mcp.json",
    allowedTools: ["mcp__list_resources", "mcp__read_resource"]
  }
})) {
  if (message.type === "result") console.log(message.result);
}

​
Autenticazione

​
Variabili d’Ambiente

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

// Imposta le variabili d'ambiente
process.env.API_TOKEN = "your-token";
process.env.API_KEY = "your-key";

​
Autenticazione OAuth2

L’autenticazione MCP OAuth2 in-client non è attualmente supportata.

​
Gestione degli Errori

Gestisci i fallimenti di connessione MCP con eleganza: 
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Elabora i dati",
  options: {
    mcpServers: {
      "data-processor": dataServer
    }
  }
})) {
  if (message.type === "system" && message.subtype === "init") {
    // Controlla lo stato del server MCP
    const failedServers = message.mcp_servers.filter(
      s => s.status !== "connected"
    );
    
    if (failedServers.length > 0) {
      console.warn("Connessione fallita:", failedServers);
    }
  }
  
  if (message.type === "result" && message.subtype === "error_during_execution") {
    console.error("Esecuzione fallita");
  }
}

​
Risorse Correlate