Crie um MCP Server para Claude Code — um guia prático, passo a passo - CometAPI

O Model Context Protocol (MCP) é um padrão aberto que permite que modelos como o Claude da Anthropic e ferramentas de desenvolvedor como o Claude Code chamem ferramentas externas, fontes de dados e prompts de maneira segura e padronizada.

Este guia vai orientar você na criação do seu próprio servidor MCP do zero, permitindo que o Claude Code acesse recursos personalizados e, assim, amplie muito sua funcionalidade além dos recursos nativos.

O que é o Model Context Protocol (MCP)?

MCP (Model Context Protocol) é uma especificação aberta projetada para padronizar como clientes de modelos de linguagem (como Claude, Claude Code ou outros frontends de LLM) se conectam a servidores de ferramentas e fontes de dados. Pense no MCP como uma “porta USB‑C para LLMs”: ele define um transporte/esquema JSON‑RPC e uma forma comum para servidores publicarem três tipos de capacidades:

Recursos — dados semelhantes a arquivos ou documentos que um cliente pode ler (por exemplo, uma linha de banco de dados, um arquivo de texto, um payload JSON).
Ferramentas — funções invocáveis que o modelo pode pedir ao host para executar (com aprovação do usuário).
Prompts — templates de prompt reutilizáveis ou fluxos que o modelo/cliente pode invocar.

O MCP oferece suporte a múltiplos transportes (stdio, HTTP, SSE) e fornece esquemas, SDKs e servidores de exemplo para que você não precise inventar o formato de comunicação. O protocolo é mantido publicamente (spec + SDKs) e possui tutoriais e uma galeria de servidores de exemplo para acelerar a adoção.

Como o MCP é arquitetado?

A arquitetura do MCP é propositalmente simples e modular: as peças centrais são servidores MCP, clientes MCP e transportes que carregam mensagens enquadradas em JSON‑RPC entre eles. A seguir estão os principais componentes com os quais você interagirá ao criar um servidor para o Claude Code (ou outros clientes MCP).

Servidor, cliente e o protocolo

Servidor MCP — Um serviço que publica ferramentas, recursos e prompts. Ferramentas podem realizar efeitos colaterais ou buscar dados; recursos expõem conteúdo somente leitura; prompts são templates reutilizáveis que o cliente pode pedir ao modelo para amostrar.
Cliente MCP (host) — Normalmente parte do host do LLM (por exemplo, Claude Code, plugin do VS Code, um cliente de navegador). Ele descobre servidores disponíveis, apresenta descrições de ferramentas ao modelo e roteia chamadas iniciadas pelo modelo para os servidores.
Protocolo — As mensagens são codificadas como JSON‑RPC; a especificação define eventos de ciclo de vida, descoberta de ferramentas, invocação, completions/amostragem e como resultados estruturados são retornados ao cliente e ao modelo.

Padrão de comunicação (o que acontece quando uma ferramenta é usada)

O cliente envia a mensagem do usuário ao modelo.
O modelo analisa o contexto e decide chamar uma ferramenta exposta pelo MCP (ou múltiplas ferramentas).
O cliente encaminha a chamada da ferramenta ao servidor MCP pelo transporte escolhido.
O servidor executa a ferramenta e retorna os resultados.
O modelo recebe a saída da ferramenta e compõe a resposta final ao usuário.

Primitivas de implementação

Mensagens JSON‑RPC seguem o esquema do MCP.
Definições de ferramentas são publicadas nas respostas de descoberta do servidor para que os clientes possam apresentá‑las na interface.
Recursos são referenciados pela sintaxe @source:path pelos clientes (por exemplo, @postgres:...), permitindo que modelos se refiram a conteúdo externo sem inserir grandes quantidades de dados no prompt.

Por que integrar o Claude Code com servidores MCP?

O Claude Code é a oferta da Anthropic focada em fluxos de trabalho de código e desenvolvedor (integração com editor/IDE, compreensão de código etc.). Expor suas ferramentas internas (busca em código‑fonte, executor de CI, sistema de tickets, registries privados) por meio de servidores MCP permite que o Claude Code as chame como ferramentas de primeira classe dentro de conversas de código e fluxos de agentes.

