6.2 Install-mcp | Curso iAmasters OS

🌐 O que é MCP (Model Context Protocol)

MCP é um standard aberto (lançado pela Anthropic em 2024) que define como Claude consome ferramentas de serviços externos. Um MCP server "publica" tools; Claude usa-as como se fossem nativas.

💡 Analogia

Sem MCPs, Claude é um chef sem ingredientes: só sabe usar o que lhe escreves no prompt. Com MCPs, abre a despensa (BD, GitHub, Notion, sites) e usa o que precisa.

Diferente de plugins fechados de cada produto: um standard único que todos seguem. Permite ecossistema aberto.

Arquitetura básica

┌─────────────┐     stdio/SSE     ┌─────────────────┐
│ Claude Code │  ←────────────→   │  MCP Server     │
│  (cliente)  │   tools, calls    │  (npx package)  │
└─────────────┘                   └────────┬────────┘
                                           │
                                           ↓
                                  Serviço externo
                                  (Supabase, GitHub,
                                   Notion, BD…)

📊 Como Claude escolhe tools

Igual ao mecanismo das skills: cada tool tem nome + description semântica. Claude faz matching do teu prompt contra todas as descriptions e chama a tool relevante.

Por isso descrições mal feitas em MCPs fazem-no ativar nos momentos errados ou ignorá-los quando devia usá-los.

📦 /install-mcp: lista curada vs URL custom

O comando aceita dois modos: nome curto (procura no catálogo) ou JSON custom (valida antes de instalar).

Modo 1 · Lista curada

/install-mcp context7
/install-mcp github
/install-mcp supabase

Procura em docs/mcps-curated.md, usa config validada, pede env vars necessárias, escreve em .mcp.json.

Modo 2 · URL/JSON custom

/install-mcp \
  https://github.com/x/y-mcp

/install-mcp '{
  "command": "npx",
  "args": [...]
}'

Valida estrutura, deteta env vars referenciadas, avisa se scopes opacos. Requer mais auditoria humana.

O que o comando faz

Lê .mcp.json atual (ou cria se não existe)
Valida que MCP não está já configurado (oferece replace)
Pede env vars necessárias (escreve em .env se não existem)
Adiciona entry em mcpServers
Atualiza .claude/settings.json com permissões mínimas
Avisa para reiniciar Claude Code (Ctrl+C × 2 + claude)
Sugere teste: prompt que deveria ativar o novo MCP

💡 .mcp.json por cliente

Se cliente A precisa Supabase e B não, mantém .mcp.json diferente por cliente em clients/<nome>/.mcp.json. Evita inflar contexto desnecessariamente em sessões onde o MCP não serve.

⭐ Top 5 recomendados

Cobrem ~80% das necessidades de um operador IA. Todos com plano grátis útil. Validados em produção pelo maintainer.

MCP	Para que	Plano
context7	Docs vivos de frameworks (Next.js, Supabase, Tailwind) injetados no contexto. Evita alucinação de APIs obsoletas.	Grátis
github	Ler issues/PRs/ficheiros, criar/comentar issues, mergear PRs sem sair do Claude.	Grátis (PAT)
supabase	Queries SQL, gestão tabelas, RLS, edge functions. READ-ONLY token para começar.	Grátis (OSS)
notion	Ler páginas, criar BDs, mover páginas. Se o teu wiki/CRM está no Notion.	Grátis (limite)
firecrawl	Scraping de sites com bot blockers. Usado por skills marketing-*. NÃO vai em .mcp.json, vai em .env.	500 free + Hobby $16/mo

📊 Ordem de instalação sugerida

context7 primeiro — zero risco, valor imediato em qualquer projeto técnico
github depois — quando começas a usar Claude para issues/PRs
firecrawl se vais scraping recorrente (não MCP — só env var)
supabase ou notion conforme o stack

💡 Outros úteis

linear (gestão de tickets), gmail (READ-ONLY), slack (READ-ONLY), filesystem (whitelisted), n8n-mcp (para criar workflows). Todos em docs/mcps-curated.md.

📄 .mcp.json: estrutura, env vars, permissões

O .mcp.json é o ficheiro de config no root do repo. JSON com chave mcpServers + um objeto por server.

