Um passo a passo prático para configurar servidores MCP (Model Context Protocol) com o Claude Code, cobrindo instalação, configuração, modos de transporte, definições de ferramentas e como conectar modelos de IA a APIs e serviços do mundo real. Exemplos funcionais que você pode copiar e executar hoje.
Se você já passou algum tempo no Claude Code e notou a seção MCP nas configurações, provavelmente se perguntou o que ela realmente faz, quão difícil é configurar e se vale o esforço. Resposta curta: sim, vale muito a pena. O MCP (Model Context Protocol) é o mecanismo que permite ao Claude ir além da sua janela de contexto, chamar funções reais, consultar bancos de dados reais e interagir com APIs reais, tudo dentro de uma conversa.
Este artigo percorre tudo, desde entender o que é o MCP até executar seu primeiro servidor personalizado com o Claude Code, incluindo exemplos reais de configuração que você pode copiar imediatamente.
O MCP é um protocolo aberto desenvolvido pela Anthropic que padroniza a forma como modelos de IA se comunicam com ferramentas e fontes de dados externas. Pense nele como um aperto de mão estruturado: seu servidor declara quais ferramentas oferece, e o Claude as chama com os argumentos corretos e processa os resultados.
Antes do MCP, cada integração era feita sob medida. Você escrevia prompts de sistema especiais, improvisava esquemas de chamada de função e torcia para o modelo seguir a especificação. O MCP formaliza tudo isso em uma única camada previsível.
O protocolo define três primitivas principais:
| Primitiva | Descrição |
|---|---|
| Ferramentas | Funções que o modelo pode chamar (por exemplo, buscar, obter dados, gravar arquivo) |
| Recursos | Dados que o modelo pode ler (por exemplo, arquivos, registros de banco de dados) |
| Prompts | Modelos de prompt reutilizáveis expostos pelo servidor |
Essas três primitivas cobrem praticamente todos os cenários de integração que você vai encontrar. Ferramentas cuidam de ações, recursos cuidam do acesso a dados e prompts cuidam de padrões de interação reutilizáveis. O protocolo é agnóstico quanto ao transporte, o que significa que o mesmo código de servidor funciona via stdio para desenvolvimento local e via HTTP para implantações em produção.
Os servidores MCP rodam em um de dois modos de transporte. Conhecer a diferença economiza horas de depuração.
O cliente (Claude Code) inicia seu servidor como um subprocesso e se comunica por stdin/stdout. Essa é a configuração mais simples para ferramentas locais e fluxos de trabalho pessoais. Sem portas, sem rede e sem necessidade de autenticação.
{
"mcpServers": {
"my-tool": {
"command": "node",
"args": ["/absolute/path/to/server/dist/index.js"]
}
}
}
Seu servidor roda como um processo HTTP independente. O Claude Code se conecta a ele pela rede. Essa é a escolha certa para servidores compartilhados por equipes, implantações em nuvem ou qualquer servidor que precise continuar rodando entre sessões.
{
"mcpServers": {
"my-tool": {
"url": "http://localhost:3000/sse"
}
}
}
💡 Comece pelo stdio. Ele não exige nenhuma configuração de rede e é bem mais fácil de depurar. Mude para o transporte HTTP só quando precisar de acesso compartilhado ou de estado persistente no servidor.
Todo servidor MCP começa do mesmo jeito: instale o SDK oficial e configure o TypeScript para ESM.
mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript tsx @types/node
Inicialize o TypeScript:
npx tsc --init
Atualize tsconfig.json para usar módulos ESM:
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"outDir": "./dist",
"strict": true
}
}
Adicione os scripts em package.json:
{
"type": "module",
"scripts": {
"build": "tsc",
"dev": "tsx src/index.ts"
}
}
O campo "type": "module" não é opcional. Sem ele, o Node trata seus arquivos como CommonJS e todas as importações ESM falham na inicialização.
Crie src/index.ts e defina sua primeira ferramenta com um esquema Zod tipado:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
const server = new McpServer({
name: "my-first-server",
version: "1.0.0",
});
server.tool(
"get_weather",
"Get current weather for a city",
{
city: z.string().describe("City name"),
units: z.enum(["celsius", "fahrenheit"]).optional().default("celsius"),
},
async ({ city, units }) => {
const temp = units === "celsius" ? "22°C" : "72°F";
return {
content: [
{
type: "text",
text: `Weather in ${city}: ${temp}, partly cloudy`,
},
],
};
}
);
const transport = new StdioServerTransport();
await server.connect(transport);
Compile e verifique se tudo está certo, sem erros:
npx tsc
node dist/index.js
Pronto, esse é um servidor MCP funcional. Ele expõe uma ferramenta com um esquema tipado que o Claude valida antes de chamá-la.
Abra as configurações do Claude Code e vá até a seção MCP. Adicione a entrada do seu servidor usando o caminho absoluto para a saída compilada:
{
"mcpServers": {
"my-first-server": {
"command": "node",
"args": ["/absolute/path/to/my-mcp-server/dist/index.js"]
}
}
}
Reinicie o Claude Code. Abra uma nova conversa e pergunte: "Qual é a previsão do tempo em Paris?"
Se tudo estiver conectado corretamente, o Claude vai chamar get_weather com city: "Paris" e mostrar o resultado na resposta. Você verá a chamada da ferramenta aparecer na conversa.
💡 Use sempre caminhos absolutos na configuração do MCP. Caminhos relativos falham silenciosamente, dependendo de como o Claude Code resolve seu diretório de trabalho na inicialização.
Servidores reais precisam de uma separação clara entre definições de esquema, handlers e lógica de serviço. Esta é a estrutura de arquivos que escala sem se tornar difícil de manter:
src/
index.ts # Entry point and server setup
tools/
definitions.ts # Zod schemas for each tool input
handlers.ts # Business logic per tool
services/
api.ts # External API calls
db.ts # Database access layer
definitions.ts guarda todos os esquemas Zod:
import { z } from "zod";
export const searchInputSchema = {
query: z.string().min(1).describe("Search query text"),
limit: z.number().int().min(1).max(50).optional().default(10),
};
handlers.ts guarda a implementação:
export async function handleSearch(
args: { query: string; limit?: number }
) {
const results = await searchApi(args.query, args.limit ?? 10);
return {
content: [{ type: "text" as const, text: JSON.stringify(results, null, 2) }],
};
}
index.ts conecta tudo em uma única chamada server.tool() por ferramenta. Essa separação permite testar os handlers sem um servidor em execução e trocar esquemas sem mexer na lógica de negócio.
São os erros que fazem tropeçar quase todo mundo que constrói o primeiro servidor MCP.
1. Falta de extensões de arquivo .js nas importações
A resolução de módulos do Node16 exige extensões .js explícitas, mesmo dentro dos arquivos-fonte TypeScript. Omiti-las causa falhas de importação em tempo de execução que são confusas, porque o compilador do TypeScript não as detecta.
// This fails at runtime with ERR_MODULE_NOT_FOUND
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
// This works correctly
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2. Usar console.log() em servidores stdio
No modo stdio, a saída padrão é o canal do protocolo. Qualquer chamada a console.log() escreve texto arbitrário nesse canal e corrompe o fluxo do MCP. Use console.error() para toda saída de depuração.
3. Falta de await na conexão do servidor
// Wrong: process may exit before connection completes
server.connect(transport);
// Correct: wait for connection handshake
await server.connect(transport);
4. Caminhos relativos na configuração do Claude Code
O Claude Code é iniciado a partir de diretórios de trabalho variáveis. Sempre use caminhos absolutos fixos ou resolva-os na inicialização com import.meta.url.
5. Descrições de ferramentas amplas demais
O Claude usa a descrição da ferramenta para decidir quando chamá-la. Descrições vagas como "faz coisas" fazem a ferramenta ser chamada com excesso de frequência ou nunca ser chamada. Seja específico: "Busca um pull request do GitHub pelo dono, pelo repositório e pelo número do PR."
Quando seu servidor precisa ser compartilhado por uma equipe ou rodar em um ambiente de nuvem, o HTTP com SSE é o transporte certo:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
import express from "express";
const app = express();
const server = new McpServer({ name: "team-server", version: "1.0.0" });
const transports: Record<string, SSEServerTransport> = {};
app.get("/sse", async (req, res) => {
const transport = new SSEServerTransport("/messages", res);
transports[transport.sessionId] = transport;
await server.connect(transport);
});
app.post("/messages", express.json(), async (req, res) => {
const sessionId = req.query.sessionId as string;
const transport = transports[sessionId];
if (transport) await transport.handlePostMessage(req, res);
});
app.listen(3000, () => console.error("MCP server listening on :3000"));
Cada cliente do Claude Code guarda seu próprio transporte de sessão, para que vários usuários possam se conectar ao mesmo tempo sem interferir uns nos outros.
Os recursos permitem que o Claude leia dados estruturados sem chamadas explícitas de ferramentas. Eles são a primitiva certa para configurações, documentação ou estado em cache que o Claude deve conhecer sem que você precise definir uma ferramenta de busca dedicada.
server.resource(
"config://app",
"Application configuration and feature flags",
async (uri) => ({
contents: [
{
uri: uri.toString(),
mimeType: "application/json",
text: JSON.stringify({
version: "2.1.0",
features: { darkMode: true, betaSearch: false },
limits: { maxResults: 50, timeoutMs: 5000 },
}),
},
],
})
);
O Claude pode referenciar config://app em seu contexto e ler esses dados de forma proativa, reduzindo o número de chamadas de ferramentas necessárias em uma conversa.
O MCP Inspector é essencial durante o desenvolvimento. Ele oferece uma interface visual para chamar suas ferramentas diretamente, sem passar pelo Claude Code:
npx @modelcontextprotocol/inspector node dist/index.js
Abra http://localhost:5173. Você verá todas as ferramentas registradas, seus esquemas e um formulário para chamar cada uma diretamente com entradas arbitrárias. O JSON bruto da requisição e da resposta fica visível, o que torna trivial identificar incompatibilidades de tipo ou campos ausentes.
Para servidores HTTP:
npx @modelcontextprotocol/inspector http://localhost:3000/sse
💡 Fique atento a incompatibilidades de esquema. Se o Claude Code diz que uma ferramenta está registrada, mas nunca a chama, a causa mais comum é um esquema Zod que rejeita os argumentos fornecidos pelo modelo. O Inspector permite reproduzir isso sem envolver o Claude.
Um dos padrões de maior valor é criar servidores MCP que orquestram chamadas a vários modelos de IA. Seu servidor vira a camada intermediária, e o Claude Code vira o coordenador.
Você pode expor uma ferramenta que direciona pedidos para o Deepseek R1 para raciocínio profundo, para o GPT 5 para escrita criativa ou para o Llama 4 Scout Instruct para processamento rápido de documentos. O Claude decide qual ferramenta chamar com base na tarefa em questão.
server.tool(
"route_to_model",
"Route a task to the most suitable language model for the job",
{
task: z.enum(["reasoning", "creative", "summarize"]),
input: z.string().describe("The text input to process"),
},
async ({ task, input }) => {
const modelMap = {
reasoning: "deepseek-r1",
creative: "gpt-5",
summarize: "llama-4-scout",
};
const result = await callModelApi(modelMap[task], input);
return { content: [{ type: "text", text: result }] };
}
);
Com o Claude Opus 4.7 como orquestrador e seu servidor MCP como camada de despacho, você obtém um sistema multimodelo que roteia de forma inteligente, sem uma infraestrutura complexa.
A Picasso IA oferece acesso via API a modelos como Claude 4.5 Sonnet, Gemini 2.5 Flash e Claude 4 Sonnet, o que facilita criar ferramentas MCP multimodelo sem gerenciar chaves de API separadas e bibliotecas cliente para cada provedor.
As ferramentas MCP nunca devem lançar exceções não tratadas. Retorne conteúdo de erro estruturado para que o Claude possa informar falhas com clareza e decidir o que fazer em seguida:
server.tool(
"safe_fetch",
"Fetch content from an external URL",
{ url: z.string().url() },
async ({ url }) => {
try {
const response = await fetch(url);
if (!response.ok) {
return {
content: [
{
type: "text",
text: `Request failed: HTTP ${response.status} from ${url}`,
},
],
isError: true,
};
}
return { content: [{ type: "text", text: await response.text() }] };
} catch (err) {
return {
content: [{ type: "text", text: `Network error: ${String(err)}` }],
isError: true,
};
}
}
);
O flag isError: true sinaliza para o Claude que a chamada falhou. O Claude então decide se tenta novamente, usa uma alternativa ou mostra o erro ao usuário.
Quando o básico estiver funcionando, o território prático se abre. Estes são os padrões que as equipes estão colocando em produção com o MCP hoje:
| Caso de uso | O que faz |
|---|---|
| Ferramenta de banco de dados | O Claude escreve e executa consultas SQL restritas, com segurança |
| Navegador de sistema de arquivos | Acesso de leitura e escrita a diretórios específicos do projeto |
| Wrapper de API | Expõe Jira, GitHub ou Slack como ferramentas chamáveis |
| Pipeline de imagens | Conecta o Claude a APIs de geração de imagens a partir de texto |
| Sandbox de código | Executa e testa trechos de código em um contêiner isolado |
| Recuperador RAG | Pesquisa em um banco de dados vetorial e retorna os trechos relevantes |
O caso de uso do pipeline de imagens é especialmente poderoso. Você cria um servidor MCP que recebe um prompt de texto do Claude, chama um modelo de texto para imagem, envia o resultado para o armazenamento em nuvem e devolve a URL, tudo em uma única chamada de ferramenta que o Claude encadeia naturalmente na conversa, sem código de orquestração adicional.
Para equipes que montam fluxos de trabalho com geração de imagens, os mais de 90 modelos disponíveis em plataformas como a Picasso IA podem ser conectados como ferramentas MCP, dando ao Claude acesso direto a modelos de difusão, upscalers e pipelines de edição dentro de uma conversa.
Se você quer ver o que é possível fazer com modelos de IA antes de criar suas próprias integrações MCP, a Picasso IA coloca mais de 90 modelos de texto para imagem e dezenas de modelos de linguagem (LLM) direto no seu navegador. Execute o Claude Opus 4.6, o GPT 5, o Deepseek R1 ou o Llama 4 Maverick Instruct sem nenhuma configuração.
É a forma mais rápida de testar a saída de um modelo antes de se comprometer com uma integração de API. Escolha um modelo, envie um prompt e veja exatamente com o que você vai trabalhar no seu conjunto de ferramentas MCP. Seja para gerar imagens para um projeto, testar estruturas de prompt ou explorar como diferentes modelos lidam com a mesma entrada, a plataforma oferece acesso rápido sem a sobrecarga de infraestrutura.
Crie uma conta, escolha um modelo e comece a gerar imagens ou textos hoje mesmo, sem arquivos de configuração.
Escolha seu idioma
