Guia de MCP Server no Claude Code: integre SaaS com segurança

Um MCP Server transforma o Claude Code em uma ferramenta capaz de ler issues do GitHub, buscar documentos de equipe, consultar Notion, Google Drive, CRM ou APIs internas. Isso é poderoso, mas também muda o risco. Um scope amplo demais, token dentro de .mcp.json, OAuth aprovado sem revisão, npx quebrando no Windows ou respostas enormes com 10,000 token warning podem tornar a integração frágil.

Este guia foca no uso real: começar pequeno, escolher o scope correto, manter segredos fora de arquivos compartilhados, verificar tudo com /mcp e expor apenas as ferramentas necessárias.

O que MCP muda no Claude Code

MCP significa Model Context Protocol. É um padrão para conectar clientes de IA a ferramentas e fontes de dados externas. O Claude Code atua como MCP client e chama tools expostas por um MCP server.

Sem MCP, Claude Code vê principalmente o repositório e o contexto que você fornece. Com MCP, pode ver documentos, tickets, métricas de produto, dados de clientes e serviços internos. Então a primeira pergunta é: quais dados este projeto pode acessar, com quais permissões e qual revisão humana será mantida?

Para limites de permissão, veja também o guia de permissões do Claude Code e as práticas de segurança.

Transporte	Uso	Atenção
stdio	Servidor local com npx, Python ou binário interno	No Windows, use cmd /c npx quando necessário
http	MCP remoto, SaaS e OAuth	Revisar workspace e scopes
sse	Compatibilidade com servidores antigos	Para novas integrações, prefira HTTP

Escolha o scope primeiro

claude mcp add aceita --scope local, --scope project e --scope user.

scope	Significado	Quando usar
local	Só no projeto atual da sua máquina	Teste, cliente, conexão com segredo
project	Salvo em .mcp.json e compartilhado no repo	Definição comum para equipe
user	Disponível em todos os projetos Claude Code	Ferramenta pessoal realmente genérica

Comece com local. Use project quando a equipe precisar compartilhar nomes e comandos. Use user com cautela.

claude mcp add --scope local --transport stdio repo-files -- npx -y @modelcontextprotocol/server-filesystem ./docs

claude mcp add --scope project --transport http team-docs https://mcp.example.com/mcp

claude mcp add --scope user --transport http personal-notes https://mcp.example.com/mcp

Servidores project-scoped exigem aprovação. Isso é uma proteção, não um incômodo.

Windows: use cmd /c npx

No Windows, npx pode funcionar no PowerShell e falhar quando o Claude Code inicia o servidor stdio. O padrão confiável é cmd /c npx.

claude mcp add --scope local --transport stdio repo-files -- cmd /c npx -y @modelcontextprotocol/server-filesystem "C:\Users\masa\work\claudecode-lab\docs"

Em .mcp.json, separe comando e argumentos.

{
  "mcpServers": {
    "repo-files": {
      "type": "stdio",
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\masa\\work\\claudecode-lab\\docs"
      ],
      "env": {}
    }
  }
}

Não entregue o diretório inteiro do usuário no primeiro teste. Comece por docs, reports ou um repo descartável. Se o servidor puder escrever, combine com o guia de hooks do Claude Code.

MCP remoto, OAuth e /mcp

Para Notion, Google Drive, GitHub ou CRM, HTTP costuma ser o transporte mais claro.

claude mcp add --scope local --transport http notion https://mcp.notion.com/mcp

Depois rode /mcp dentro do Claude Code. Verifique conexão, OAuth e tools expostas.

/mcp

# Confira:
# - servidor connected
# - OAuth authenticated
# - workspace correto
# - tools esperadas
# - sem write/admin se a intenção era read-only

APIs internas com bearer token podem usar header.

claude mcp add --scope local --transport http crm-readonly https://mcp.example.com/readonly \
  --header "Authorization: Bearer $CRM_READONLY_TOKEN"

O .mcp.json da equipe deve descrever conexões, não guardar segredos.

{
  "mcpServers": {
    "customer-docs": {
      "type": "http",
      "url": "https://mcp.example.com/customer-docs"
    },
    "github-readonly": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@example/github-readonly-mcp"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_READONLY_TOKEN}"
      }
    }
  }
}

Caso 1: GitHub e Notion para triagem

