As ferramentas personalizadas permitem que você estenda as capacidades do Claude Code com sua própria funcionalidade através de servidores MCP em processo, permitindo que o Claude interaja com serviços externos, APIs ou execute operações especializadas.

​
Criando Ferramentas Personalizadas

Use as funções auxiliares createSdkMcpServer e tool para definir ferramentas personalizadas com segurança de tipos: 
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

// Criar um servidor MCP SDK com ferramentas personalizadas
const customServer = createSdkMcpServer({
  name: "my-custom-tools",
  version: "1.0.0",
  tools: [
    tool(
      "get_weather",
      "Get current weather for a location",
      {
        location: z.string().describe("City name or coordinates"),
        units: z.enum(["celsius", "fahrenheit"]).default("celsius").describe("Temperature units")
      },
      async (args) => {
        // Chamar API do clima
        const response = await fetch(
          `https://api.weather.com/v1/current?q=${args.location}&units=${args.units}`
        );
        const data = await response.json();
        
        return {
          content: [{
            type: "text",
            text: `Temperature: ${data.temp}°\nConditions: ${data.conditions}\nHumidity: ${data.humidity}%`
          }]
        };
      }
    )
  ]
});

​
Usando Ferramentas Personalizadas

Passe o servidor personalizado para a função query através da opção mcpServers como um dicionário/objeto.
Importante: Ferramentas MCP personalizadas requerem modo de entrada de streaming. Você deve usar um gerador/iterável assíncrono para o parâmetro prompt - uma string simples não funcionará com servidores MCP.

​
Formato do Nome da Ferramenta

Quando as ferramentas MCP são expostas ao Claude, seus nomes seguem um formato específico:
  • Padrão: mcp__{server_name}__{tool_name}
  • Exemplo: Uma ferramenta chamada get_weather no servidor my-custom-tools se torna mcp__my-custom-tools__get_weather

​
Configurando Ferramentas Permitidas

Você pode controlar quais ferramentas o Claude pode usar através da opção allowedTools: 
import { query } from "@anthropic-ai/claude-code";

// Usar as ferramentas personalizadas em sua consulta com entrada de streaming
async function* generateMessages() {
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "What's the weather in San Francisco?"
    }
  };
}

