Criar um servidor MCP para o Claude Code — um guia prático e atualizado

CometAPI
AnnaNov 22, 2025
Criar um servidor MCP para o Claude Code — um guia prático e atualizado

O Protocolo de Contexto de Modelo (MCP) é um padrão aberto que permite que modelos como o do Anthropic Claude e ferramentas de desenvolvedor como Código Claude Recorrer a ferramentas externas, fontes de dados e solicitações de forma segura e padronizada.

Este guia irá orientá-lo na criação de seu próprio servidor MCP do zero, permitindo que o Claude Code acesse recursos personalizados e, assim, expanda consideravelmente sua funcionalidade, muito além dos recursos integrados.

O que é o Protocolo de Contexto do Modelo (MCP)?

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

  • Notícias — dados semelhantes a arquivos ou documentos que um cliente pode ler (por exemplo, uma linha de banco de dados, um arquivo de texto, uma carga útil JSON).
  • Ferramentas — funções chamáveis ​​que o modelo pode solicitar ao host para executar (com a aprovação do usuário).
  • Solicita — modelos de prompts ou fluxos de trabalho reutilizáveis ​​que o modelo/cliente pode invocar.

O MCP suporta múltiplos transportes (stdio, HTTP, SSE) e fornece esquemas, SDKs e servidores de exemplo para que você não precise criar o formato de transmissão do zero. O protocolo é mantido publicamente (especificação + SDKs) e conta com tutoriais e uma galeria de servidores de exemplo para acelerar sua adoção.

Como é arquitetada a MCP?

A arquitetura do MCP é intencionalmente simples e modular: as peças principais são MCP Servidores, MCP clientes e Transporte que transportam mensagens em formato JSON-RPC entre si. Abaixo estão os principais componentes com os quais você interagirá ao construir 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. As ferramentas podem executar efeitos colaterais ou buscar dados; os recursos exibem conteúdo somente leitura; os prompts são modelos de prompts reutilizáveis ​​que o cliente pode solicitar ao modelo para extrair amostras.
  • Cliente MCP (host) — Normalmente faz 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 encaminha chamadas iniciadas pelo modelo para os servidores.
  • Protocolo — As mensagens são codificadas em JSON-RPC; a especificação define eventos do ciclo de vida, descoberta de ferramentas, invocação, conclusões/amostragem e como os resultados estruturados são transportados de volta para o cliente e o modelo.

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

  1. O cliente envia uma mensagem do usuário para o modelo.
  2. O modelo analisa o contexto e decide acionar uma ferramenta exposta pelo MCP (ou várias ferramentas).
  3. O cliente encaminha a chamada da ferramenta para o servidor MCP através do transporte escolhido.
  4. O servidor executa a ferramenta e retorna os resultados.
  5. O modelo recebe os dados da ferramenta e compõe a resposta final para o usuário.

Primitivas de implementação

  • JSON-RPC As mensagens seguem o esquema MCP.
  • Definições de ferramentas são publicadas nas respostas de descoberta do servidor para que os clientes possam apresentá-las na interface do usuário.
  • Notícias são referenciados por @source:path sintaxe por clientes (ex: @postgres:...), permitindo que os modelos se refiram a conteúdo externo sem inserir grandes quantidades de dados diretamente no prompt.

Por que integrar o Claude Code com os servidores MCP?

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

A integração do Claude Code com os servidores MCP desbloqueia funcionalidades práticas e relevantes para a produção de um agente de codificação:

1. Deixe o modelo agir em sistemas reais

O Claude Code pode solicitar a um servidor MCP que consulte sistemas de rastreamento de problemas, execute consultas em bancos de dados, leia documentação extensa ou crie Pull Requests (PRs) no GitHub — possibilitando a automação completa diretamente da sessão de programação. Isso é explicitamente suportado pela documentação do Claude Code (exemplos: consultas ao Postgres, Sentry ou criação de 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 por meio do MCP. O modelo chama a ferramenta, recebe uma resposta estruturada e a utiliza para raciocínio — isso reduz o uso de tokens e permite que os servidores lidem com tarefas complexas (consultas a bancos de dados, leitura de arquivos longos, autenticação).

3. Segurança e governança

O MCP centraliza o controle de acesso e a auditoria na camada do servidor, permitindo que as organizações criem listas de permissões para servidores aprovados, controlem quais ferramentas estão disponíveis e limitem as saídas. O Claude Code também oferece suporte à configuração corporativa do MCP e ao consentimento por escopo.

4. Reutilização e ecossistema

Os servidores MCP são reutilizáveis ​​em diferentes clientes e equipes. Crie-os uma vez e vários clientes Claude/LLM poderão usar os mesmos serviços (ou trocar as implementações).

O que você precisa antes de começar?

Requerimentos mínimos

  • Uma máquina de desenvolvimento com Python 3.10 + (Usaremos Python no exemplo). Alternativamente, Node.js e outras linguagens são suportadas pelos SDKs do MCP.
  • uv (A ferramenta Astral) ou um executor equivalente para executar servidores stdio do MCP (o tutorial do MCP usa uvEtapas de instalação mostradas abaixo.
  • É necessário ter o 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 servidores HTTP, SSE e stdio local.
  • Nota de segurançaAdicione servidores MCP confiáveis ​​ao Claude Code somente em ambientes de equipe ou corporativos — o MCP concede acesso a dados confidenciais aos servidores, e existem riscos de injeção imediata caso um servidor retorne conteúdo malicioso.

Como instalar e verificar a CLI do Claude Code

Isto é Guia de Instalação e Utilização do Claude Code.

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

Use o instalador nativo (Recomendado) ou Homebrew no macOS/Linux. O NPM está disponível caso precise de uma instalação baseada em Node.js. O Windows possui instaladores em 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+ apenas necessário para o método de instalação via NPM.

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

Nativo (recomendado — sem dependência do 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 de instalação nativa).

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

# requires Node.js 18+

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

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

4) Verificar se o binário foi instalado (verificações básicas)

Execute estes comandos 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 or ~/.nvm/.../bin/claude) e claude --version Imprime uma string semelhante à versão semântica (semver). A documentação e o arquivo README mostram isso. claude como o principal ponto de entrada da CLI.

