Como criar um servidor MCP com o Claude Code: guia passo a passo (2026)

· Por Jasmine — uma dev que usa o Claude Code todos os dias e já escreveu à mão e colocou no ar alguns servidores MCP internos para o meu time.

O que é um servidor MCP? (recapitulando rápido)

Um servidor MCP é um pequeno processo que expõe três tipos de capacidade——tools (funções que um agente pode chamar), resources (dados que ele pode ler) e prompts (templates de prompt reutilizáveis)——para um LLM pelo Model Context Protocol. Dito de outro jeito, é um "adaptador" padronizado entre o Claude Code e o mundo externo: uma API interna, um banco de dados, o sistema de arquivos ou qualquer serviço que você queira que o Claude alcance de forma controlada.

O bacana do MCP é que ele é um padrão aberto: você escreve o servidor uma vez e usa em vários hosts (Claude Code, Claude Desktop e outros clientes). Este guia não vai se aprofundar no conceito——isso é assunto do artigo o que é MCP. Aqui o foco é escrever o próprio servidor e conectá-lo direto ao Claude Code, a parte que a documentação oficial costuma deixar solta.

Quando você realmente precisa escrever seu próprio servidor MCP?

Antes de digitar uma única linha de código, pergunte: alguém já escreveu esse servidor? Muitas necessidades comuns já têm servidores oficiais ou da comunidade——GitHub, Playwright, Sentry, sistema de arquivos e mais. Plugar um existente é sempre mais rápido do que construir do zero.

Minha regra de bolso: escreva seu próprio servidor MCP quando os dados ou a lógica são seus e ainda não existe um adaptador padrão. Não reescreva algo que outras pessoas já fazem bem.

Antes de começar

Uma checklist curtinha para você não tropeçar no meio do caminho:

• Claude Code instalado e com login feito (um plano Pro/Max ou uma chave de API, ambos funcionam).
• Runtime: Node.js 18+ (para TypeScript) ou Python 3.10+ (para Python).
• Escolha um SDK: FastMCP / o SDK de Python se você se sente à vontade em Python; o SDK de TypeScript (@modelcontextprotocol/sdk) se você vive no Node.
• Um objetivo concreto: por exemplo, "uma tool que busca um pedido na nossa API interna." Não comece com um servidor genérico que faz de tudo.

Se o Claude Code é novidade para você, leia primeiro o que é Claude Code para entender como rodar uma sessão e conceder permissões.

Opção 1 — Escrever o servidor MCP à mão

Fazer isso manualmente uma vez ajuda você a entender o que realmente acontece quando o Claude chama uma tool. Depois disso, você automatiza à vontade. Os cinco passos abaixo vão do projeto a um teste funcionando.

Passo 1 — Projete as tools em torno de fluxos de trabalho, não de endpoints

O erro mais comum é mapear cada endpoint REST um-para-um para uma tool. O resultado é um agente que precisa chamar cinco tools para fazer uma coisa só, e ele facilmente se perde. Em vez disso, projete de forma centrada no agente:

• Consolide operações por intenção: uma única tool get_order_summary devolve tudo de uma vez, em vez de obrigar o agente a costurar get_order + get_customer + get_items.
• Devolva uma saída que uma pessoa ou um agente consiga ler: nomes de campo claros, não códigos internos.
• Escreva mensagens de erro que "ensinem" o agente: relate o erro com uma dica de como corrigir, não só um stack trace.

Esses princípios vêm das boas práticas embutidas na skill ak-mcp-builder——a parte que muitos tutoriais genéricos pulam.

Passo 2 — Monte o esqueleto do projeto e instale o SDK

Nomeie as coisas com clareza para que fiquem óbvias depois: em Python use {service}_mcp, em TypeScript use {service}-mcp-server.

Python (FastMCP):

python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install "mcp[cli]" # or: pip install fastmcp

# server.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("orders_mcp")

if __name__ == "__main__":
 mcp.run() # defaults to the stdio transport

TypeScript (SDK do MCP):

npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node

// src/index.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({ name: "orders-mcp-server", version: "1.0.0" });

const transport = new StdioServerTransport();
await server.connect(transport);

Passo 3 — Escreva sua primeira tool (com um exemplo executável)

Uma boa tool tem três partes: um input schema enxuto, uma descrição clara (o agente a lê para saber quando chamar a tool) e tool annotations que descrevem o comportamento. Aqui está uma tool de consulta de pedido:

Python:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("orders_mcp")

@mcp.tool(
 annotations={
 "readOnlyHint": True, # read-only, does not change data
 "idempotentHint": True, # same result when called again
 "openWorldHint": True, # calls an external system
 }
)
def get_order_summary(order_id: str) -> str:
 """Look up a summary of one order by its order ID.
 Use when the user asks about the status/total/customer of a specific order."""
 order = fetch_order(order_id) # calls your internal API
 if order is None:
 return f"Order '{order_id}' not found. Double-check the ID (format ORD-xxxxx)."
 return (
 f"Order {order['id']} | Customer: {order['customer']} | "
 f"Status: {order['status']} | Total: ${order['total']:,}"
 )

