Skip to main content
Todos os guias
Conteúdo do guia

Conteúdo do guia

Tempo de leitura: 12 min
#automation#mcp#claude-code#typescript#devtools
Intermediário12 min

Servidores MCP e Claude Code: um guia prático de conexão e criação

Como estender as capacidades do Claude Code usando o Model Context Protocol: conectar sistemas de arquivos, GitHub, PostgreSQL, Brave Search e desenvolver seu próprio servidor em TypeScript.

Publicado:
PARA AGENTE DE IAChatGPTClaude

Claude Code já vem, “out of the box”, com a capacidade de ler arquivos locais, executar comandos no terminal e editar o código-fonte do projeto. No entanto, em tarefas reais de desenvolvimento, isso muitas vezes não é suficiente: surge a necessidade de obter informações de um banco de dados PostgreSQL, verificar Pull Requests abertos no GitHub, puxar documentação atualizada da nuvem ou enviar requisições para uma API corporativa interna.

É exatamente para resolver esse problema que foi criado o Model Context Protocol (MCP) — um padrão aberto que transforma o Claude Code de um simples assistente local em um centro completo de orquestração de sistemas e serviços externos.

Neste guia prático, analisaremos a arquitetura do MCP, aprenderemos a conectar servidores oficiais prontos, exploraremos a criação de um servidor próprio em TypeScript e consolidaremos as habilidades com tarefas práticas reais.

1. O que é um MCP Server

Model Context Protocol (MCP) — protocolo de comunicação aberto, desenvolvido pela Anthropic, que padroniza a interação entre modelos de linguagem (LLMs) e ferramentas externas ou fontes de dados.

Em vez de escrever plugins únicos separados para cada serviço, o MCP introduz uma interface cliente-servidor unificada.

text
┌─────────────────────────────────────────────────────────────┐ │ Claude Code (Cliente) │ └──────────────────────────────┬──────────────────────────────┘ │ JSON-RPC 2.0 (stdio / SSE) ▼ ┌─────────────────────────────────────────────────────────────┐ │ Servidor MCP (Adaptador) │ └──────┬───────────────────────┼───────────────────────┬──────┘ │ │ │ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Sistema │ │ API do │ │ Banco de │ │ de Arquivos │ │ GitHub e │ │ Dados │ │ │ │ Issues │ │ PostgreSQL │ └─────────────┘ └─────────────┘ └─────────────┘

Qualquer MCP Server fornece ao modelo três primitivos básicos:

  • Tools (Ferramentas) — funções executáveis com esquema JSON tipado de parâmetros, que o Claude Code pode chamar autonomamente durante a resolução de uma tarefa (por exemplo, create_issue, execute_query).
  • Resources (Recursos) — dados passivos ou esquemas que o assistente pode ler como contexto de entrada (arquivos, esquemas de BD, logs).
  • Prompts (Templates de Prompts) — cenários de contexto prontos que simplificam a execução de tarefas típicas repetitivas.

Comparação das capacidades do Claude Code

Cenário de trabalhoSem MCP (Claude Code básico)Com MCP Servers conectados
Trabalho com arquivosApenas dentro do diretório atual do projetoAcesso a qualquer diretório permitido e notas
Dados do repositórioArquivos locais via git diff / git logLeitura de issues, PRs, code reviews e API do GitHub
Bancos de dadosSomente se um cliente CLI local estiver instaladoLeitura direta de esquemas, tabelas e execução de SQL
Busca de informaçõesgrep / ripgrep local nos arquivosBusca na web em tempo real via Brave/Tavily
Serviços internosInacessíveis sem escrever scripts bash complexosChamada de funções de APIs internas via SDK tipado

2. Arquitetura e princípio de funcionamento do MCP

A arquitetura de interação baseia-se no padrão JSON-RPC 2.0. Na maioria dos cenários locais, a comunicação ocorre através dos fluxos padrão de entrada/saída (stdio), enquanto para servidores remotos usa-se Server-Sent Events (SSE) ou HTTP.

Ciclo de vida passo a passo de uma requisição

  1. Inicialização e Handshake: Ao iniciar uma sessão, o Claude Code lê o arquivo de configuração, inicia os processos dos servidores especificados e solicita a lista de ferramentas suportadas (tools/list).
  2. Publicação de capacidades: Cada MCP Server retorna uma lista de seus métodos junto com esquemas JSON de parâmetros e descrições detalhadas de propósito.
  3. Avaliação da intenção: Quando você define uma tarefa em linguagem natural, o Claude compara sua solicitação com as ferramentas disponíveis.
  4. Chamada da ferramenta: Se a tarefa exigir dados externos, o modelo envia uma requisição estruturada tools/call ao servidor com argumentos válidos.
  5. Execução no lado do servidor: O servidor conecta-se à API externa, banco de dados ou disco e retorna o resultado ao cliente.
  6. Geração da resposta: Após receber os dados brutos, o Claude interpreta-os e fornece a resposta final estruturada.
Nota

A interação é transparente para o desenvolvedor: você não precisa lembrar nomes de funções ou sintaxe de API. O Claude escolhe autonomamente a ferramenta mais adequada com base no contexto da tarefa.

3. Como conectar um MCP Server ao Claude Code

A conexão de servidores é feita através de configuração JSON no bloco mcpServers. O Claude Code suporta dois níveis de configuração:

  1. Configuração do projeto (.claude/settings.json) — aplica-se exclusivamente ao diretório atual e pode ser salva no repositório para toda a equipe.
  2. Configuração global (~/.claude/settings.json) — disponível para todos os projetos do usuário atual no computador.
json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic-ai/mcp-filesystem",
        "./docs"
      ]
    }
  }
}

Estrutura dos parâmetros de configuração

Cada registro de servidor na seção mcpServers consiste em três campos principais:

ParâmetroTipoObrigatórioDescrição e propósitoExemplos de valores
commandstringSimComando executável para iniciar o processo do servidor"npx", "node", "uvx", "docker"
argsstring[]SimArray de argumentos de inicialização (nome do pacote, caminhos, parâmetros)["-y", "@anthropic-ai/mcp-filesystem", "/path"]
envobjectNãoDicionário de variáveis de ambiente para autorização e chaves de API{"GITHUB_TOKEN": "ghp_...", "DEBUG": "1"}
Dica

Se você usar ferramentas em Python, em vez de npx pode usar uvx (do gerenciador de pacotes uv), por exemplo: "command": "uvx", "args": ["mcp-server-git"].

4. Catálogo de MCP Servers prontos

A Anthropic e a comunidade open-source desenvolveram servidores prontos para as ferramentas mais populares. Você não precisa escrever código do zero — basta conectar o pacote npm ou python correspondente.

ServidorPacote oficialAcesso / AutenticaçãoPrincipais funcionalidades
Filesystem@anthropic-ai/mcp-filesystemCaminhos para pastas locais permitidasLeitura, escrita e busca em diretórios externos
GitHub@anthropic-ai/mcp-githubPersonal Access Token (GITHUB_TOKEN)Busca em repositórios, análise de issues, abertura de PRs
PostgreSQL@anthropic-ai/mcp-postgresString de conexão (connectionString)Inspeção de esquemas, leitura de tabelas, execução de consultas SQL
Brave Search@anthropic-ai/mcp-brave-searchChave de API de busca (BRAVE_API_KEY)Acesso a informações atuais da internet sem alucinações

1. Filesystem Server

Fornece ao Claude Code acesso a diretórios fora do repositório atual (por exemplo, pasta global de documentação ou notas do Obsidian).

json
{ "mcpServers": { "docs": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-filesystem", "/Users/username/Developer/knowledge-base" ] } } }

2. GitHub Server

Permite que o assistente trabalhe diretamente com repositórios da organização: ler issues, deixar comentários em PRs e verificar status de pipelines.

json
{ "mcpServers": { "github": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-github" ], "env": { "GITHUB_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } } }

3. PostgreSQL Server

Possibilita que o Claude execute consultas analíticas ou diagnósticas diretamente no seu banco de dados local ou remoto.

json
{ "mcpServers": { "postgres": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-postgres", "postgresql://postgres:password@localhost:5432/my_app_db" ] } } }

4. Brave Search Server

Integra o motor de busca web, permitindo que o assistente encontre documentação fresca, soluções para bugs recentes ou mudanças em bibliotecas.

json
{ "mcpServers": { "brave-search": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-brave-search" ], "env": { "BRAVE_API_KEY": "BSAu_your_brave_search_api_key" } } } }

Após adicionar o servidor à configuração, você não precisa inserir comandos especiais ou prefixos. O Claude Code analisa sua solicitação em linguagem natural e decide autonomamente quando chamar uma ferramenta.

Exemplo de cenário: trabalho com GitHub

Solicitação do usuário:

"Verifique quais issues abertas estão atribuídas a mim no repositório acme/platform e liste as mais prioritárias."

Processo interno do Claude Code:

  1. O modelo reconhece que arquivos locais são insuficientes para responder.
  2. Ele forma uma chamada mcp__github__search_issues com filtros repo:acme/platform state:open assignee:@me.
  3. Recebe uma resposta JSON estruturada do servidor GitHub.
  4. Formata a resposta em um layout conveniente.
markdown
Foram encontradas 3 tarefas abertas atribuídas a você: 1. **#42 — Fix login redirect loop** (Prioridade: Alta, Criada há: 2 dias) 2. **#38 — Add rate limiting to auth API** (Prioridade: Média, Criada há: 5 dias) 3. **#35 — Update user profile settings page** (Prioridade: Baixa, Criada há: 1 semana) Deseja analisar o código em detalhes para corrigir o erro na #42?

6. Criando seu próprio MCP Server em TypeScript

Se as soluções prontas forem insuficientes e você precisar de uma ferramenta específica para lógica de negócio ou microsserviços internos, um MCP Server pode ser escrito em poucos minutos usando o SDK oficial @modelcontextprotocol/sdk.

Passo 1. Inicialização e instalação de dependências

Crie um diretório separado e instale as bibliotecas:

bash
mkdir my-mcp-server && cd my-mcp-server npm init -y npm install @modelcontextprotocol/sdk zod npm install -D typescript @types/node tsx

Passo 2. Implementação do servidor (server.ts)

Crie o arquivo server.ts com a definição do servidor e uma ferramenta customizada:

typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { z } from "zod"; // 1. Ініціалізуємо сервер з метаданими const server = new McpServer({ name: "internal-crm-server", version: "1.0.0", }); // 2. Реєструємо інструмент пошуку користувача server.tool( "lookup-user", "Отримати профіль клієнта за його адресою електронної пошти", { email: z.string().email().describe("Email адреса зареєстрованого користувача"), }, async ({ email }) => { // Тут може бути реальний запит до CRM, Redis чи внутрішнього API const mockUser = { id: "usr_99812", email, name: "Олександр Коваленко", plan: "Enterprise", status: "active", createdAt: "2024-03-15T10:00:00Z", }; return { content: [ { type: "text", text: JSON.stringify(mockUser, null, 2), }, ], }; } ); // 3. Запускаємо сервер через стандартний stdio транспорт async function run() { const transport = new StdioServerTransport(); await server.connect(transport); console.error("Internal CRM MCP server started on stdio"); } run().catch((error) => { console.error("Server startup error:", error); process.exit(1); });

Passo 3. Conectando o servidor ao Claude Code

Adicione o servidor criado ao .claude/settings.json do seu projeto:

json
{ "mcpServers": { "crm": { "command": "npx", "args": [ "tsx", "/Users/username/Developer/my-mcp-server/server.ts" ] } } }
Dica

O uso da utilidade tsx permite executar arquivos TypeScript diretamente, sem necessidade de build prévio via tsc.

7. Segurança e isolamento ao trabalhar com MCP

O MCP aumenta significativamente a autonomia do Claude Code, mas dá ao código a capacidade de interagir com seu sistema operacional e serviços externos. Para manter a segurança do ambiente de trabalho, siga estas regras:

1. O servidor executa com suas permissões de sistema

O MCP Server roda no contexto do usuário atual do sistema operacional. Se o servidor tiver erros ou contiver código malicioso, ele poderá ler arquivos aos quais seu usuário tem acesso.

2. Proteção de segredos e chaves de API

Nunca armazene chaves de produção no repositório. Use a configuração global ~/.claude/settings.json para tokens sensíveis ou passe variáveis de ambiente via arquivos .env incluídos no .gitignore.

3. Verificação de pacotes de terceiros antes da conexão

Sempre audite o repositório ou pacote npm de um MCP Server de terceiros antes de adicioná-lo à configuração:

  • Certifique-se de que o código-fonte é aberto.
  • Verifique o número de downloads e a atividade do repositório.
  • Observe as requisições de rede que o servidor faz durante a inicialização.

4. Separação dos níveis de configuração

text
┌─────────────────────────────────────────────────────────────┐ │ ~/.claude/settings.json │ │ Ferramentas globais: GitHub, Busca na Web, Navegador │ └──────────────────────────────┬──────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ .claude/settings.json │ │ Ferramentas locais: Dev PostgreSQL, scripts específicos │ └─────────────────────────────────────────────────────────────┘
Aviso

Evite conectar servidores com permissão de escrita em bancos de dados de produção (Production DB) em modo de desenvolvimento. Para testes, use réplicas Read-Only separadas ou containers Docker locais.

8. Workshop prático: configuração passo a passo

Execute duas tarefas práticas para consolidar o material e verificar a correção da conexão dos servidores.

Tarefa 1. Conectando o GitHub MCP Server

  1. Crie um novo Personal Access Token (classic ou fine-grained) no GitHub na seção Settings → Developer settings com permissões repo e read:org.
  2. Abra ou crie o arquivo de configuração ~/.claude/settings.json:
json
{ "mcpServers": { "github": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-github" ], "env": { "GITHUB_TOKEN": "ghp_ваш_токен_тут" } } } }
  1. Inicie uma nova sessão do Claude Code e execute o prompt de verificação:
bash
claude

Prompt para teste:
"Mostre meus 5 últimos repositórios atualizados no GitHub e seu status."

  • O Claude Code chamou a ferramenta GitHub com sucesso, sem erros de autenticação.
  • Foi obtida uma lista atualizada de repositórios.

Tarefa 2. Conectando o Filesystem Server para notas externas

Dê ao Claude acesso a uma pasta externa com documentação ou notas de arquitetura:

  1. Adicione o servidor filesystem ao .claude/settings.json:
json
{ "mcpServers": { "external-docs": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-filesystem", "/шлях/до/вашої/папки/з_документами" ] } } }
  1. Teste o funcionamento com uma consulta ao Claude:

Prompt para teste:
"Encontre na pasta external-docs todos os arquivos markdown que descrevem a arquitetura da API e faça um resumo breve deles."

  • O Claude leu arquivos fora do diretório de trabalho do projeto.
  • Resumiu as informações encontradas sem perda de contexto.

9. Autoavaliação rápida de conhecimentos

Verifique quão bem você assimilou os princípios fundamentais da arquitetura do Model Context Protocol.

Questão 1. Qual é o propósito básico de um MCP Server?

  • A. Máquina virtual na nuvem para hospedar modelos Claude
  • B. Programa adaptador que fornece ao modelo de linguagem acesso padronizado a ferramentas e dados externos
  • C. Biblioteca para compressão automática de embeddings vetoriais
  • D. Web server para publicar código compilado do projeto
Dica

Resposta correta: B.
Um MCP Server é um processo local ou remoto que atua como ponte entre o modelo e serviços de terceiros, fornecendo ao modelo Tools, Resources e Prompts padronizados.

Questão 2. Em qual arquivo fica a configuração de servidores destinada apenas a um repositório específico?

  • A. ~/.claude/settings.json
  • B. package.json
  • C. .claude/settings.json na raiz do projeto
  • D. CLAUDE.md
Dica

Resposta correta: C.
Para configuração no nível de um projeto individual, usa-se .claude/settings.json. O arquivo no diretório home ~/.claude/settings.json é responsável pelas ferramentas globais do desenvolvedor.

Questão 3. Como o Claude Code sabe qual ferramenta usar para responder a uma pergunta?

  • A. O usuário deve explicitamente indicar a flag --tool=name antes de cada requisição
  • B. É necessário chamar previamente o comando /mcp select
  • C. O modelo analisa a semântica da requisição e as descrições dos esquemas JSON das ferramentas, escolhendo a relevante autonomamente
  • D. Todas as ferramentas são chamadas simultaneamente e resultados extras são descartados
Dica

Resposta correta: C.
Graças às descrições e esquemas de parâmetros padronizados, o Claude avalia a intenção do usuário e chama autonomamente a ferramenta necessária, passando argumentos válidos.

10. Conclusões e checklist de arquitetura

O Model Context Protocol torna o Claude Code um ambiente agentic flexível. Em vez de copiar manualmente conteúdo de arquivos ou esquemas de banco de dados para o diálogo, você configura canais de comunicação permanentes uma única vez.

Checklist de prontidão do seu ambiente

  • Níveis de configuração: Serviços globais (GitHub, Web Search) movidos para ~/.claude/settings.json, enquanto específicos do projeto (BD, documentação) ficam em .claude/settings.json.
  • Segurança: Tokens e senhas não são commitados em repositórios públicos; bancos de dados conectados com privilégios mínimos necessários (Read-Only para análise).
  • Teste de ferramentas: O funcionamento dos servidores foi verificado com consultas direcionadas após o início da sessão.
  • Extensibilidade: Para tarefas internas específicas, foi criado um template de servidor próprio em TypeScript via @modelcontextprotocol/sdk.
Este guia é totalmente gratuito. Se ele te poupou uma noite, você pode apoiar o crescimento do projeto.
Apoiar o autor