5) Verificar a integridade e a configuração da instalação (verificações recomendadas)

a) claude doctor,Correr:

claude doctor

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

b) Execute um teste de fumaça (não interativo)

A partir do diretório do seu projeto:

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

Isso usa impressão modo (-p) para enviar um único prompt e depois sair; bom para CI ou verificações funcionais rápidas.

c) Verificação de autenticação (certifique-se de que a CLI consiga se conectar à Anthropic)

O Claude Code suporta diversos fluxos de autenticação (OAuth via console, chave de API, integrações com provedores). Verificações comuns:

  1. 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 CometAPIA chave de API do Claude para usar o código dele, ao usar a API do Claude através da CometAPI, lhe dará um desconto de 20%.

  1. Se você usou o OAuth por meio do console - correr:
claude auth status
claude auth whoami

Você deverá ver informações sobre sua conta/plano ou uma confirmação de que você foi autenticado.

Preparação do ambiente passo a passo

A seguir, apresentamos etapas concretas para preparar duas plataformas de desenvolvimento comuns (TypeScript e Python), seguidas de verificações rápidas para garantir que tudo funcione corretamente.

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

  1. 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
  1. Crie server.ts(Fornecemos um exemplo completo na seção “Como construir rapidamente…”.)
  2. Executar:
npx -y tsx server.ts
  1. Faça o teste localmente com o Inspetor MCP ou adicione ao código Claude:
npx @modelcontextprotocol/inspector
# or (for Claude Code)

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

(Os comandos Inspector e Claude permitem validar a descoberta e invocar ferramentas.)

Como criar rapidamente um servidor MCP para o Claude Code?

lista de verificação rápida

  1. Inicie seu servidor (Streamable HTTP recomendado): node server.ts or uvicorn server:app.

  2. A partir da sua máquina de desenvolvimento, execute um dos seguintes comandos:

  • Uso Inspetor MCP para validar (npx @modelcontextprotocol/inspector) e confirme tools/list e resources/list; Ou
  • Adicione o servidor ao código Claude: claude mcp add --transport http <name> http://<host>:<port>/mcp (ou siga os fluxos da interface web se o seu cliente suportar MCP remoto).

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

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

Observação: o código abaixo segue os exemplos públicos do SDK e é intencionalmente minimalista para maior clareza. Para produção, adicione autenticação, registro de logs, limitação de taxa de requisições e validação de entrada além das configurações padrão 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

Em seguida, conecte em código Claude (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 foi adaptado do Guia de Início Rápido do SDK oficial do TypeScript e demonstra como registrar ferramentas e recursos e, em seguida, expô-los por meio do Streamable HTTP.

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

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

Entre em contato com o inspetor:

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

Os exemplos do SDK Python e os utilitários FastMCP facilitam o registro. @mcp.tool() e @mcp.resource() funções decoradas que o LLM pode descobrir e invocar.

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 banco de dados, executa testes ou chama uma API externa) e retorna o resultado. conteúdo estruturado e conteúdo apresentávelO cliente (Claude Code) pode então incluir a saída estruturada no contexto do modelo para que este possa continuar raciocinando com esses dados confiáveis ​​— e não apenas com a saída textual do servidor. O SDK do TypeScript oferece suporte ao registro. inputSchema e outputSchema (zod) para que os argumentos e as saídas sejam validados e tipados pela máquina.

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

Inspetor MCP

O Inspetor MCP é a ferramenta visual oficial para desenvolvedores que testam servidores MCP. Ela permite conectar-se a um servidor (stdio, SSE ou streamable-HTTP), listar ferramentas, invocá-las manualmente e inspecionar o ciclo de vida das mensagens JSON-RPC — algo inestimável durante o desenvolvimento. Inicie-a através de npx @modelcontextprotocol/inspector.

Testes locais versus remotos

  • Local (stdio) — Ciclo de iteração rápido para aplicativos de desktop e depuração offline.
  • HTTP transmitível — teste com o Inspector ou conecte-se ao Claude Code usando o claude mcp add Utilize a CLI ou o conector MCP na API de Mensagens para testes remotos. Certifique-se de fornecer todos os cabeçalhos de autenticação necessários para o seu servidor.

Conclusão

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

Os desenvolvedores podem acessar Claude Soneto 4.5 API e  API Claude Opus 4.1 etc. através da CometAPI, a versão mais recente do modelo está sempre atualizado com o site oficial. Para começar, explore as capacidades do modelo no Playground e consulte o Guia de API para obter instruções detalhadas. Antes de acessar, certifique-se de ter feito login no CometAPI e obtido a chave da API. CometAPI oferecem um preço muito mais baixo que o preço oficial para ajudar você a se integrar.

Pronto para ir?→ Inscreva-se no CometAPI hoje mesmo !

Se você quiser saber mais dicas, guias e novidades sobre IA, siga-nos em VK, X e  Discord!

Leia Mais

500+ Modelos em Uma API

Até 20% de Desconto