TypeScript (usando Zod para o input schema):

import { z } from "zod";

server.registerTool(
 "get_order_summary",
 {
 description: "Look up a summary of one order by its order ID.",
 inputSchema: { order_id: z.string().describe("Order ID, format ORD-xxxxx") },
 annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
 },
 async ({ order_id }) => {
 const order = await fetchOrder(order_id);
 const text = order
 ? `Order ${order.id} | Customer: ${order.customer} | Status: ${order.status}`
 : `Order '${order_id}' not found.`;
 return { content: [{ type: "text", text }] };
 }
);

Saída de exemplo quando o Claude chama a tool: Order ORD-10231 | Customer: Alex Nguyen | Status: In transit | Total: $540. Uma ressalva: as annotations são apenas dicas para o host, não um mecanismo de segurança——não conte com readOnlyHint para bloquear escritas.

Passo 4 — Escolha um transporte (stdio / HTTP / SSE)

O transporte decide como o host conversa com o seu servidor. Escolha conforme a situação, em vez de ir no padrão às cegas:

Padrão para uso local + Claude Code: use stdio. Só migre para HTTP quando precisar compartilhar o servidor com várias pessoas ou implantá-lo remotamente.

Passo 5 — Rode e teste do jeito certo

É aqui que muita gente tropeça——e poucos tutoriais avisam:

• O servidor é um processo de longa duração. Rodar python server.py direto vai parecer que "travou" o terminal, porque ele está esperando entrada pelo stdio——isso é normal, não é bug. Para uma checagem rápida sem ficar preso, use timeout 5s python server.py, rode em tmux / num painel separado, ou use um harness de eval.
• Com stdio: nunca faça log no stdout. O stdout é o canal do protocolo——um print() perdido ali quebra o stream JSON-RPC e o servidor "morre" de um jeito confuso. Faça log no stderr (Python: print(..., file=sys.stderr) ou o módulo logging).
• Verifique primeiro se compila: Python python -m py_compile server.py; TypeScript npm run build.

A forma mais confiável de testar é orientada a eval: escreva um script que chama cada tool com entradas de exemplo e faz asserções sobre a saída, rodando num processo filho com um timeout. Assim você pega bugs de schema e de protocolo na hora, em vez de esperar até plugar no Claude Code e descobrir uma tool que devolve nada silenciosamente.

Opção 2 — Deixe o Claude Code escrever o servidor MCP para você

Depois que você entende a estrutura da Opção 1, não precisa redigitar boilerplate toda vez. Este é o "ângulo meta" divertido: usar o próprio Claude Code para escrever um servidor MCP para o Claude Code.

Um padrão de prompt de que eu gosto, dividido em pedaços para o agente não sair do foco:

Write a Python MCP server named orders_mcp using FastMCP.
- Tool get_order_summary(order_id) calls our internal API at BASE_URL (read from env).
- Tight input schema, clear description, readOnlyHint/idempotentHint annotations.
- Log to stderr, NOT stdout. Transport stdio.
Then write a test script that uses timeout so it does not hang, and explain how to wire it into Claude Code.

O Claude Code vai montar o esqueleto do projeto, escrever a tool + o schema e, se você pedir, escrever também o passo de teste. Seu trabalho principal é revisar——as partes repetitivas ficam com o agente. Dica: peça ao agente para declarar suas suposições (caminhos, nomes de variáveis de ambiente) antes de escrever, e faça-o rodar py_compile / npm run build ele mesmo para confirmar que o código compila ali na sessão. Assim você recebe um servidor que já passou por uma checagem básica, em vez de uma pilha de código sem teste.

Se você constrói muitos servidores, vale usar uma skill pronta em vez de lembrar cada boa prática por conta própria. O Engineer Kit da AgentKit (a skill ak-mcp-builder) traz um processo de construção de servidor MCP em várias fases (research -> implement -> review -> eval) que empacota as boas práticas de design de tools e um harness de eval para testar——assim você não precisa manter na cabeça todo o boilerplate e as armadilhas de stdio / longa duração acima. Para os detalhes, veja o que tem dentro do Engineer Kit da AgentKit.

Um esclarecimento para evitar confusão: "AgentKit" aqui é o kit de skills para o Claude Code (agentkit.best, a CLI ak), que é diferente do produto "AgentKit" da OpenAI. Minha abordagem: faça à mão uma vez para entender e depois use uma skill para ganhar velocidade.

Conectando o servidor MCP ao Claude Code

Agora que você tem um servidor, plugue-o no Claude Code. O comando central é claude mcp add.

Servidor stdio local——passe o comando depois do separador --:

claude mcp add orders -- python /path/to/server.py
# or a built TypeScript server:
claude mcp add orders -- node /path/to/dist/index.js

Servidor remoto (HTTP):

claude mcp add orders --transport http https://mcp.company.com/orders

