Todo resultado do claude mcp add depende de duas escolhas: o escopo e o transporte. Veja onde os escopos local, de projeto e de usuário guardam seus dados, qual prevalece quando os nomes colidem, como registrar servidores HTTP com cabeçalhos ou OAuth e como iniciar servidores stdio no Windows.
Você cola a URL de um servidor no claude mcp add, aperta Enter, e o servidor aparece em um projeto mas some no seguinte. Ou ele cai no checkout de um colega e pede uma aprovação que ninguém esperava. Quase todo resultado confuso desse comando vem de duas decisões: qual escopo você escolheu e qual transporte você usou. Este artigo percorre o comando flag por flag, mostra onde cada escopo guarda seus dados, explica como os escopos de usuário e de projeto interagem e traz exemplos funcionais para servidores HTTP e stdio, incluindo a peculiaridade do Windows que pega muita gente.
claude mcp add registra um servidor do Model Context Protocol no Claude Code para que o assistente possa chamar suas ferramentas, ler seus recursos e executar seus prompts. O comando não instala nada por conta própria. Ele grava uma pequena entrada de configuração, e o Claude Code lê essa entrada na próxima vez que uma sessão começar ou quando você reconectar pelo menu /mcp.
Três decisões moldam cada chamada:
http, sse ou stdio).local, project ou user).claude mcp get, claude mcp remove e no menu /mcp.Duas formas cobrem quase tudo o que você vai executar:
# Remote server reached over a URL
claude mcp add [options] <name> <url>
# Local process started by Claude Code
claude mcp add [options] <name> -- <command> [args...]
Coloque --transport, --scope e --env antes do nome do servidor. Para processos locais, o duplo hífen diz ao analisador que tudo o que vem depois pertence ao servidor e não ao Claude Code.
💡 Dica: passe
--transportsempre, mesmo quando um padrão funcionaria. Uma flag explícita faz o comando ficar igual no histórico do shell, nos arquivos README e no chat da equipe, qualquer que seja a versão que cada pessoa usa.
O Claude Code guarda cada servidor em um de três lugares, e a flag --scope (forma curta -s) escolhe o lugar. Se você não usar a flag, obtém local.
| Escopo | Carrega em | Compartilhado com a equipe | Armazenado em |
|---|---|---|---|
local (padrão) | Somente o projeto atual | Não | ~/.claude.json, no caminho do projeto |
project | Somente o projeto atual | Sim, pelo controle de versão | .mcp.json na raiz do projeto |
user | Todos os projetos da sua máquina | Não | ~/.claude.json |
A palavra local confunde as pessoas porque soa como "na minha máquina", e o escopo de usuário também fica na sua máquina. A diferença é o alcance. Local é privado e limitado a um projeto, enquanto usuário é privado e acompanha você em todos os repositórios.
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
Use o escopo local para experimentos, para servidores ligados a um único repositório e para qualquer coisa que carregue uma credencial pessoal. Nada é gravado no repositório, então não há risco de commitar um token por acidente. Também é o escopo em que você cai quando esquece a flag, e por isso um servidor adicionado com pressa parece sumir quando você abre outra pasta.
claude mcp add --scope project --transport http sentry https://mcp.sentry.dev/mcp
Isso cria ou atualiza .mcp.json na raiz do projeto. Faça o commit e todo colega recebe a mesma lista de servidores após o pull. Como um arquivo em um repositório pode iniciar processos na sua máquina, o Claude Code pede que cada pessoa aprove os servidores de projeto na primeira vez em que aparecem. Se alguém recusou por engano, claude mcp reset-project-choices limpa as respostas anteriores para que o pedido volte a aparecer.
claude mcp add --scope user --transport http notion https://mcp.notion.com/mcp
O escopo de usuário serve para ferramentas pessoais que você quer em todos os repositórios: um app de anotações, um servidor de busca em documentação, um auxiliar de navegador. A entrada fica em ~/.claude.json, acompanha sua conta naquela máquina e nunca toca em um repositório.
A escolha entre escopo de usuário e de projeto se resume a uma pergunta: quem mais precisa deste servidor? Se a resposta é "todo mundo que clona este repo", use projeto. Se a resposta é "só eu, mas em todo repo", use usuário. Se a resposta é "só eu, só aqui", fique com o local.
| Situação | Melhor escopo | Por quê |
|---|---|---|
| Todo colega precisa do mesmo servidor | project | Um .mcp.json commitado substitui uma página de wiki com passos de configuração |
| Um auxiliar pessoal para todos os seus repositórios | user | Adicione uma vez e ele acompanha você em todo lugar |
| Testar um servidor por uma tarde | local | Nada vaza para o repositório, e remover é trivial |
| Apontar um servidor da equipe para uma URL de staging | local | Ele sobrepõe a definição compartilhada apenas na sua máquina |
| Um servidor que precisa do seu próprio token | local ou user | Credenciais pessoais nunca devem estar em um arquivo commitado |
Quando o mesmo nome de servidor existe em mais de um escopo, o Claude Code usa a definição mais específica: local vence projeto, e projeto vence usuário. Essa ordem permite sobrepor uma entrada compartilhada na sua própria máquina sem editar um arquivo que todos usam.
Suponha que o .mcp.json da equipe defina um servidor chamado docs que aponta para produção. Você pode executar isto no seu próprio checkout:
claude mcp add --transport http docs https://staging.example.com/mcp
A entrada local vence, então sua sessão conversa com o staging enquanto seus colegas continuam conversando com a produção. Apague a entrada local e você volta para a compartilhada.
Uma entrada de escopo de projeto é JSON simples, o que significa que você também pode escrevê-la à mão:
{
"mcpServers": {
"docs": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer ${DOCS_TOKEN}"
}
}
}
}
O Claude Code expande ${VAR} e ${VAR:-default} dentro de command, args, url, headers e env. Esse é o padrão seguro para arquivos compartilhados: commite a estrutura e deixe cada pessoa fornecer o próprio segredo por meio de uma variável de ambiente. Um token real colado em .mcp.json acaba no histórico do git, e rotacionar o token é a única correção confiável.
HTTP é o transporte recomendado para servidores remotos: sem processo local, sem runtime para instalar, e o fornecedor cuida das atualizações. A maioria dos servidores MCP hospedados publica uma URL terminada em /mcp, e é esse endereço que você entrega ao comando.
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
| Transporte | Melhor para | Status |
|---|---|---|
http | Servidores remotos acessados por uma URL | Recomendado |
sse | Servidores remotos mais antigos em um endpoint /sse | Obsoleto, use http quando o fornecedor oferecer |
stdio | Processos locais iniciados na sua máquina | Totalmente suportado |
Se a documentação de um fornecedor ainda mostrar um endereço /sse, verifique se o mesmo serviço oferece um endpoint /mcp antes de registrar o antigo. Servidores no transporte obsoleto continuam funcionando por enquanto, mas configurações novas não devem começar por ele.
Servidores que aceitam uma credencial estática a leem de um cabeçalho da requisição. Passe-a com --header (forma curta -H), e repita a flag quando precisar de mais de uma:
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
--header "Authorization: Bearer YOUR_TOKEN"
claude mcp add --transport http api https://example.com/mcp \
--header "Authorization: Bearer YOUR_TOKEN" \
--header "X-Team: platform"
💡 Cuidado com o shell: se você digitar
$GITHUB_TOKENentre aspas duplas, o shell expande a variável antes que o Claude Code veja o comando, então a entrada guardada contém o token real. Para qualquer coisa compartilhada, escreva a forma${VAR}em.mcp.json.
Muitos servidores hospedados dispensam tokens estáticos e usam OAuth. Adicione o servidor sem cabeçalhos, inicie o Claude Code e execute /mcp. Escolha o servidor na lista e siga o login pelo navegador. O Claude Code guarda as credenciais resultantes e as renova para você, então não há nada para colar em um arquivo de configuração e nada para commitar por engano.
Com stdio, o Claude Code inicia o servidor como um processo filho e se comunica com ele pela entrada e saída padrão. Escolha esse transporte para ferramentas que precisam rodar na sua máquina: um auxiliar de banco de dados local, uma ferramenta de sistema de arquivos ou um script que você mesmo escreveu. As variáveis de ambiente acompanham a flag --env (forma curta -e).
claude mcp add --transport stdio --env API_TOKEN=YOUR_TOKEN myserver \
-- npx -y my-mcp-server
Tudo antes do -- é para o Claude Code. Tudo depois dele é o comando exato que inicia o seu servidor, com argumentos. Esquecer o separador é o erro mais comum com stdio:
# Wrong: --port is parsed as a Claude Code option
claude mcp add --transport stdio myserver npx server --port 8080
# Right: the server command sits after the double dash
claude mcp add --transport stdio myserver -- npx server --port 8080
No Windows nativo (não no WSL), npx é um wrapper de lote e não um executável de verdade, então o Claude Code não consegue iniciá-lo diretamente. Envolva o comando em cmd /c:
claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package
Sem o wrapper, normalmente você vê um erro "Connection closed" em /mcp, que parece um bug do servidor mas é só uma falha de inicialização. A mesma correção vale quando você escreve a entrada à mão: defina "command": "cmd" e comece args com "/c", depois "npx".
Registrar um servidor é só metade do trabalho. Três comandos cuidam do resto da vida dele:
claude mcp list # every server and its connection status
claude mcp get docs # details for one server
claude mcp remove docs # delete it
Dentro de uma sessão, /mcp mostra o mesmo status em tempo real e também é onde você faz login em servidores OAuth ou reconecta um que caiu.
Execute claude mcp list primeiro sempre que algo parecer errado. Ele mostra o que o Claude Code de fato conhece, de todos os escopos, para você ver na hora se o servidor está ausente ou apenas falhando. Use claude mcp get <name> para ver de onde veio uma entrada. Se o mesmo nome existir em mais de um escopo, passe --scope para claude mcp remove para apagar a cópia certa.
Quando um fornecedor entrega um trecho JSON, dispense as flags e passe-o direto ao comando:
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'
add-json aceita a mesma flag --scope, então você pode colocar um trecho no escopo de usuário ou de projeto em um único passo. Se você já montou um conjunto de servidores no Claude Desktop, claude mcp add-from-claude-desktop os importa de forma interativa no macOS e no WSL.
A maioria das falhas cai em uma lista curta. Identifique primeiro o sintoma e só então comece a editar arquivos.
| Sintoma | Causa provável | Correção |
|---|---|---|
| Servidor ausente em outra pasta | Adicionado no escopo local | Adicione de novo com --scope user |
| Colegas não veem o servidor | Adicionado no escopo local ou de usuário | Adicione de novo com --scope project e commite .mcp.json |
| "Connection closed" no Windows | npx iniciado sem wrapper | Use -- cmd /c npx ... |
| Flags do servidor rejeitadas | Nenhum -- antes do comando | Coloque o duplo hífen depois do nome |
| Servidor de projeto nunca carrega | Aprovação recusada antes | Execute claude mcp reset-project-choices |
| Servidor lento expira na inicialização | Limite de inicialização curto demais | Inicie o Claude Code com MCP_TIMEOUT=30000 |
| Saída da ferramenta é cortada | Limite de tokens de saída atingido | Defina MAX_MCP_OUTPUT_TOKENS maior |
| Token em arquivo commitado | Segredo literal em .mcp.json | Gire o token e depois use ${VAR} |
Quando a tabela não resolver, faça as mesmas quatro verificações, em ordem:
claude mcp list para confirmar que o servidor está registrado e ver o status dele.claude mcp get <name> para ler o comando ou a URL exata que o Claude Code está usando./mcp dentro de uma sessão para ver o estado da conexão em tempo real e reconectar.Quando um servidor não conecta: para um servidor remoto, abra a URL no navegador ou chame-a com curl. Um 401 ou 403 significa que seu cabeçalho ou seu login está errado, um 404 geralmente indica que o caminho está errado (/mcp em vez de /sse), e um timeout aponta para a rede. Para um servidor stdio, o comando exato que você registrou precisa rodar sozinho com as mesmas variáveis de ambiente definidas.
Depois que os escopos estiverem organizados, o MCP se torna uma forma de dar ao Claude capacidades reais, e imagens são um bom exemplo. O PicassoIA expõe seus modelos de geração por uma API para desenvolvedores em https://api.picassoia.com/v1 e por conexões MCP. Os quatro modelos dessa superfície são PicassoIA Image, PicassoIA Image Editor Pro e dois modelos de vídeo. Os trabalhos são assíncronos: o Claude envia uma predição, consulta o resultado e depois lê o resultado final. A plataforma permite 5 predições simultâneas por conta, compartilhadas entre todas as conexões que você tem abertas, então um lote de requisições de uma mesma sessão entra em fila em vez de rodar tudo de uma vez.
💡 Dica de escopo: a página de preços lista as conexões MCP nos planos Pro+, Elite e Infinite, então confirme seu plano antes de configurar. Registre a conexão no escopo de usuário se quiser geração de imagens em todos os repositórios, ou no escopo local se só um projeto precisar dela. Copie a URL de conexão da sua conta do PicassoIA em vez de adivinhar um endereço.
Você não precisa de um terminal para pedir ajuda com um comando claude mcp add que falha. Claude Sonnet 5 roda no PicassoIA e lida bem com esse tipo de depuração:
/mcp ou do terminal.claude mcp list.Para um raciocínio mais pesado sobre um grande .mcp.json, o Claude Opus 4.7 está disponível na mesma plataforma, e o Claude 4.5 Haiku responde a perguntas rápidas de sintaxe com velocidade.
Ler sobre escopos é útil, mas o ganho real vem de ter o Claude trabalhando com visuais enquanto você programa. Abra o PicassoIA, escolha um modelo como o PicassoIA Image e gere algumas imagens a partir dos seus próprios prompts. Experimente um gráfico de cabeçalho para o próximo README, um mockup de produto ou uma cena em estilo fotográfico para um post de blog. Quando gostar dos resultados, conecte essa mesma capacidade ao Claude Code por MCP e deixe o assistente produzir imagens dentro do seu fluxo de trabalho. Experimente à vontade, compare modelos lado a lado e guarde os prompts que funcionam.
Escolha seu idioma