Anatomia típica

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PAT"
      }
    },
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--project-ref=$SUPABASE_PROJECT_REF",
        "--read-only"
      ],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "$SUPABASE_ACCESS_TOKEN"
      }
    }
  }
}

command + args

Quase sempre npx -y <package>. O -y evita prompt de confirmação. Args adicionais (flags como --read-only, --project-ref) variam por MCP.

env

Variáveis passadas ao processo do MCP. Sempre referenciadas ($VAR), nunca literais. Valores em .env do repo (no .gitignore).

⚠️ Permissões em .claude/settings.json

Cada MCP precisa entrada em permissions.allow:

"permissions": {
  "allow": [
    "mcp__context7__*",
    "mcp__github__*",
    "mcp__supabase__*"
  ]
}

Sem isto, Claude pergunta confirmação a cada uso. Wildcard * permite todas as tools desse MCP.

📊 Token budget: 5-7 MCPs ativos máximo

Cada MCP ativo adiciona ~500-2000 tokens ao system prompt (descrições das tools que expõe). 10 MCPs = facilmente 10-20K tokens fixos por sessão, antes de começares a falar.

MCPs ativos	Custo aprox. tokens	Veredito
1-3	~1-5K	Ótimo
4-7	~5-15K	Aceitável
8-12	~15-25K	Aviso
13+	25K+	Mau — degrada respostas

📊 Sintomas de demasiados MCPs

•Respostas pioram em sessões longas (context window cheio antes do esperado)
•Claude esquece info anterior mais cedo
•Claude chama tool errada (porque muitas descrições parecidas)
•Latência de startup mais alta (todos os MCPs arrancam ao iniciar)

💡 Estratégia

Mantém 5-7 MCPs ativos globalmente. Os que precisas só ocasionalmente, comenta no .mcp.json e descomenta quando precisares. Ou tem .mcp.json diferente por cliente.

🚫 MCPs a evitar

Nem todos os MCPs valem o risco. Estas categorias estão no "a evitar" do docs/mcps-curated.md.

✗ Write em redes sociais sem gates

MCPs que postam em LinkedIn, X, Instagram sem aprovação humana intermédia. Risco crítico de fuga de identidade (post errado, momento errado, tom errado) numa conta com seguidores.

✗ MCPs com scopes opacos

Se a documentação não diz claramente que tools expõe e com que permissões, não instalar. Tools "fazem tudo" são red flag — Claude pode chamar coisas que não esperavas.

✗ MCPs custom não auditados

MCPs de devs desconhecidos sem código revisto. Estás a executar código deles em runtime com acesso a credenciais tuas. Audita ou usa alternativa conhecida.

✗ Write em BD de produção

Supabase, Postgres, etc. — começa READ-ONLY. Eleva para write só quando confiares no fluxo. Tens backups testados? Replica? Se não, fica em read.

📊 Princípios gerais

READ antes de WRITE em todos os MCPs com permissões sensíveis
Scopes mínimos — só tokens com permissões necessárias
Gates humanos para ações irreversíveis ou públicas
Monitoriza custos em APIs pagas (firecrawl, OpenAI via MCPs)
Audita código de MCPs custom antes de instalar

💡 Em caso de dúvida

Se um MCP não está em docs/mcps-curated.md e não tens tempo para auditar, não instales. Espera pela revisão trimestral do catálogo ou submete-o tu próprio em PR para a comunidade revisar.

✅ Resumo do Módulo

✓

MCP = standard aberto para tools externas — Claude consome como nativas

✓

/install-mcp em 2 modos — nome curto (curado) ou JSON custom (auditado)

✓

Top 5: context7, github, supabase, notion, firecrawl — cobrem 80% das necessidades

✓

.mcp.json com env vars referenciadas — $VAR, nunca literal, permissões em settings.json

✓

5-7 MCPs ativos máximo — token budget realista, .mcp.json por cliente

✓

A evitar: write redes sem gates, scopes opacos, custom não auditados — READ antes de WRITE sempre

Próximo Módulo:

6.3 — Criar a tua skill própria com meta-skill-creator + critérios para contribuir ao catálogo iAmasters.

← Voltar para Trilha 6 Módulo 6.3 →