Integrar o Claude Code com servidores MCP desbloqueia capacidades práticas e relevantes para produção para um agente de programação:

1. Permitir que o modelo atue em sistemas reais

O Claude Code pode solicitar a um servidor MCP que consulte rastreadores de issues, execute consultas em banco de dados, leia documentos extensos ou produza PRs no GitHub — viabilizando automação ponta a ponta dentro da sessão de codificação. Isso é explicitamente suportado pela documentação do Claude Code (exemplos: consultar Postgres, Sentry ou criar PRs).

2. Descarregar grandes volumes de dados e lógica especializada

Em vez de incorporar cada fonte de dados no prompt (o que consome tokens), você publica dados e ferramentas via MCP. O modelo chama a ferramenta, recebe uma resposta estruturada e raciocina com ela — isso reduz o uso de tokens e permite que servidores lidem com trabalho pesado (consultas de BD, leitura de arquivos longos, autenticação).

3. Segurança e governança

O MCP centraliza controle de acesso e auditoria na camada do servidor, permitindo que organizações incluam na lista de permissões servidores aprovados, controlem quais ferramentas estão disponíveis e limitem saídas. O Claude Code também suporta configuração de MCP corporativa e consentimento por escopo.

4. Reutilização e ecossistema

Servidores MCP são reutilizáveis entre clientes e equipes. Construa uma vez e muitos clientes Claude/LLM podem usar os mesmos serviços (ou trocar implementações).

O que você precisa antes de começar?

Requisitos mínimos

Uma máquina de desenvolvimento com Python 3.10+ (usaremos Python no exemplo). Alternativamente, Node / outras linguagens são suportadas pelos SDKs do MCP.
uv (ferramenta da Astral) ou runner equivalente para executar servidores MCP via stdio (o tutorial do MCP usa uv). Etapas de instalação abaixo.
Claude Code instalado ou acesso ao cliente Claude (desktop ou CLI) para registrar e testar seu servidor; ou qualquer cliente compatível com MCP. O Claude Code suporta HTTP, SSE e servidores stdio locais.
Nota de segurança: Adicione apenas servidores MCP confiáveis ao Claude Code em configurações de equipe ou empresa — o MCP dá aos servidores acesso a dados sensíveis, e há riscos de prompt injection se um servidor retornar conteúdo malicioso.

Como instalar e verificar o CLI do Claude Code

Este é o Guia de Instalação e Uso do Claude Code.

1) Resumo rápido — métodos de instalação recomendados

Use o instalador nativo (recomendado) ou Homebrew no macOS/Linux. NPM está disponível se você precisar de uma instalação baseada em Node. No Windows há instaladores para PowerShell / CMD. Fonte: documentação oficial do Claude Code e GitHub.

2) Pré-requisitos

macOS 10.15+, Ubuntu 20.04+/Debian 10+, ou Windows 10+ (WSL recomendado no Windows).
Node.js 18+ necessário apenas para o método de instalação via NPM.

3) Comandos de instalação (escolha um)

Nativo (recomendado — sem dependência de Node), macOS / Linux / WSL:

curl -fsSL https://claude.ai/install.sh | bash
# optional: install latest explicitly

curl -fsSL https://claude.ai/install.sh | bash -s latest
# or install a specific version

curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex
# or for latest: & (::Create((irm https://claude.ai/install.ps1))) latest

(Estes são os scripts oficiais do instalador nativo).

NPM (se você quiser uma instalação global baseada em Node):

# requires Node.js 18+

npm install -g @anthropic-ai/claude-code

Não use sudo npm install -g — evite instalações globais com sudo (problemas de permissão/segurança). Se você enfrentar erros de permissão, use nvm ou corrija seu prefixo global do npm em vez de usar sudo.

4) Verificar se o binário foi instalado (checagens básicas)

Execute localmente imediatamente após a instalação:

# is the command on PATH?

which claude

# version (or -v)

claude --version
# or

claude -v

# help (sanity check)

claude --help

Esperado: which mostra um caminho (por exemplo, /usr/local/bin/claude ou ~/.nvm/.../bin/claude) e claude --version imprime uma string semelhante a semver. A documentação e o README mostram claude como o comando principal do CLI.

