Toeverything·Publicado 20 de ago. de 2026 · Atualizado 21 de ago. de 2026
Como adicionar servidores MCP ao Claude Code (e Desktop)
Produtividade
Resumo em 30 segundos
O Claude Code fala MCP de fábrica: para um servidor remoto, basta um comando claude mcp add e alguns minutos.
A configuração mora em um de três escopos (local, project e user). Compartilhamento com o time é no project; credenciais ficam no escopo pessoal.
O Claude Desktop tem dois caminhos: Connectors (remoto) e arquivo de configuração (local). As configurações dele e do Claude Code são independentes.
Servidor sumido? Dentro da sessão, o comando /mcp mostra o estado da conexão — comece sempre por aí.
Este guia cobre o comando claude mcp add e a lógica dos escopos, a configuração no Claude Desktop, o passo a passo completo usando um workspace do AFFiNE como exemplo e a lista de verificação para quando a conexão não aparece. Se o conceito ainda é novidade para você, comece por o que é um servidor MCP.
Adicionando servidores MCP ao Claude Code
Para um servidor remoto (HTTP) — o caso mais comum com serviços hospedados:
claude mcp add --transport http <nome> <URL do servidor> \
--header "Authorization: Bearer <token>"
Guias antigos ainda mostram --transport sse; o transporte SSE está descontinuado — quando o serviço oferecer os dois, fique com o HTTP.
Para um servidor local (stdio), que o Claude Code executa na sua máquina:
claude mcp add <nome> -- <comando que inicia o servidor>
A manutenção cabe em três subcomandos: claude mcp list para ver o que está configurado, claude mcp get para os detalhes e claude mcp remove para apagar. Se o produto entrega um JSON pronto, claude mcp add-json '' aceita o trecho como está. Durante a sessão, o comando /mcp mostra o estado da conexão e as ferramentas disponíveis — primeiro lugar para olhar quando alguma coisa não bater. As flags menos comuns estão todas na referência oficial de MCP do Claude Code.
Nem todo servidor hospedado usa token fixo: serviços como Sentry, Linear e Notion ficam atrás de OAuth. Nesse caso, o claude mcp add vai sem --header — logo depois, o claude mcp list mostra o servidor como ! Needs authentication, que é o estado esperado, não um erro. Abra uma sessão, rode /mcp, selecione o servidor e escolha Authenticate: o login termina no navegador, e dali em diante os tokens são renovados sozinhos.
Escopos: local, project e user
Onde a configuração é gravada define quem a enxerga (local e user moram no ~/.claude.json da sua máquina; project, em um arquivo versionado no repositório):
local (padrão): este projeto, esta máquina, só você. Ideal para experimentos e credenciais pessoais.
project: gravado em um arquivo .mcp.json na raiz do repositório, versionado e compartilhado com o time inteiro. É o lugar de servidores padrão da equipe, como a base de conhecimento; cada colega aprova o servidor no primeiro uso.
user (--scope user): vale para você em todos os projetos da máquina. Para os servidores pessoais de uso constante.
Quando o mesmo nome existe em mais de um escopo, vale o mais específico: local ganha de project, que ganha de user.
A regra prática: credenciais ficam no escopo pessoal; o que se compartilha via project é a definição do servidor, com cada pessoa fornecendo o próprio token por variável de ambiente. O .mcp.json expande a sintaxe ${VAR} — e ${VAR:-padrão}, com valor de reserva — em campos como url e headers: o arquivo versionado guarda Authorization: Bearer ${AFFINE_TOKEN}, e o valor de verdade mora no ambiente de cada máquina.
Adicionando ao Claude Desktop
Servidor remoto: Configurações → Connectors → adicionar conector personalizado, colar a URL e autorizar. É o caminho sem terminal — para servidores hospedados como o do AFFiNE ou o do Notion, resolve.
Servidor local: edite o claude_desktop_config.json (Configurações → Desenvolvedor → editar configuração), acrescente o servidor em mcpServers e reinicie o aplicativo.
Os mesmos servidores funcionam no Claude Code e no Claude Desktop, mas cada um guarda a própria configuração — configure uma vez em cada aplicativo que usar. Um atalho para não digitar tudo duas vezes: no macOS (ou no WSL), o comando claude mcp add-from-claude-desktop importa para o Claude Code, com um seletor interativo, os servidores que você já tinha no aplicativo.
Do início ao fim: conectando sua base de conhecimento
O ciclo completo com o servidor MCP embutido do AFFiNE, que torna documentos e quadros brancos do workspace pesquisáveis por qualquer cliente MCP:
Crie a credencial. No AFFiNE: Configurações → Integrations → MCP Server → Create credential. Dê o nome do cliente (“Claude Code”; uma credencial por cliente facilita a revogação), mantenha o acesso padrão somente leitura e defina a validade.
Copie a configuração. O token aparece uma única vez, ao lado do botão Copy JSON, que gera a configuração completa — URL do endpoint e cabeçalho de autenticação incluídos. O endpoint segue o formato https://app.affine.pro/api/workspaces//mcp; em instâncias auto-hospedadas, entra o endereço do seu servidor.
Adicione:
claude mcp add --transport http affine \
"https://app.affine.pro/api/workspaces/<id do workspace>/mcp" \
--header "Authorization: Bearer <token>"
Use. Abra uma sessão e faça uma pergunta que só as suas notas respondem: “ache o desenho da lógica de retentativa de pagamento e resuma os pontos em aberto”. O Claude Code chama a ferramenta de busca (palavra-chave + semântica, quadros brancos incluídos), lê o documento dentro das suas permissões — o conteúdo chega em Markdown — e responde com o que realmente está escrito lá.
Sem custo adicional: funciona no AFFiNE Cloud e em instâncias auto-hospedadas com os recursos de IA ativados.
O transporte define onde o servidor roda; as permissões da credencial definem quais ferramentas e dados o cliente pode acessar.
A mesma configuração no Cursor e no ChatGPT
O Cursor lê o ~/.cursor/mcp.json (ou .cursor/mcp.json por projeto). A saída do Copy JSON do AFFiNE bate com o formato do Cursor como está: cole, reinicie, pronto.
O ChatGPT conecta a servidores MCP remotos pelos conectores; servidores personalizados pedem o modo de desenvolvedor (Configurações → Conectores → Avançado). O mesmo endpoint e o mesmo cabeçalho passam sem mudança. Um servidor, todos os assistentes — essa é justamente a proposta do MCP.
Solução de problemas: o servidor não aparece
Desça a lista na ordem; a grande maioria dos casos termina aqui:
Primeiro o /mcp. Ele mostra se o servidor conectou, falhou na autenticação ou nem subiu. Ler o erro exibido é mais rápido que chutar.
Transporte errado. Servidor hospedado exige --transport http; sem a flag, o Claude Code trata a URL como comando local. Remova e adicione de novo com a flag.
Cabeçalho digitado errado. O formato é Authorization: Bearer — um Bearer faltando ou um espaço a mais vira um 401 que não explica nada. Não digite à mão; cole do Copy JSON.
Credencial expirada ou revogada. Token com validade definida uma hora expira — faz parte. Emita uma credencial nova e registre de novo.
Escopo trocado. Servidor adicionado com escopo local em um projeto não existe nos outros. Rode claude mcp list na pasta onde você esperava vê-lo.
Editou o .mcp.json com a sessão aberta. O arquivo é lido na inicialização da sessão; saia e abra o Claude Code de novo para a mudança valer. E se você recusou a aprovação do servidor lá atrás, claude mcp reset-project-choices faz a pergunta aparecer de novo.
Dependência faltando no servidor local. Servidor stdio executa um comando; sem o runtime instalado, ele morre na largada. Rode o comando à mão uma vez e leia o erro real. Se ele só demora — a primeira execução via npx ainda baixa o pacote —, aumente o limite de inicialização, que por padrão é de 30 segundos: MCP_TIMEOUT=60000 claude, com o valor em milissegundos.
Conecta, mas não é usado. Nas primeiras vezes, cite a fonte no pedido (“procure no meu workspace do AFFiNE...”). Depois que o padrão se firma, o Claude passa a escolher a ferramenta certa sozinho.
Padrões de segurança que valem manter
Somente leitura até precisar de mais. Conexão de base de conhecimento raramente precisa escrever; as credenciais do AFFiNE nascem somente leitura, e a escrita está em liberação gradual.
Uma credencial por cliente. Revogar o notebook não deve derrubar o desktop. Com validade definida, a rotação vira rotina de calendário.
Aprovação de ferramenta é decisão consciente. O Claude pergunta antes de usar ferramenta nova, e servidores compartilhados via project passam por aprovação no primeiro uso. Não desligue isso para nada que modifique dados. O checklist completo está no nosso guia de segurança MCP (em inglês).
Perguntas frequentes
Qual comando adiciona um servidor MCP ao Claude Code?
O claude mcp add: para servidores hospedados, com --transport http, a URL e o cabeçalho de autenticação; para locais, com o comando de inicialização. Confira com claude mcp list e, dentro da sessão, o /mcp mostra o estado na hora.
O Claude Desktop aceita servidores MCP?
Aceita. Servidores remotos entram por Configurações → Connectors como conector personalizado; locais vão no claude_desktop_config.json, em mcpServers, com reinício do aplicativo. Só lembre: a configuração dele é separada da do Claude Code.
Qual é a diferença entre os escopos local, project e user?
Local vale para você em um projeto; project grava um .mcp.json compartilhado no repositório para o time; user vale para você em todos os projetos da máquina. Credenciais ficam no lado pessoal; o que vai para o project é só a definição do servidor.
O Claude Code conecta a servidores MCP remotos?
Conecta. Servidores remotos por Streamable HTTP têm suporte oficial com --transport http e cabeçalho de autenticação. Endpoints hospedados, como o do workspace do AFFiNE, conectam sem nenhum processo local para manter.
Por que meu servidor não aparece na lista?
Verifique o estado com /mcp e depois os suspeitos de sempre: falta de --transport http em servidor remoto, cabeçalho Authorization mal formado, credencial expirada ou escopo trocado (local só existe no projeto onde foi adicionado). Esses quatro explicam quase tudo.
Usar MCP no Claude custa algo?
O suporte a MCP vem incluído no Claude Code e no Claude Desktop sem custo extra, e o protocolo é um padrão aberto. As condições variam por servidor; o embutido do AFFiNE, por exemplo, é gratuito no Cloud e em instâncias auto-hospedadas com IA ativada.
Preciso reiniciar o Claude Code depois de editar o .mcp.json?
Precisa: o arquivo é lido na inicialização da sessão, então mudança feita com a sessão aberta só vale depois de sair e abrir de novo. Se o servidor continuar sumido, rode /mcp e procure aviso de erro de sintaxe; e, caso você tenha recusado a aprovação daquele servidor no passado, claude mcp reset-project-choices reapresenta a pergunta.
E se o servidor exigir login OAuth em vez de token?
Adicione normalmente com claude mcp add --transport http, sem --header; o claude mcp list vai mostrar ! Needs authentication, que é o estado esperado. Dentro da sessão, rode /mcp, selecione o servidor e escolha Authenticate — o login se completa no navegador, e os tokens passam a ser renovados automaticamente.
Resumindo
Conectou o primeiro, o segundo sai no piloto automático — o procedimento é o mesmo para qualquer servidor. Comece pelo lugar onde você passa o dia procurando respostas: o seu workspace.