Verifique a conexão:

claude mcp list # shows: orders ✔ Connected
claude mcp get orders # view a server's full configuration

O escopo decide onde o servidor fica disponível: local (só você, só neste projeto), project (commitado para o time todo), user (todos os seus projetos). Para um servidor compartilhado pelo time, escreva à mão um .mcp.json na raiz do repositório e faça o commit:

{
 "mcpServers": {
 "orders": {
 "command": "python",
 "args": ["server.py"],
 "env": { "BASE_URL": "https://api.internal.company.com" }
 }
 }
}

Depois de editar o .mcp.json, lembre-se de reiniciar a sessão do Claude Code para ele recarregar.

Problemas comuns e como resolver

Boas práticas para escrever servidores MCP

Fechando com o que vale a pena lembrar (boa parte tirada do ak-mcp-builder):

• Nomeie as tools com o padrão {service}_{action}_{resource} (snake_case), com um prefixo de serviço para evitar colisões quando vários servidores estão plugados.
• Suporte tanto JSON quanto Markdown na saída——agentes leem bem dados estruturados, pessoas leem a versão em Markdown com mais facilidade.
• Pagine as tools que devolvem muitos dados: use limit, has_more, next_offset em vez de devolver milhares de linhas.
• Limite o tamanho da saída (regra de bolso ~25.000 caracteres) e trunque com orientação ("mais N resultados, use offset...").
• Faça as mensagens de erro serem acionáveis: diga exatamente o que deu errado e como corrigir.
• Segurança: valide a entrada, mantenha as chaves de API no ambiente (nunca hardcode) e não vaze erros internos / stack traces para o agente. Lembre-se de que as annotations são só dicas, não um substituto para controle de acesso de verdade.

Quer automatizar mais do seu fluxo de desenvolvimento? Veja como criar uma skill personalizada para o Claude Code e usar subagents no Claude Code para dividir o trabalho de build/teste.

Perguntas frequentes (FAQ)

Em qual linguagem devo escrever um servidor MCP?

As escolhas mais comuns são Python (FastMCP / SDK de Python) e TypeScript (@modelcontextprotocol/sdk). O MCP tem SDKs para outras linguagens também, mas para o Claude Code, Python ou TS são as opções mais rápidas e com mais exemplos.

Como isso é diferente de conectar a um servidor existente?

Conectar a um servidor existente só precisa de claude mcp add apontando para um que outra pessoa já escreveu. Escrever seu próprio servidor é para quando você precisa expor sua própria lógica/dados (uma API interna, um DB) que ninguém ainda empacotou num adaptador.

O Claude Code consegue escrever um servidor MCP sozinho?

Sim. Descreva a tool, o schema e o transporte que você quer, e o Claude Code vai montar o esqueleto do projeto, escrever a tool e até um script de teste. Você só revisa. A skill ak-mcp-builder empacota esse processo junto com as boas práticas.

Como implanto um servidor remoto (HTTP)?

Rode o servidor com o transporte streamable HTTP na sua própria infraestrutura e depois claude mcp add <name> --transport http <url>. Um servidor remoto precisa cuidar também da autenticação (OAuth/token)——diferente de um servidor stdio local, que confia na sua máquina.

Preciso do Claude Code Pro?

Nenhum plano específico é exigido. O MCP funciona com o Claude Code assim que você faz login——um plano Pro/Max ou uma chave de API, ambos funcionam. Escrever um servidor não custa nada além do uso do modelo que você já paga.

O que é o ak-mcp-builder e ele é obrigatório?

O ak-mcp-builder é uma skill do Engineer Kit da AgentKit que constrói servidores MCP por um processo de várias fases com um harness de eval. Ele não é obrigatório——você pode escrever tudo à mão como na Opção 1. Ele só deixa as coisas mais rápidas e ajuda a evitar as armadilhas de boas práticas quando você constrói muitos servidores.

Conclusão e próximos passos

Recapitulando, há duas formas de criar um servidor MCP com o Claude Code: escrever à mão (projetar as tools em torno de fluxos -> instalar o SDK -> escrever a tool -> escolher um transporte -> testar com timeout/stderr) para entender a fundo, e deixar o Claude Code escrever para você quando você precisa de velocidade. De qualquer forma, o ponto crucial é conectá-lo ao Claude Code com claude mcp add ou .mcp.json e confirmar ✔ Connected. Meu conselho: faça à mão uma vez para entender e depois automatize.

Como próximo passo, tente transformar esse processo de construção na sua própria skill personalizada. E se você quer um processo de construção de servidor MCP padronizado e pronto para eval logo de cara, dê uma olhada no Engineer Kit da AgentKit — 20% de desconto, agora $79.20 (a skill ak-mcp-builder).

Fontes: Model Context Protocol - especificação e guia de como construir um servidor (versão de 2026-07-28); documentação do Claude Code - MCP e claude mcp add (v2.1.219). Verifique os comandos exatos antes de usar, já que a CLI é atualizada rapidamente.