5) Verificar integridade da instalação e configuração (checagens recomendadas)

a) `claude doctor` — Execute:

claude doctor

Este diagnóstico embutido verifica seu tipo de instalação, problemas comuns (como problemas de permissão do npm), dependências como ripgrep, e sugere correções. A documentação recomenda executar claude doctor após a instalação.

b) Executar um smoke test (não interativo)

No diretório do seu projeto:

cd /path/to/your/project
claude -p "Explain this project in 3 sentences"

Isso usa o modo print (-p) para enviar um único prompt e sair; bom para CI ou checagens rápidas de funcionalidade.

c) Verificação de autenticação (garantir que o CLI consegue alcançar a Anthropic)

O Claude Code suporta vários fluxos de autenticação (Console OAuth, chave de API, integrações de provedores). Checagens comuns:

Se estiver usando uma chave de API (CI / headless / variável de ambiente local):

export ANTHROPIC_API_KEY="sk-..."
# then

claude auth status
claude auth whoami    # or `claude auth whoami` / `claude whoami` depending on version

Você pode usar a chave de API da CometAPI para usar o Claude Code. Usar a API do Claude por meio da CometAPI lhe dará um desconto de 20%.

Se você usou OAuth pelo console — execute:

claude auth status
claude auth whoami

Você deve ver informações de conta/plano ou uma confirmação de que está autenticado.

Preparação de ambiente passo a passo

A seguir estão etapas concretas para preparar duas stacks comuns de desenvolvimento (TypeScript e Python), seguidas de checagens rápidas para garantir que tudo funciona.

H3 — A. Configuração TypeScript / Node (caminho mais rápido)

Crie o projeto e instale o SDK:

mkdir mcp-demo && cd mcp-demo
npm init -y
npm install @modelcontextprotocol/sdk express zod
npm install --save-dev typescript tsx @types/node @types/express

Crie server.ts. (Fornecemos um exemplo completo na seção “Como construir rapidamente...”)
Execute:

npx -y tsx server.ts

Teste localmente com o MCP Inspector ou adicione ao Claude Code:

npx @modelcontextprotocol/inspector
# or (for Claude Code)

claude mcp add --transport http my-server http://localhost:3000/mcp

(O Inspector e os comandos do Claude permitem validar a descoberta e invocar ferramentas.)

Como construir rapidamente um servidor MCP para o Claude Code?

Checklist rápido

Inicie seu servidor (HTTP streamable recomendado): node server.ts ou uvicorn server:app.
Da sua máquina de desenvolvimento, você pode:

Usar o MCP Inspector para validar (npx @modelcontextprotocol/inspector) e confirmar tools/list e resources/list; ou
Adicionar o servidor ao Claude Code: claude mcp add --transport http <name> http://<host>:<port>/mcp (ou seguir os fluxos de UI web se seu cliente suportar MCP remoto).

Se você planeja usar o conector do Messages API da Anthropic para MCP remoto (sem cliente separado), leia a documentação do Claude — pode ser necessário um header beta (verifique a documentação para o header exato e o status de suporte atual).

Abaixo estão dois exemplos completos porém compactos de servidor que você pode copiar, executar e conectar ao Claude Code (ou ao MCP Inspector). O exemplo em TypeScript usa Express + o SDK em TypeScript; o exemplo em Python demonstra um FastAPI montado.

Nota: o código abaixo segue os exemplos públicos do SDK e é intencionalmente mínimo para clareza. Em produção, adicione autenticação, logging, rate limiting e validação de entrada além dos padrões do SDK.

Exemplo 1: TypeScript + Express (HTTP streamable)

Crie server.ts (completo):

// server.ts
import express from "express";
import * as z from "zod/v4";
import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

const server = new McpServer({ name: "claude-code-demo", version: "0.1.0" });

// Register a simple tool: add two numbers
server.registerTool(
  "add",
  {
    title: "Add",
    description: "Add two numbers a and b",
    inputSchema: { a: z.number(), b: z.number() },
    outputSchema: { result: z.number() }
  },
  async ({ a, b }) => {
    const output = { result: a + b };
    return {
      content: ,
      structuredContent: output
    };
  }
);

