MCP na prática: conectar Drive, GitHub, Slack e bancos de dados

# MCP usa JSON-RPC 2.0 para comunicação entre cliente e servidor
# Transporte padrão: stdio (servidor roda como processo filho do Claude Code)
# Alternativas: SSE (Server-Sent Events), HTTP Streamable

# Um servidor MCP expõe três primitivos:

# 1. Tools — funções chamáveis com side effects
{
  "name": "execute_query",
  "description": "Executa uma SQL query no banco de dados",
  "inputSchema": {
    "type": "object",
    "properties": {
      "sql": { "type": "string", "description": "Query SQL a executar" },
      "read_only": { "type": "boolean", "default": true }
    }
  }
}

# 2. Resources — dados navegáveis (URI scheme)
# postgres://localhost/mydb/tables → lista tabelas
# file:///path/to/docs/          → lista documentos

# 3. Prompts — templates reutilizáveis
# "code_review" → template de revisão de código
# "explain_error" → template para explicar stack traces

# Fluxo quando Claude usa um MCP Tool:
# Claude → [tool call: execute_query({sql: "SELECT ..."})]
# Claude Code → [envia para servidor MCP via stdio]
# Servidor MCP → [executa query, retorna resultado]
# Claude Code → [exibe resultado para Claude]
# Claude → [analisa e responde]

# ~/.claude.json (configuração global) ou .claude/mcp.json (projeto)

{
  "mcpServers": {

    # GitHub — issues, PRs, code search
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },

    # PostgreSQL — queries, schema inspection
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://readonly_user:pass@localhost/mydb"
      ]
    },

    # Filesystem — acesso a diretório específico (mais seguro que acesso total)
    "docs": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/dev/projetos/empresa/docs"
      ]
    },

    # Slack — mensagens, canais (requer app token)
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
        "SLACK_TEAM_ID": "T0XXXXXXX"
      }
    },

    # Google Drive (OAuth necessário na primeira vez)
    "gdrive": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-gdrive"]
    },

    # Brave Search — busca web quando Claude precisa de info externa
    "search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    }
  }
}

# Sessão realista: analisar um bug reportado no GitHub, investigar no banco,
# e propor correção no código

$ claude

Você: Temos uma issue aberta no GitHub (#247) sobre usuários não conseguindo
      fazer login após trocar de senha. Investigue e proponha uma correção.

Claude: [usa MCP GitHub] Lendo issue #247...
        Título: "Login falha após reset de senha"
        Descrição: usuário reseta senha, tenta logar, recebe "Invalid credentials"
        Labels: bug, authentication, high-priority

        [usa MCP GitHub] Buscando código relacionado...
        Encontrei src/auth/password.ts - função resetPassword()

        [usa Read] Lendo src/auth/password.ts...

        Encontrei o problema: após reset, o hash é salvo mas o
        campo updated_at não é atualizado. O sistema de cache
        usa updated_at como chave de invalidação — o cache antigo
        com o hash anterior ainda está ativo.

        [usa MCP Postgres] Verificando no banco de dev...
        SELECT id, updated_at, last_password_change FROM users WHERE id = 123;
        → updated_at: 2026-04-10 (não mudou)
        → last_password_change: 2026-04-17 (recente)

        Confirmado: updated_at não é atualizado no reset.

        Posso corrigir src/auth/password.ts e adicionar um teste?

Você: Sim, faça isso.

Claude: [Edit] src/auth/password.ts — adiciona updated_at = NOW() na query de reset
        [Write] src/tests/auth.test.ts — adiciona teste para reset + login
        [Bash] npm test -- auth.test.ts (aguardando confirmação)

Você: [Enter para aprovar]

Claude: Testes passando. Posso criar um comentário na issue #247 com o diagnóstico?

Você: Sim.

Claude: [MCP GitHub] Postando comentário na issue #247...
        "Root cause identified: updated_at not updated on password reset..."
        Feito. Issue atualizada com o diagnóstico e PR pronto para review.

# Para integrar uma API interna ou serviço proprietário, crie seu próprio servidor
# Usando o SDK oficial: @modelcontextprotocol/sdk

# exemplo: servidor MCP para sistema de tickets interno
# arquivo: mcp-tickets-server.js

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: "sistema-tickets",
  version: "1.0.0",
});

// Tool: buscar tickets
server.tool(
  "buscar_tickets",
  "Busca tickets no sistema interno",
  {
    status: z.enum(["aberto", "fechado", "em_andamento"]).optional(),
    assignee: z.string().optional(),
    limit: z.number().default(10),
  },
  async ({ status, assignee, limit }) => {
    const tickets = await fetch(
      `https://tickets.empresa.internal/api?status=${status}&limit=${limit}`,
      { headers: { Authorization: `Bearer ${process.env.TICKETS_TOKEN}` } }
    ).then(r => r.json());

    return {
      content: [{ type: "text", text: JSON.stringify(tickets, null, 2) }],
    };
  }
);

// Resource: lista de projetos
server.resource(
  "projetos",
  "lista de projetos ativos",
  async () => {
    const projetos = await fetch("https://tickets.empresa.internal/api/projetos")
      .then(r => r.json());
    return {
      contents: [{ uri: "tickets://projetos", text: JSON.stringify(projetos) }],
    };
  }
);

// Iniciar servidor
const transport = new StdioServerTransport();
await server.connect(transport);

# Adicionar ao .claude/mcp.json:
{
  "mcpServers": {
    "tickets": {
      "command": "node",
      "args": ["/caminho/para/mcp-tickets-server.js"],
      "env": { "TICKETS_TOKEN": "${TICKETS_TOKEN}" }
    }
  }
}