O ganho rápido vem de reduzir a troca entre issue, PR e especificação. Claude Code pode ler uma issue via GitHub MCP, buscar requisitos em Notion e resumir risco antes de editar.

Leia a issue #248 no GitHub e busque requisitos relacionados na documentação do produto.
Ainda não altere código.
Retorne:
1. Arquivos provavelmente afetados
2. Requisitos claros
3. Perguntas abertas
4. Menor plano seguro de implementação

Esse “ainda não altere código” é importante. MCP dá mais contexto, mas também pode acelerar uma decisão errada.

Caso 2: Google Drive para proposta

Em consultoria, treinamento e desenvolvimento sob demanda, atas e propostas antigas ficam no Drive. Um MCP read-only ajuda a criar rascunhos.

Pesquise a pasta "2026-05 Customer A".
Crie um esboço de proposta:
1. Cinco problemas do cliente
2. Escopo provável
3. Pontos a confirmar
4. Três planos: treinamento, suporte de implementação e operação

Masque nomes, emails e valores exatos.

A configuração segura é pasta limitada, somente leitura e revisão humana antes do envio.

Caso 3: métricas read-only

MCP pode conectar métricas de produto ou analytics. Não dê permissão de escrita em produção para análise. Um endpoint read-only basta.

claude mcp add --scope local --transport http product-metrics https://mcp.example.com/readonly-metrics \
  --header "Authorization: Bearer $METRICS_READONLY_TOKEN"

Analise fontes de tráfego, PV por artigo e cliques de conversão dos últimos 14 dias.
Agrupe páginas por tema.
Recomende cinco próximos artigos com a métrica que sustenta cada ideia.
Inclua onde os dados são fracos ou ruidosos.

Isso aproxima conteúdo de monetização, porque cria um ciclo de feedback.

10,000 token warning

Quando uma tool MCP devolve conteúdo demais, Claude Code pode mostrar 10,000 token warning. Isso acontece com buscas que retornam texto completo, listas longas, HTML inteiro ou queries sem limite.

Reduza a saída primeiro.

Retorne no máximo 10 resultados.
Para cada um, inclua título, URL, data de atualização e motivo.
Não inclua texto completo até eu pedir um item específico.

Para análise pontual:

MAX_MCP_OUTPUT_TOKENS=50000 claude

$env:MAX_MCP_OUTPUT_TOKENS = "50000"
claude

Se isso for necessário todo dia, redesenhe o servidor com paginação, filtros e resumo.

Falhas comuns

Primeira falha: segredos em .mcp.json. Configuração project é compartilhada; use env, OAuth ou secret manager.

Segunda: --scope user por conveniência. Integrações de clientes podem aparecer em outros projetos.

Terceira: tratar documentos externos como comandos. Conteúdo lido por MCP é dado, não instrução.

Quarta: não verificar /mcp após OAuth. Login certo não garante workspace certo.

Quinta: depender de respostas gigantes. Fluxos estáveis filtram, resumem e pedem detalhe sob demanda.

Diagnóstico

claude mcp list
claude mcp get repo-files

Dentro do Claude Code:

/mcp

Reset de aprovação do projeto:

claude mcp reset-project-choices

Teste mínimo:

Verifique apenas a conexão repo-files.
Liste até 10 nomes de arquivo na pasta permitida.
Não leia conteúdo e não modifique nada.

Monetização: venda o fluxo seguro

MCP está perto da receita porque conecta Claude Code aos sistemas reais de uma equipe. Mas “instalo MCP Server” é fraco. Melhor: “conecto GitHub, Notion, Google Drive e SaaS interno com segurança para o time usar Claude Code toda semana”.

• Produto inicial: templates .mcp.json e checklist de segurança
• Serviço de equipe: revisão de GitHub, Notion, Drive e permissões
• Premium: scope, OAuth, hooks, monitoramento e treinamento

Comece com filesystem em uma pasta de teste. Em equipe, escolha um SaaS read-only e um .mcp.json project-scoped, depois conecte ao Claude Code Harness Engineering.

Este artigo segue a documentação oficial de Claude Code sobre claude mcp add, scopes, .mcp.json, /mcp, OAuth, project server approval e MAX_MCP_OUTPUT_TOKENS. Regra prática: scope pequeno, read-only primeiro, nenhum segredo compartilhado e verificação antes de usar.