// Register a resource: greet user (dynamic)
server.registerResource(
  "greeting",
  new ResourceTemplate("greeting://{name}", { list: undefined }),
  { title: "Greeting", description: "Return a greeting for the name" },
  async (uri, params) => {
    return {
      contents: 
    };
  }
);

// Express + Streamable HTTP transport
const app = express();
app.use(express.json());

app.post("/mcp", async (req, res) => {
  const transport = new StreamableHTTPServerTransport({ enableJsonResponse: true });
  // Close transport when connection closes
  res.on("close", () => transport.close());
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

const port = parseInt(process.env.PORT || "3000", 10);
app.listen(port, () => console.log(`MCP server listening: http://localhost:${port}/mcp`));

Executar:

npm install
npx -y tsx server.ts

Depois conecte no Claude Code (exemplo):

# Add the remote server to your Claude Code MCP list (local dev)

claude mcp add --transport http my-demo http://localhost:3000/mcp

Este exemplo é adaptado do Quick Start oficial do SDK TypeScript e demonstra como registrar ferramentas e recursos, e então expô‑los via HTTP streamable.

Exemplo 2: Python + FastAPI (FastMCP + HTTP streamable)

Crie server.py (completo):

# server.py

from fastapi import FastAPI
from mcp.server.fastmcp import FastMCP

app = FastAPI()
mcp = FastMCP("claude-python-demo", stateless_http=True)

# tool: simple sum

@mcp.tool()
def add(a: int, b: int) -> dict:
    """Add two integers"""
    return {"result": a + b}

# resource: simple greeting resource template

@mcp.resource("greeting://{name}")
def greeting(name: str):
    return {"contents": }

# mount the streamable-http MCP endpoint (FastMCP exposes an ASGI app)

app.mount("/mcp", mcp.streamable_http_app())

# optional endpoint to demonstrate other API routes

@app.get("/")
async def root():
    return {"status": "OK"}

Executar:

uvicorn server:app --reload --port 8000

Conecte com o Inspector:

npx @modelcontextprotocol/inspector
# In Inspector select Streamable HTTP and enter http://localhost:8000/mcp

Os exemplos do SDK em Python e as utilidades FastMCP tornam simples registrar funções decoradas com @mcp.tool() e @mcp.resource() que o LLM pode descobrir e chamar.

Como o Claude Code realmente chama suas ferramentas?

Quando um LLM decide usar uma ferramenta, o cliente envia uma invocação JSON‑RPC para o servidor MCP. O servidor executa a ferramenta solicitada (por exemplo, consulta um BD, executa testes ou chama uma API externa) e retorna conteúdo estruturado e conteúdo apresentável. O cliente (Claude Code) pode então incluir a saída estruturada no contexto do modelo para que o modelo continue raciocinando com esses dados confiáveis — não apenas a saída textual do servidor. O SDK em TypeScript suporta registrar inputSchema e outputSchema (zod) para que argumentos e saídas sejam validados e tipados de forma programática.

Quais ferramentas de teste e depuração você deve usar?

MCP Inspector

O MCP Inspector é a ferramenta visual oficial para desenvolvedores testarem servidores MCP. Ele permite conectar a um servidor (stdio, SSE ou HTTP streamable), listar ferramentas, invocá‑las manualmente e inspecionar o ciclo de vida das mensagens JSON‑RPC — inestimável durante o desenvolvimento. Inicie‑o via npx @modelcontextprotocol/inspector.

Testes locais vs remotos

Local (stdio) — ciclo de iteração rápido para apps desktop e depuração offline.
HTTP streamable — teste com o Inspector ou conecte ao Claude Code usando o CLI claude mcp add ou o conector MCP no Messages API para testes remotos. Certifique‑se de fornecer quaisquer headers de autenticação exigidos pelo seu servidor.

Conclusão

O MCP é a ponte prática entre LLMs modernos e os sistemas que de fato contêm os dados e executam ações. Para fluxos de trabalho de código, integrar o Claude Code a um servidor MCP dá ao modelo acesso estruturado e auditável a repositórios, CI, rastreadores de issues e ferramentas personalizadas — resultando em automação mais precisa e efeitos colaterais mais seguros. Com SDKs oficiais em TypeScript e Python, HTTP streamable para hospedagem remota e ferramentas como o MCP Inspector, você pode construir um servidor mínimo em minutos e iterar rumo a uma implantação de produção.

Desenvolvedores podem acessar a Claude Sonnet 4.5 API e a Claude Opus 4.1 API etc. via CometAPI; a versão mais recente do modelo é sempre atualizada com o site oficial. Para começar, explore as capacidades do modelo no Playground e consulte o guia da API para instruções detalhadas. Antes de acessar, certifique‑se de ter feito login na CometAPI e obtido a chave de API. A CometAPI oferece um preço muito inferior ao oficial para ajudar na integração.

Pronto para começar? → Cadastre‑se na CometAPI hoje!

Se você quer mais dicas, guias e novidades sobre IA, siga‑nos no VK, X e Discord!

Crie um MCP Server para Claude Code — um guia prático, passo a passo

O que é o Model Context Protocol (MCP)?

Como o MCP é arquitetado?

Servidor, cliente e o protocolo

Padrão de comunicação (o que acontece quando uma ferramenta é usada)

Primitivas de implementação

Por que integrar o Claude Code com servidores MCP?

1. Permitir que o modelo atue em sistemas reais

2. Descarregar grandes volumes de dados e lógica especializada

3. Segurança e governança

4. Reutilização e ecossistema

O que você precisa antes de começar?

Requisitos mínimos

Como instalar e verificar o CLI do Claude Code

1) Resumo rápido — métodos de instalação recomendados

2) Pré-requisitos

