# Como configurar MCP no Claude Code em 2026: 7 integrações

> Configure o MCP no Claude Code em 5 minutos com claude mcp add. 7 servidores, stdio ou HTTP, âmbitos, hooks e verificação da ligação com /mcp.

Source: https://ailoot.ai/blog/pt-pt/mcp-servers-claude-code/
Canonical: https://ailoot.ai/blog/pt-pt/mcp-servers-claude-code/
Language: pt-PT
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-172
Revision: sha256-1309968a58166a7b5fa497518f87aebf5d628b6efc4c1d8689fd87dd70f1b2a8


As instruções adicionais para trabalhar com Ailoot estão na [documentação](https://ailoot.ai/docs/).



## O que é um servidor MCP e porque é que o Claude Code precisa de um?

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key points in this section">

Pontos-chave

O MCP (Model Context Protocol) é uma norma aberta da Anthropic que dá ao Claude Code acesso a ferramentas e dados externos através de uma interface unificada. Um protocolo em vez de dez APIs diferentes. A Anthropic chama-lhe «USB-C para aplicações de IA»: ligue a porta e o Claude consegue aceder à sua base de dados, ao e-mail, ao messenger ou ao repositório.

</div>

A Anthropic anunciou o MCP em 25 de novembro de 2024 como uma norma aberta. Num ano, o protocolo tornou-se uma norma da indústria: OpenAI, Google DeepMind e Microsoft dão-lhe suporte. O repositório oficial `modelcontextprotocol/servers` contém servidores de referência do próprio projeto MCP (Filesystem, Memory, Sequential Thinking, Fetch e outros); os fornecedores — GitHub, Notion, Stripe, Linear, Cloudflare e Sentry — publicam servidores MCP nos seus próprios repositórios. Os índices comunitários contabilizam milhares de servidores.

Tecnicamente, o MCP funciona sobre JSON-RPC 2.0. A arquitetura é simples: o seu Claude Code é o cliente, qualquer serviço é um servidor e o servidor MCP entre ambos tem três entidades: `tools` (o que a IA pode invocar), `resources` (o que a IA pode ler) e `prompts` (modelos prontos a utilizar).

<figure>
<blockquote>
Tal como o USB-C oferece uma forma normalizada de ligar dispositivos a diferentes periféricos, o MCP oferece uma forma normalizada de ligar modelos de IA a diferentes fontes de dados e ferramentas.
</blockquote>
<figcaption>— Model Context Protocol, https://modelcontextprotocol.io/</figcaption>
</figure>

Porque é que isto importa a quem faz vibe coding: antes do MCP, cada ligação entre o Claude e um serviço de terceiros exigia uma integração separada, com o seu próprio wrapper. Com o MCP, ligar o Postgres, o Slack e o GitHub implica três comandos semelhantes; desligá-los é igualmente simples quando já não precisa do serviço.

## Em que difere o MCP das Skills e dos subagentes?

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key points in this section">

Pontos-chave

Os três mecanismos parecem semelhantes, mas resolvem problemas diferentes. As Skills são os seus fluxos de trabalho e prompts em código. Os subagentes são «colegas» especializados e separados, com o seu próprio contexto. O MCP fornece ferramentas externas através das quais o Claude pode aceder a serviços e dados. Os custos em tokens são diferentes: uma skill é a opção mais económica, enquanto o MCP costuma ser mais caro. Inicialmente, o MCP coloca no contexto apenas os nomes das ferramentas e as instruções do servidor; o Claude carrega as descrições completas a pedido. A maior parte do custo vem das respostas dos serviços: podem ser extensas e permanecer na conversa.

</div>

Uma tabela simples para ter claras as diferenças:

| Mecanismo | O que é | Quando o utilizar | Custo em tokens |
|----|----|----|----|
| Skill | Um ficheiro com instruções e prompts em `.claude/skills/` | Um fluxo de trabalho repete-se: escrever um e-mail, compilar um relatório, publicar uma mensagem | Baixo. Carregado quando é acionado |
| Subagente | Um agente separado com o seu próprio contexto e ferramentas | Uma tarefa longa e paralela: revisão, auditoria, investigação | Médio. Tem o seu próprio contexto |
| Servidor MCP | Um serviço com ferramentas/recursos através de JSON-RPC | É necessário acesso a dados em tempo real: base de dados, e-mail, messenger, repositório | Médio ou alto. Só os nomes das ferramentas ficam no contexto; as descrições são carregadas a pedido e as respostas dos serviços podem ser extensas |

Conclusão prática: se uma tarefa foi especificada uma vez e se repete em texto, é uma skill. Se a IA precisa de uma resposta em tempo real de um sistema externo, é MCP. Se a tarefa é longa, tem ramificações e precisa de um cérebro separado, é um subagente.

Saiba mais sobre os dois mecanismos relacionados: [Claude Code Skills: Como criar a sua própria biblioteca](https://ailoot.ai/blog/pt-pt/claude-code-skills-library/) e [Claude Code Subagents: 5 exemplos prontos](https://ailoot.ai/blog/pt-pt/claude-code-subagents/).

## No Claude Code configurar MCP começa por adicionar e verificar o servidor {#configurar-mcp-no-claude-code-o-seu-primeiro-comando-em-5-minutos}

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key points in this section">

Pontos-chave

A mesma sintaxe funciona em todos os casos: `claude mcp add [name] -- [launch command]`. O servidor aparecerá na lista apresentada por `claude mcp list`. Em seguida, o Claude irá detetar as ferramentas do servidor e começar a utilizá-las na conversa. Não é necessário editar manualmente a configuração — tudo é feito através da CLI.

</div>

Sintaxe completa da documentação oficial:

```bash
claude mcp add <name> [options] -- <command> [args...]
```

São suportados três transportes: `--transport stdio` (predefinido, um processo local), `--transport http` (HTTP remoto) e `--transport sse` (assinalado como obsoleto; utilize-o apenas se o servidor ainda não tiver migrado).

São suportados três âmbitos através da opção `--scope`:

- `local` — apenas na pasta do projeto atual (predefinição).
- `project` — escrito em `.mcp.json`, enviado para o repositório e disponível para toda a equipa.
- `user` — global para todos os projetos na máquina.

Um exemplo mínimo com o servidor de referência Filesystem do projeto MCP. Fica a funcionar em meio minuto:

```bash
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem@2026.8.31 /Users/me/projects
claude mcp list
```

Depois de executar `list`, verá `filesystem` na lista se a pasta indicada no comando existir; sem ela, o servidor não arranca. O servidor poderá ver as pastas de trabalho do Claude Code, ou seja, a pasta a partir da qual o iniciou. Explico mais abaixo, na secção 5.2, porque é assim e quando é que este servidor é realmente útil.

Para verificar se o MCP está ligado, execute `/mcp` numa sessão do Claude Code. Serão apresentados todos os servidores, os respetivos estados e as listas de ferramentas. As instruções adicionais para trabalhar com Ailoot estão disponíveis na [documentação](https://ailoot.ai/docs/). Consulte o README do servidor MCP escolhido para ver os comandos específicos.

## stdio ou HTTP: que transporte deve escolher?

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key points in this section">

Pontos-chave

stdio é um processo local na sua máquina; tudo funciona sem rede e não é necessário OAuth. HTTP é um serviço remoto, acedido com um token ou OAuth, que pode ser partilhado entre dispositivos. Se um servidor MCP for instalado através de `npx` ou `uvx`, utiliza stdio. Se um serviço tiver o seu próprio endereço público, utiliza HTTP. SSE está oficialmente assinalado como obsoleto, por isso não dependa dele.

</div>

Comparação segundo os critérios principais:

| Critério | stdio | HTTP |
|----|----|----|
| Onde é executado | Localmente (um processo subordinado do Claude Code) | Servidor remoto |
| Autorização | Não é necessária | OAuth 2.1 ou token Bearer |
| Portas de rede | Nenhuma | Endereço público |
| Casos de utilização | Filesystem, Postgres, utilitários locais | GitHub, Slack, Notion, Linear, Sentry |
| Reconexão | Não é necessária | Recuo exponencial, até 5 tentativas |
| Implementação | Instalação de um pacote local | Serviço do fornecedor |

Regra prática: tudo o que está guardado no seu disco ou numa base de dados local utiliza stdio. Tudo o que está na nuvem utiliza HTTP. SSE está oficialmente obsoleto; não o escolha.

## 7 servidores MCP prontos a utilizar para empreendedores

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key points in this section">

Pontos-chave

Estas sete configurações cobrem 80% das tarefas de quem faz vibe coding: código (GitHub), ficheiros (Filesystem), base de dados (Postgres através de DBHub), comunicação de equipa (Slack), base de conhecimentos (Notion), monitorização de erros (Sentry) e fluxos de trabalho no browser (Playwright). Para cada configuração abaixo, apresento um comando de instalação de uma linha e um exemplo exato de como pode pedir ao Claude que execute o trabalho numa conversa real.

</div>

### 5.1. GitHub MCP — o servidor oficial do GitHub

O que faz: dá ao Claude Code acesso a issues, pull requests, ficheiros do repositório e execuções de ações. O servidor é open source e tem mais de 30 000 estrelas no GitHub.

Instalação (HTTP, através de OAuth):

```bash
claude mcp add --transport http github https://api.githubcopilot.com/mcp/
```

Em alternativa, utilize stdio através do Docker se precisar de um token PAT em vez de OAuth.

Exemplo: «Lê as issues abertas com a etiqueta `bug`, agrupa-as por componente e sugere a ordem para as fechar.» O Claude irá chamar o GitHub MCP, ler todas as issues e devolver uma lista ordenada por prioridade.

Repositório: [github/github-mcp-server](https://github.com/github/github-mcp-server).

### 5.2. Filesystem MCP — o servidor de referência do projeto MCP

O que faz: dá à IA acesso a ficheiros no computador dentro das pastas aprovadas. É publicado pelo próprio projeto MCP; o registo npm indica Model Context Protocol a Series of LF Projects, LLC como autor.

Instalação (stdio), com uma versão fixa:

```bash
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem@2026.8.31 /Users/me/projects
```

Quando se liga, o Claude Code passa as suas pastas de trabalho ao servidor, substituindo tudo o que foi especificado no comando. As pastas de trabalho do Claude Code são aquela a partir da qual o iniciou, além das que foram adicionadas com o comando `/add-dir` ou com a opção `--add-dir`. Não é possível indicar ao servidor uma pasta separada com maquetas através do comando. Ainda assim, a pasta indicada no comando tem de existir, caso contrário o servidor não arranca.

Assim, no Claude Code, este servidor duplica sobretudo as ferramentas integradas. Para aceder a ficheiros noutra pasta, basta usar `/add-dir`: depois disso, as próprias ferramentas do Claude Code também podem ler essa pasta. O servidor é mais útil para programas que não têm acesso próprio a ficheiros. No Claude Desktop pode ocorrer outro problema: as ferramentas do servidor são rejeitadas porque as respetivas descrições utilizam um formato de esquema antigo; este problema continua em aberto.

Conceda acesso apenas às pastas de que realmente precisa, tanto no comando como através de `/add-dir`. Não conceda acesso à raiz do disco — essa é a primeira falha de segurança.

Exemplo: primeiro `/add-dir ~/Documents/design` e, em seguida, «Move todas as maquetas de `~/Documents/design/landing-v3/` para o projeto atual e muda-lhes o nome segundo a convenção `hero-*.png`».

### 5.3. Postgres MCP — DBHub (Bytebase)

O que faz: liga o Claude a Postgres, MySQL, SQL Server, MariaDB ou SQLite. Suporta o modo só de leitura, para que o agente de IA não possa eliminar a base de dados com um único comando. É frequentemente utilizado como substituto do servidor de referência arquivado da Anthropic, `server-postgres`.

Instalação (HTTP, só de leitura):

```bash
claude mcp add postgres -- npx -y @bytebase/dbhub --dsn "postgresql://user:pass@localhost:5432/mydb?sslmode=disable" --readonly
```

Para uma base de dados de produção, utilize sempre um utilizador separado com permissões apenas de leitura e anonimize os dados pessoais através de uma VIEW ou de uma rota de API intermédia. Não ligue a uma base de dados de produção com permissões de escrita.

Exemplo: «Consulta os clientes cujo estado da subscrição é `expired` no último mês e apresenta os 20 primeiros por valor total de pagamentos.»

Repositório: [bytebase/dbhub](https://github.com/bytebase/dbhub).

### 5.4. Slack MCP — comunicação de equipa

O que faz: dá ao Claude acesso à leitura de canais do Slack e ao envio de mensagens. Útil para automatização: «Quando a compilação passar, publica uma mensagem em `#releases`»; «Compila um resumo semanal de `#engineering`».

Instalação (stdio através de um wrapper npx, como `@modelcontextprotocol/server-slack` ou um equivalente do fornecedor):

```bash
claude mcp add slack \
  -e SLACK_BOT_TOKEN=xoxb-... \
  -e SLACK_TEAM_ID=T0... \
  -- npx -y @modelcontextprotocol/server-slack
```

A autorização utiliza um Slack Bot Token; o acesso é restringido através dos âmbitos do lado do Slack. Pode dar à IA apenas `chat:read` e `chat:write:user`, caso em que não poderá editar as definições do espaço de trabalho. Consulte o README do servidor escolhido para ver os comandos atuais; o ecossistema muda rapidamente.

Exemplo: «Todas as manhãs às 9:00, envia uma lista dos PR integrados ontem para `#daily`».

### 5.5. Notion MCP — base de conhecimentos

O que faz: dá ao Claude acesso a páginas e bases de dados do Notion. É uma base de conhecimento fora do seu projeto: se guardar aí notas, um registo de clientes ou uma política editorial, a IA poderá lê-los.

Instalação (HTTP, através de OAuth):

```bash
claude mcp add --transport http notion https://mcp.notion.com/mcp
```

Em alternativa, utilize o plugin oficial da Anthropic `@makenotion/claude-code-notion-plugin`.

Exemplo: «Na base de dados do Notion “Customers”, encontra todos os que têm o estado “active” e com quem não houve uma chamada há mais de duas semanas. Prepara um e-mail para cada um.»

Guia do Notion: [developers.notion.com/guides/mcp](https://developers.notion.com/guides/mcp/get-started-with-mcp).

### 5.6. Sentry MCP — monitorização de erros

O que faz: liga o Claude aos erros do seu sistema de produção. Quando uma página falha com um erro 500, pode perguntar: «Mostra-me os 10 problemas mais recentes no Sentry para o projeto e explica a causa principal de cada um» e obter uma análise de imediato.

Instalação (HTTP):

```bash
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
```

A autorização é feita através do Sentry OAuth. O acesso pode ser limitado a um projeto específico.

Exemplo: «Seleciona os três problemas mais frequentes das últimas 24 horas. Explica em linguagem simples o que aconteceu e sugere como resolver.»

Repositório: [getsentry/sentry-mcp](https://github.com/getsentry/sentry-mcp).

### 5.7. Playwright MCP — fluxos de trabalho no browser

O que faz: dá ao Claude um browser. A IA pode abrir uma página, clicar, preencher um formulário e tirar uma captura de ecrã. É útil para verificar a interface, fazer testes manuais após a publicação e analisar fluxos de trabalho.

Instalação (stdio):

```bash
claude mcp add playwright -- npx -y @playwright/mcp@latest
```

A versão v0.0.75, lançada em 7 de maio de 2026, é mantida ativamente pela Microsoft (mais de 32 000 estrelas).

Exemplo: «Abre a página inicial do nosso site, verifica se todos os cartões são apresentados corretamente e tira uma captura de ecrã num computador e num telemóvel.»

Repositório: [microsoft/playwright-mcp](https://github.com/microsoft/playwright-mcp).

Consulte o README da versão escolhida do Playwright MCP para obter o comando com uma versão fixa, a opção para várias sessões simultâneas e os erros de instalação mais comuns.



## Como controlar a segurança com um hook PreToolUse

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key points in this section">

Pontos-chave

O MCP dá muito poder à IA: pode escrever em bases de dados, enviar mensagens e eliminar ficheiros. Um hook PreToolUse pode controlar chamadas correspondentes, mas uma expressão regular de prefixos SQL não é autorização de base de dados e um matcher só Postgres não cobre Slack nem ficheiros. Use primeiro permissões reais do serviço e sistema de ficheiros e teste separadamente o âmbito exato do hook.

</div>

Uma lista negra de prefixos SQL não impõe só de leitura: SQL minúsculo, comentários, `UPDATE`, `INSERT`, `ALTER`, várias instruções e funções com efeitos secundários não são cobertos por três prefixos maiúsculos. Use uma função de base de dados separada com permissões só de leitura e verifique-as numa base descartável. Um hook é controlo adicional de chamadas, não substitui essas permissões.

Segue-se um **exemplo de quarentena** deliberadamente restrito: negar todas as chamadas das três famílias MCP indicadas até rever e testar uma política específica. Bloqueia leituras e escritas. Faça corresponder os nomes reais de servidores/ferramentas; um servidor renomeado, Bash incorporado ou outro conector ficam fora destes padrões.

Coloque regras separadas em `.claude/settings.json`:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__postgres__.*",
        "hooks": [{"type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/deny-unapproved-mcp.sh\""}]
      },
      {
        "matcher": "mcp__slack__.*",
        "hooks": [{"type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/deny-unapproved-mcp.sh\""}]
      },
      {
        "matcher": "mcp__filesystem__.*",
        "hooks": [{"type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/deny-unapproved-mcp.sh\""}]
      }
    ]
  }
}
```

Guarde este script em `.claude/hooks/deny-unapproved-mcp.sh`. Devolve o [contrato documentado de decisão PreToolUse](https://code.claude.com/docs/en/hooks#pretooluse-decision-control), não a forma antiga `decision: approve/block` no nível superior:

```bash
#!/bin/bash
printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"This MCP server family is quarantined pending a reviewed policy."}}'
```

O script não interpreta nem classifica SQL. Numa chamada correspondente, nega sempre. Verifique matcher e resultado numa sessão isolada antes de ligar dados valiosos: `SELECT 1`, `delete` minúsculo, `UPDATE` após comentário, leitura ou envio Slack e leitura Filesystem de `.env` devem ser negados quando os nomes correspondem. Uma ferramenta de outra família fica fora do exemplo; verifique explicitamente esse limite separado.

Para leitura de base de dados, use permissões verificadas e substitua a quarentena por política revista das ferramentas reais. Para Slack só de leitura, use credencial sem envio. Para ficheiros, restrinja raízes permitidas do servidor e permissões do processo. Não afirme que o hook impede acesso por outras ferramentas, shell, anexos de prompts ou uma política que o agente pode editar.

A mesma abordagem é explicada em maior detalhe no guia [Plan Mode no Claude Code](https://ailoot.ai/blog/pt-pt/claude-code-plan-mode/) — a lógica de «verificar antes de executar» é semelhante.

## O que fazer se tiver mais de 40 ferramentas e o Claude se perder?

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key points in this section">

Pontos-chave

Sete servidores podem facilmente significar 50–100 ferramentas. O Claude Code utiliza o Tool Search por predefinição: no arranque, apenas os nomes das ferramentas e as instruções dos servidores são colocados no contexto, e o Claude carrega a descrição completa quando precisa de uma ferramenta. Se a pesquisa estiver desativada, todas as descrições são carregadas de uma só vez e, ao fim de cerca de 40 ferramentas, o Claude começa a confundir-se: escolhe a ferramenta errada ou recorre ao MCP quando um comando normal seria suficiente.

</div>

De acordo com a [documentação do Claude Code](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search), está agora ativado por predefinição e não precisa de ser ligado manualmente.

Exceções em que o Claude Code carrega todas as ferramentas de imediato: utilização através de um proxy de terceiros (quando `ANTHROPIC_BASE_URL` está definido para um endereço diferente do da Anthropic), modelos anteriores à geração 4.5 no Google Cloud e implementações do Microsoft Foundry no Azure. A variável `ENABLE_TOOL_SEARCH` altera o comportamento:

- não definida — todas as ferramentas MCP são adiadas e carregadas a pedido;
- `true` — o mesmo, além de o Claude Code tentar ativar a pesquisa através de um proxy;
- `auto` — modo por limiar: enquanto todas as descrições das ferramentas ocuparem menos de 10% da janela de contexto, são carregadas de imediato; acima desse valor, são adiadas;
- `auto:N` — o mesmo, mas com um limiar percentual personalizado, por exemplo `auto:5`;
- `false` — o comportamento antigo; todas as ferramentas ficam imediatamente no contexto.

Para ferramentas críticas que têm de estar sempre visíveis, existe a opção `alwaysLoad: true` em `.mcp.json`, junto à descrição do servidor. Cada uma destas ferramentas ocupa espaço no contexto desde o primeiro minuto, por isso utilize esta opção apenas nas ferramentas de que o Claude precisa em quase todas as respostas.

Se tiver cinco ou mais servidores MCP e o Claude se confundir sobre a ferramenta a invocar, verifique primeiro se a pesquisa está desativada: procure `ENABLE_TOOL_SEARCH=false` nas definições e confirme se está a trabalhar através de um proxy.

Também poderá ajudar [reduzir o contexto com /compact](https://ailoot.ai/blog/pt-pt/claude-code-token-limits-saving/).

## Quando não precisa de MCP: será melhor usar uma Skill, um subagente ou a CLI?

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key points in this section">

Pontos-chave

Em termos de tokens, o MCP é a forma mais dispendiosa de dar capacidades externas ao Claude. Se a tarefa puder ser executada com uma ferramenta CLI pronta a utilizar (`gh issue list`, `psql`, `curl`) ou com uma skill de uma página, utilize essas opções em vez de criar servidores MCP. Regra: o MCP só se justifica quando a IA precisa de uma conversa bidirecional em tempo real com um serviço, e não de uma resposta pontual.

</div>

Hierarquia por custo em tokens e complexidade:

1.  **Comando CLI através do Bash** — quase gratuito. A IA executa `gh pr list`, `psql -c` ou `curl` e recebe uma resposta como qualquer utilizador do terminal.
2.  **Skill** — económica. Um modelo de prompt pronto a utilizar, com instruções sobre o que invocar e como processar o resultado. Carregado com base num acionador no nome da pasta.
3.  **Subagente** — custo médio. Contexto separado para uma tarefa longa, com a sua própria sessão de tokens.
4.  **Servidor MCP** — dispendioso. Apenas os nomes das ferramentas permanecem no contexto, mas a descrição da ferramenta é carregada quando o Claude a encontra antes de uma chamada; as respostas dos serviços podem ser extensas: o Claude Code avisa quando uma resposta de ferramenta excede 10 000 tokens. Além disso, é necessária uma sessão OAuth para HTTP.

Conselho contraintuitivo: para analisar páginas Web, trabalhar com git, abrir PDFs e utilizar utilitários open source, escolha **CLI**, não MCP. A IA pode invocar comandos do terminal tão bem como uma pessoa, e só são gastos tokens com o comando e a respetiva resposta, sem descrições de ferramentas nem custos adicionais do servidor.

O MCP justifica-se em dois casos:

- O serviço é **fechado**: Slack, Notion, Sentry, Linear. Também existem ferramentas CLI, mas o MCP oferece um acesso mais granular através de OAuth e controlos de âmbito.
- É necessária uma **conversa bidirecional em tempo real**: a IA liga-se ao Postgres, verifica o esquema, faz uma pergunta de seguimento, obtém os dados e avança para o passo seguinte. Com a CLI, isso implicaria 10 comandos manuais.

## 6 antipadrões de ligação ao MCP

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key points in this section">

Pontos-chave

Seis erros concretos que apanham desprevenidos os adeptos de vibe coding nas primeiras semanas com MCP. Cada antipadrão pode ser corrigido num minuto: abra `claude mcp list`, reveja a lista e verifique os âmbitos e os hooks. A maioria dos problemas resolve-se removendo um servidor desnecessário, não adicionando outro; esta secção é uma lista de verificação curta que pode seguir do princípio ao fim.

</div>

1.  **Armário de MCP.** Ligou 10 servidores «por precaução»; o Claude confunde-se sobre que ferramenta invocar e as respostas destes servidores enchem o contexto. Solução: mantenha 3–5 servidores para o projeto atual e remova os restantes com `claude mcp remove`.

2.  **Acesso de escrita a uma base de dados de produção.** Ligou o Postgres MCP a uma base de dados de produção sem `--readonly`, um utilizador separado ou um hook de lista de permissões. Basta um prompt — «elimina os registos de teste» — para apagar dados de produção. Solução: uma função de base de dados separada com permissões só de leitura verificadas, modo só de leitura do servidor quando aplicável e controlos testados de chamadas. A lista de prefixos `DROP|TRUNCATE|DELETE` não é autorização suficiente.

3.  **Dados pessoais sem anonimização.** Ligou diretamente uma base de dados com os e-mails, números de telefone e dados de passaporte dos clientes. O Claude vê os dados e estes acabam nos registos da Anthropic. Solução: uma VIEW ou uma rota de API intermédia que devolva dados mascarados, como `j***@gmail.com`.

4.  **MCP em vez de uma skill.** Precisa de «criar um relatório de vendas no formato X» — uma tarefa de rotina que uma skill com um prompt pronto resolve. Não crie um servidor MCP.

5.  **MCP em vez de uma CLI open source.** Precisa de converter um PDF em texto. Existe `pdftotext`. Não crie um «PDF MCP» — só desperdiçaria tokens.

6.  **Não acompanhar os custos em tokens.** Consegue ver o servidor ligado em `claude mcp list`, mas não quanto utiliza em cada conversa. Ao fim de uma semana, nem imagina que «o MCP consumiu 40% do contexto e estive a pagar por isso durante todo este tempo». Solução: desative periodicamente os servidores que não utiliza e acompanhe as alterações de utilização através de [acompanhamento do limite de utilização do Claude Code](https://ailoot.ai/blog/pt-pt/claude-code-token-limits-saving/).

## Como resolver problemas de ligação ao MCP

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key points in this section">

Pontos-chave

Os problemas mais comuns são: o callback do OAuth não funciona, o nome do servidor entra em conflito com um servidor existente ou a ferramenta não aparece em `claude mcp list` após o comando `add`. O procedimento normal de diagnóstico resolve-os: `list` mostra o que foi ligado, `status` verifica o indicador de estado e, se estiver vermelho, `logs` devolve um stack trace. Depois de ajustar `--scope` ou uma variável ENV, reinicie tudo.

</div>

Lista de verificação passo a passo:

1.  **O servidor está visível na lista?**

    ```bash
    claude mcp list
    ```

    Caso contrário, `claude mcp add` não foi concluído. A causa mais comum é `--scope`: adicionou-o a `local` e está a verificar a partir de outro projeto.

2.  **O estado do servidor está verde?**

    ```bash
    claude mcp status <name>
    ```

    Vermelho significa que o processo não arrancou (stdio) ou que o servidor não respondeu (HTTP).

3.  **Os registos do servidor mostram algo útil?**

    ```bash
    claude mcp logs <name>
    ```

    Se vir um stack trace, o problema está normalmente relacionado com o pacote (`npx` não conseguiu encontrá-lo ou a versão do Node é anterior à 20).

4.  **O callback do OAuth não está a regressar?** O problema está normalmente relacionado com `--callback-port` ou com um filtro de rede. Reencaminhe uma porta específica:

    ```bash
    claude mcp add --transport http --callback-port 8765 [name] [url]
    ```

5.  **Há um conflito no nome da ferramenta?** Dois servidores expõem uma ferramenta com o mesmo nome e o Claude invoca a errada. Utilize o Tool Search (consulte o H2 anterior) ou remova manualmente o servidor a mais com `claude mcp remove`.

6.  **Não consegue ver as extensões (connectors) do claude.ai?** É um problema conhecido: as extensões (connectors) da interface Web do claude.ai não estão disponíveis no Claude Code quando este utiliza uma chave API. Solução: ligue o MCP através da CLI, não da interface Web.

## Próximos passos: OAuth, os seus próprios servidores MCP e o Plugin Marketplace

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key points in this section">

Pontos-chave

Depois dos sete servidores prontos a utilizar, os três passos seguintes são configurar OAuth para os seus próprios servidores HTTP (se quiser partilhar o MCP com a equipa), criar o seu próprio MCP para um serviço único e ligar-se ao Plugin Marketplace da Anthropic. O Marketplace foi lançado em 9 de outubro de 2025 e integra o MCP em plugins que podem ser instalados com um único comando.

</div>

O Plugin Marketplace acelera o trabalho de quem não quer memorizar comandos de instalação. O formato consiste num manifesto `.claude-plugin/marketplace.json` que descreve um conjunto de servidores num único pacote.

Instale um plugin do marketplace:

```bash
claude plugin install <plugin-name>
```

Um plugin pode conter vários servidores MCP, skills e subagentes ao mesmo tempo — uma configuração empacotada para um cenário específico: comércio eletrónico, marketing ou um departamento jurídico.

Escreva o seu próprio servidor MCP de acordo com a especificação `modelcontextprotocol.io`. Um modelo mínimo utiliza o SDK Python ou TypeScript da Anthropic; em seguida, descreva as ferramentas e ligue um transporte. A complexidade é comparável à de escrever uma API REST com FastAPI.

Se o seu projeto já tiver um [CLAUDE.md configurado](https://ailoot.ai/blog/pt-pt/claude-md-template/) e compreender a [engenharia de contexto](https://ailoot.ai/blog/pt-pt/context-engineering/), adicionar o seu próprio MCP demora um dia. Se ainda não tiver esses elementos, é melhor aprender primeiro os conceitos básicos.

<div class="section" role="doc-bibliography" aria-label="Sources">

### Fontes

- [Model Context Protocol — site oficial](https://modelcontextprotocol.io/)
- [A Anthropic apresenta o MCP — 25 de novembro de 2024](https://www.anthropic.com/news/model-context-protocol)
- [Documentação MCP do Claude Code](https://code.claude.com/docs/en/mcp)
- [Claude Code: pesquisa de ferramentas MCP](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search)
- [Anúncio do Claude Code Plugins — 9 de outubro de 2025](https://claude.com/blog/claude-code-plugins)
- [Code with Claude 2026](https://claude.com/code-with-claude)
- [modelcontextprotocol/servers — registo oficial](https://github.com/modelcontextprotocol/servers)
- [github/github-mcp-server](https://github.com/github/github-mcp-server)
- [microsoft/playwright-mcp](https://github.com/microsoft/playwright-mcp)
- [bytebase/dbhub — Postgres MCP](https://github.com/bytebase/dbhub)
- [getsentry/sentry-mcp](https://github.com/getsentry/sentry-mcp)
- [makenotion/claude-code-notion-plugin](https://github.com/makenotion/claude-code-notion-plugin)
- [Guia MCP do Notion](https://developers.notion.com/guides/mcp/get-started-with-mcp)
- [Repositório Anthropic Claude Code — issues e changelog](https://github.com/anthropics/claude-code)

</div>





Para continuar a trabalhar com modelos, aceda a [Ailoot](https://ailoot.ai/).

## Perguntas frequentes

### Este hook torna só de leitura o acesso à base de produção?

Não. O exemplo põe em quarentena todas as chamadas correspondentes às famílias MCP indicadas; não classifica SQL. Só de leitura deve vir de uma função separada com permissões verificadas, usando hooks como controlo adicional.

### Como testo o âmbito do hook?

Numa sessão isolada, confirme a negação de nomes correspondentes em leituras e escritas, incluindo SQL minúsculo ou com comentário inicial. Confirme depois que uma ferramenta alheia fica fora do matcher; esse percurso descoberto exige permissões ou política próprias.


## Ailoot · A empresa e a sua carteira de projetos

A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI.

A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões.

A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.