for await (const message of query({
  prompt: generateMessages(),  // Usar gerador assíncrono para entrada de streaming
  options: {
    mcpServers: {
      "my-custom-tools": customServer  // Passar como objeto/dicionário, não array
    },
    // Opcionalmente especificar quais ferramentas o Claude pode usar
    allowedTools: [
      "mcp__my-custom-tools__get_weather",  // Permitir a ferramenta do clima
      // Adicionar outras ferramentas conforme necessário
    ],
    maxTurns: 3
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

​
Exemplo de Múltiplas Ferramentas

Quando seu servidor MCP tem múltiplas ferramentas, você pode permiti-las seletivamente: 
const multiToolServer = createSdkMcpServer({
  name: "utilities",
  version: "1.0.0",
  tools: [
    tool("calculate", "Perform calculations", { /* ... */ }, async (args) => { /* ... */ }),
    tool("translate", "Translate text", { /* ... */ }, async (args) => { /* ... */ }),
    tool("search_web", "Search the web", { /* ... */ }, async (args) => { /* ... */ })
  ]
});

// Permitir apenas ferramentas específicas com entrada de streaming
async function* generateMessages() {
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Calculate 5 + 3 and translate 'hello' to Spanish"
    }
  };
}

for await (const message of query({
  prompt: generateMessages(),  // Usar gerador assíncrono para entrada de streaming
  options: {
    mcpServers: {
      utilities: multiToolServer
    },
    allowedTools: [
      "mcp__utilities__calculate",   // Permitir calculadora
      "mcp__utilities__translate",   // Permitir tradutor
      // "mcp__utilities__search_web" NÃO é permitido
    ]
  }
})) {
  // Processar mensagens
}

​
Segurança de Tipos com Python

O decorador @tool suporta várias abordagens de definição de esquema para segurança de tipos: 
import { z } from "zod";

tool(
  "process_data",
  "Process structured data with type safety",
  {
    // Esquema Zod define tanto validação em tempo de execução quanto tipos TypeScript
    data: z.object({
      name: z.string(),
      age: z.number().min(0).max(150),
      email: z.string().email(),
      preferences: z.array(z.string()).optional()
    }),
    format: z.enum(["json", "csv", "xml"]).default("json")
  },
  async (args) => {
    // args é totalmente tipado baseado no esquema
    // TypeScript sabe: args.data.name é string, args.data.age é number, etc.
    console.log(`Processing ${args.data.name}'s data as ${args.format}`);
    
    // Sua lógica de processamento aqui
    return {
      content: [{
        type: "text",
        text: `Processed data for ${args.data.name}`
      }]
    };
  }
)

​
Tratamento de Erros

Trate erros graciosamente para fornecer feedback significativo: 
tool(
  "fetch_data",
  "Fetch data from an API",
  {
    endpoint: z.string().url().describe("API endpoint URL")
  },
  async (args) => {
    try {
      const response = await fetch(args.endpoint);
      
      if (!response.ok) {
        return {
          content: [{
            type: "text",
            text: `API error: ${response.status} ${response.statusText}`
          }]
        };
      }
      
      const data = await response.json();
      return {
        content: [{
          type: "text",
          text: JSON.stringify(data, null, 2)
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Failed to fetch data: ${error.message}`
        }]
      };
    }
  }
)

​
Ferramentas de Exemplo

​
Ferramenta de Consulta de Banco de Dados

const databaseServer = createSdkMcpServer({
  name: "database-tools",
  version: "1.0.0",
  tools: [
    tool(
      "query_database",
      "Execute a database query",
      {
        query: z.string().describe("SQL query to execute"),
        params: z.array(z.any()).optional().describe("Query parameters")
      },
      async (args) => {
        const results = await db.query(args.query, args.params || []);
        return {
          content: [{
            type: "text",
            text: `Found ${results.length} rows:\n${JSON.stringify(results, null, 2)}`
          }]
        };
      }
    )
  ]
});

​
Ferramenta de Gateway de API

const apiGatewayServer = createSdkMcpServer({
  name: "api-gateway",
  version: "1.0.0",
  tools: [
    tool(
      "api_request",
      "Make authenticated API requests to external services",
      {
        service: z.enum(["stripe", "github", "openai", "slack"]).describe("Service to call"),
        endpoint: z.string().describe("API endpoint path"),
        method: z.enum(["GET", "POST", "PUT", "DELETE"]).describe("HTTP method"),
        body: z.record(z.any()).optional().describe("Request body"),
        query: z.record(z.string()).optional().describe("Query parameters")
      },
      async (args) => {
        const config = {
          stripe: { baseUrl: "https://api.stripe.com/v1", key: process.env.STRIPE_KEY },
          github: { baseUrl: "https://api.github.com", key: process.env.GITHUB_TOKEN },
          openai: { baseUrl: "https://api.openai.com/v1", key: process.env.OPENAI_KEY },
          slack: { baseUrl: "https://slack.com/api", key: process.env.SLACK_TOKEN }
        };
        
        const { baseUrl, key } = config[args.service];
        const url = new URL(`${baseUrl}${args.endpoint}`);
        
        if (args.query) {
          Object.entries(args.query).forEach(([k, v]) => url.searchParams.set(k, v));
        }
        
        const response = await fetch(url, {
          method: args.method,
          headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
          body: args.body ? JSON.stringify(args.body) : undefined
        });
        
        const data = await response.json();
        return {
          content: [{
            type: "text",
            text: JSON.stringify(data, null, 2)
          }]
        };
      }
    )
  ]
});

​
Ferramenta de Calculadora

const calculatorServer = createSdkMcpServer({
  name: "calculator",
  version: "1.0.0",
  tools: [
    tool(
      "calculate",
      "Perform mathematical calculations",
      {
        expression: z.string().describe("Mathematical expression to evaluate"),
        precision: z.number().optional().default(2).describe("Decimal precision")
      },
      async (args) => {
        try {
          // Use uma biblioteca de avaliação matemática segura em produção
          const result = eval(args.expression); // Apenas exemplo!
          const formatted = Number(result).toFixed(args.precision);
          
          return {
            content: [{
              type: "text",
              text: `${args.expression} = ${formatted}`
            }]
          };
        } catch (error) {
          return {
            content: [{
              type: "text",
              text: `Error: Invalid expression - ${error.message}`
            }]
          };
        }
      }
    ),
    tool(
      "compound_interest",
      "Calculate compound interest for an investment",
      {
        principal: z.number().positive().describe("Initial investment amount"),
        rate: z.number().describe("Annual interest rate (as decimal, e.g., 0.05 for 5%)"),
        time: z.number().positive().describe("Investment period in years"),
        n: z.number().positive().default(12).describe("Compounding frequency per year")
      },
      async (args) => {
        const amount = args.principal * Math.pow(1 + args.rate / args.n, args.n * args.time);
        const interest = amount - args.principal;
        
        return {
          content: [{
            type: "text",
            text: `Investment Analysis:\n` +
                  `Principal: $${args.principal.toFixed(2)}\n` +
                  `Rate: ${(args.rate * 100).toFixed(2)}%\n` +
                
                  `Time: ${args.time} years\n` +
                  `Compounding: ${args.n} times per year\n\n` +
                  `Final Amount: $${amount.toFixed(2)}\n` +
                  `Interest Earned: $${interest.toFixed(2)}\n` +
                  `Return: ${((interest / args.principal) * 100).toFixed(2)}%`
          }]
        };
      }
    )
  ]
});

​
Documentação Relacionada