3) Comandos de instalação (escolha um)

4) Verificar se o binário foi instalado (checagens básicas)

5) Verificar integridade da instalação e configuração (checagens recomendadas)

a) `claude doctor` — Execute:

b) Executar um smoke test (não interativo)

c) Verificação de autenticação (garantir que o CLI consegue alcançar a Anthropic)

Preparação de ambiente passo a passo

H3 — A. Configuração TypeScript / Node (caminho mais rápido)

Como construir rapidamente um servidor MCP para o Claude Code?

Checklist rápido

Exemplo 1: TypeScript + Express (HTTP streamable)

Exemplo 2: Python + FastAPI (FastMCP + HTTP streamable)

Como o Claude Code realmente chama suas ferramentas?

Quais ferramentas de teste e depuração você deve usar?

MCP Inspector

Testes locais vs remotos

Conclusão

Pronto para reduzir os custos de desenvolvimento de IA em 20%?

Leia Mais

Crie um MCP Server para Claude Code — um guia prático, passo a passo

O que é o Model Context Protocol (MCP)?

Como o MCP é arquitetado?

Servidor, cliente e o protocolo

Padrão de comunicação (o que acontece quando uma ferramenta é usada)

Primitivas de implementação

Por que integrar o Claude Code com servidores MCP?

1. Permitir que o modelo atue em sistemas reais

2. Descarregar grandes volumes de dados e lógica especializada

3. Segurança e governança

4. Reutilização e ecossistema

O que você precisa antes de começar?

Requisitos mínimos

Como instalar e verificar o CLI do Claude Code

1) Resumo rápido — métodos de instalação recomendados

2) Pré-requisitos

3) Comandos de instalação (escolha um)

4) Verificar se o binário foi instalado (checagens básicas)

5) Verificar integridade da instalação e configuração (checagens recomendadas)

a) claude doctor — Execute:

b) Executar um smoke test (não interativo)

c) Verificação de autenticação (garantir que o CLI consegue alcançar a Anthropic)

Preparação de ambiente passo a passo

H3 — A. Configuração TypeScript / Node (caminho mais rápido)

Como construir rapidamente um servidor MCP para o Claude Code?

Checklist rápido

Exemplo 1: TypeScript + Express (HTTP streamable)

Exemplo 2: Python + FastAPI (FastMCP + HTTP streamable)

Como o Claude Code realmente chama suas ferramentas?

Quais ferramentas de teste e depuração você deve usar?

MCP Inspector

Testes locais vs remotos

Conclusão

Pronto para reduzir os custos de desenvolvimento de IA em 20%?

Leia Mais

a) `claude doctor` — Execute: