# 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. 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 trabalho | Sem MCP (Claude Code básico) | Com MCP Servers conectados | | :--- | :--- | :--- | | **Trabalho com arquivos** | Apenas dentro do diretório atual do projeto | Acesso a qualquer diretório permitido e notas | | **Dados do repositório** | Arquivos locais via `git diff` / `git log` | Leitura de issues, PRs, code reviews e API do GitHub | | **Bancos de dados** | Somente se um cliente CLI local estiver instalado | Leitura direta de esquemas, tabelas e execução de SQL | | **Busca de informações** | grep / ripgrep local nos arquivos | Busca na web em tempo real via Brave/Tavily | | **Serviços internos** | Inacessíveis sem escrever scripts bash complexos | Chamada 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. > [!NOTE] > 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. :::tabs === Projeto (.claude/settings.json) ```json { "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-filesystem", "./docs" ] } } } ``` === Global (~/.claude/settings.json) ```json { "mcpServers": { "github": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-github" ], "env": { "GITHUB_TOKEN": "ghp_your_token_here" } } } } ``` ::: ### Estrutura dos parâmetros de configuração Cada registro de servidor na seção `mcpServers` consiste em três campos principais: | Parâmetro | Tipo | Obrigatório | Descrição e propósito | Exemplos de valores | | :--- | :--- | :--- | :--- | :--- | | `command` | `string` | Sim | Comando executável para iniciar o processo do servidor | `"npx"`, `"node"`, `"uvx"`, `"docker"` | | `args` | `string[]` | Sim | Array de argumentos de inicialização (nome do pacote, caminhos, parâmetros) | `["-y", "@anthropic-ai/mcp-filesystem", "/path"]` | | `env` | `object` | Não | Dicionário de variáveis de ambiente para autorização e chaves de API | `{"GITHUB_TOKEN": "ghp_...", "DEBUG": "1"}` | > [!TIP] > 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. | Servidor | Pacote oficial | Acesso / Autenticação | Principais funcionalidades | | :--- | :--- | :--- | :--- | | **Filesystem** | `@anthropic-ai/mcp-filesystem` | Caminhos para pastas locais permitidas | Leitura, escrita e busca em diretórios externos | | **GitHub** | `@anthropic-ai/mcp-github` | Personal Access Token (`GITHUB_TOKEN`) | Busca em repositórios, análise de issues, abertura de PRs | | **PostgreSQL** | `@anthropic-ai/mcp-postgres` | String de conexão (`connectionString`) | Inspeção de esquemas, leitura de tabelas, execução de consultas SQL | | **Brave Search** | `@anthropic-ai/mcp-brave-search` | Chave 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" } } } } ``` --- ## 5. Como o Claude Code usa o MCP no diálogo 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" ] } } } ``` > [!TIP] > 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 │ └─────────────────────────────────────────────────────────────┘ ``` > [!WARNING] > 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_ваш_токен_тут" } } } } ``` 3. 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", "/шлях/до/вашої/папки/з_документами" ] } } } ``` 2. 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 > [!TIP] > **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` > [!TIP] > **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 > [!TIP] > **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 - [x] **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`. - [x] **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). - [x] **Teste de ferramentas:** O funcionamento dos servidores foi verificado com consultas direcionadas após o início da sessão. - [x] **Extensibilidade:** Para tarefas internas específicas, foi criado um template de servidor próprio em TypeScript via `@modelcontextprotocol/sdk`.