Constrói o Teu Próprio Servidor MCP para Claude Code

Problema: Os servidores MCP públicos não falam com os sistemas que tu realmente usas. A tua API interna, o Postgres da empresa, um workflow personalizado que mais ninguém toca. Para o Claude Code chegar a esses, tens de escrever o servidor tu mesmo.

Vitória Rápida: Cinco minutos de Node.js põe o Claude a falar com qualquer API REST:

// my-api-server.js - Connect Claude to your API
const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
 
const server = new Server({ name: "my-api-server", version: "1.0.0" });
 
server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "fetch_user_data",
      description: "Get user information from our internal API",
      inputSchema: {
        type: "object",
        properties: {
          userId: { type: "string", description: "User ID to fetch" },
        },
        required: ["userId"],
      },
    },
  ],
}));
 
server.setRequestHandler("tools/call", async (request) => {
  const { name, arguments: args } = request.params;
 
  if (name === "fetch_user_data") {
    const response = await fetch(
      `https://api.yourcompany.com/users/${args.userId}`,
      {
        headers: { Authorization: `Bearer ${process.env.API_TOKEN}` },
      },
    );
    return {
      content: [{ type: "text", text: JSON.stringify(await response.json()) }],
    };
  }
});
 
server.connect(process.stdio);

Guarda o ficheiro como my-api-server.js. Corre node my-api-server.js para o testar. Isso é uma integração funcional.

O Que é um Servidor MCP na Prática

Um servidor MCP é um processo Node.js que entrega ao Claude Code uma lista de tools que pode chamar. Corre por conta própria, separado do editor, e dá ao Claude um canal para tudo o que podes alcançar a partir de Node: APIs, bases de dados, serviços internos.

Cada servidor tem quatro coisas:

Definições de tools: as funções que o Claude pode chamar
Handlers de tools: o código que corre quando o Claude chama uma
Tratamento de erros: mensagens úteis quando a chamada falha
Autenticação: uma forma segura de alcançar os sistemas por trás

Padrões que Cobrem a Maioria dos Casos

Falar com uma API REST

Aponta o Claude para qualquer endpoint HTTP com um conector pequeno:

// Generic API connector pattern
const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
 
const server = new Server({ name: "api-connector", version: "1.0.0" });
 
server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "api_get",
      description: "GET request to any endpoint",
      inputSchema: {
        type: "object",
        properties: {
          endpoint: { type: "string", description: "API endpoint path" },
          params: { type: "object", description: "Query parameters" },
        },
        required: ["endpoint"],
      },
    },
  ],
}));
 
server.setRequestHandler("tools/call", async (request) => {
  const { name, arguments: args } = request.params;
 
  if (name === "api_get") {
    const url = new URL(`${process.env.API_BASE_URL}${args.endpoint}`);
    if (args.params) {
      Object.entries(args.params).forEach(([key, value]) =>
        url.searchParams.append(key, value),
      );
    }
 
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.API_TOKEN}` },
    });
 
    return {
      content: [
        { type: "text", text: JSON.stringify(await response.json(), null, 2) },
      ],
    };
  }
});
 
server.connect(process.stdio);

A mesma forma funciona para Stripe, Shopify, o teu dashboard interno, tudo o que fala HTTP.

Falar com uma Base de Dados

Troca a chamada fetch por um cliente de base de dados:

// Database connector for PostgreSQL, MySQL, SQLite
const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
const { Client } = require("pg");
 
const server = new Server({ name: "database-connector", version: "1.0.0" });
const client = new Client({ connectionString: process.env.DATABASE_URL });
 
server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "query_database") {
    const result = await client.query(request.params.arguments.query);
    return {
      content: [{ type: "text", text: JSON.stringify(result.rows, null, 2) }],
    };
  }
});

O Claude pode agora correr SQL e ajudar com trabalho de base de dados.

Configuração e Testes

Inicia o projeto:

mkdir my-mcp-server && cd my-mcp-server
npm init -y && npm install @modelcontextprotocol/sdk

Depois aponta o Claude Code para o servidor a partir do seu ficheiro de config MCP. Onde esse ficheiro fica depende de como corres o Claude:

Claude Code CLI: ~/.claude.json (nível de utilizador) ou .mcp.json (nível de projeto)
Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "my-custom-server": {
      "command": "node",
      "args": ["/path/to/your/server.js"],
      "env": { "API_TOKEN": "your-token" }
    }
  }
}

Reinicia o Claude Code depois de guardar. O novo servidor carrega no arranque.

Quando as Coisas Falham

Servidor não encontrado: o caminho na config ou o JSON está errado. Verifica bem a localização do ficheiro. Usa um caminho absoluto para command.

Timeout da tool: chamadas demoradas bloqueiam a tool. Envolve-as no teu próprio timeout para que falhem de forma limpa.

Autenticação falhou: as variáveis de ambiente na config não estão a chegar ao servidor. Verifica se estão escritas corretamente e presentes.

Coisas que Vale a Pena Fazer Desde o Início

Cada chamada externa vai num try-catch para que os erros apareçam como texto, não como crashes
Os tokens vivem em variáveis de ambiente, nunca no código fonte
APIs com rate limit precisam do seu próprio throttle para o Claude não queimar a tua quota
A saída de console.log aparece nos logs do Claude, por isso usa-a à vontade para debugging

Próximos Passos

Escolhe uma coisa para ligar e constrói a partir daí:

Começa com uma API: a que usas todos os dias
Copia o padrão REST: o conector acima é o template
Confirma que carregou: pergunta ao Claude "What MCP tools are available?" e a tua nova tool deve aparecer
Escreve boas descrições de tools: o MCP Tool Search usa-as para decidir quando carregar o teu servidor
Lê mais: o guia de fundamentos MCP e a lista de servidores MCP populares cobrem o que construir a seguir

Um servidor MCP personalizado transforma o Claude Code num cliente para o teu próprio stack. Um servidor por semana e a lista de coisas que o Claude pode alcançar vai crescendo silenciosamente.

Constrói o Teu Próprio Servidor MCP para Claude Code

On this page