Adicione um servidor MCP ao Claude Code no terminal ou no VS Code. Siga os comandos exatos para servidores HTTP remotos e stdio locais, os três escopos, o login OAuth, um exemplo de imagem e vídeo com o PicassoIA e as correções para qualquer servidor que não conecta.
O Claude Code consegue ler seus arquivos e executar comandos de shell logo de cara, mas não enxerga seu rastreador de problemas, seu banco de dados nem seu gerador de imagens até que você os conecte. Essa conexão é um servidor MCP. MCP, abreviação de Model Context Protocol, é o padrão aberto que permite ao Claude Code chamar serviços externos como se fossem nativos. Adicionar um leva um único comando, e o mesmo servidor passa a aparecer no terminal e na extensão do VS Code.
Este artigo mostra os comandos exatos, os três escopos que definem quem tem acesso a um servidor, os detalhes de OAuth e token que costumam dar problema e um exemplo real usando a conexão de imagem e vídeo do PicassoIA. Os comandos e flags abaixo foram conferidos com a documentação atual do Claude Code em 6 de outubro de 2026, então correspondem ao que você verá no seu terminal.
💡 A versão curta: para um servidor hospedado, execute
claude mcp add --transport http <name> <url>. Para um servidor local, executeclaude mcp add --transport stdio <name> -- <command>. Depois digite/mcpdentro do Claude Code e confirme se o servidor mostra Connected.
Você precisa do próprio Claude Code. Para o caminho pelo VS Code, também é necessário o VS Code 1.94.0 ou posterior com a extensão do Claude Code. Verifique a versão da CLI com claude --version, porque alguns recursos dependem dela:
/mcp reconnect all exige a v2.1.284 ou posteriorUma instalação antiga é a primeira coisa a descartar quando um passo abaixo não faz nada. Você também precisa dos dados do servidor, e eles dependem de onde o servidor roda. Um servidor remoto fornece uma URL e um token ou um login pelo navegador. Um servidor local fornece um comando que o inicia, geralmente via npx, então o Node.js precisa estar instalado.
A flag --transport indica ao Claude Code como se comunicar com o servidor. Há três opções.
| Transporte | Onde o servidor roda | Use quando | Status |
|---|---|---|---|
http | URL remota | Um serviço hospedado fornece uma URL | A escolha atual para servidores hospedados |
sse | URL remota | O fornecedor só publica um endpoint /sse | Descontinuado |
stdio | Na sua máquina | O servidor é um programa que o Claude Code inicia | Padrão para ferramentas locais |
Uma regra rápida: uma URL que termina em /mcp significa HTTP, uma URL que termina em /sse significa o transporte SSE mais antigo (verifique se o fornecedor agora oferece uma URL HTTP), e um comando npx significa stdio.
A CLI é o caminho mais rápido, e tudo o que você faz aqui é também o que a extensão do VS Code lê. Abra um terminal na pasta do seu projeto ou em qualquer pasta, se pretende usar o escopo de usuário descrito mais adiante.
O padrão é claude mcp add --transport http <name> <url>. Aqui está um servidor hospedado real:
claude mcp add --transport http notion https://mcp.notion.com/mcp
A palavra notion é o nome que você escolhe. Ela aparece nos nomes das ferramentas como mcp__notion__<tool>, então mantenha-a curta e em minúsculas. Quando o servidor pedir um token, passe-o como cabeçalho:
claude mcp add --transport http secure-api https://api.example.com/mcp \
--header "Authorization: Bearer your-token"
💡 Atenção:
claude mcp addsalva a configuração sem verificar suas credenciais. Um token de exemplo é aceito, e a falha só aparece depois, quando o servidor tenta se conectar.
Um servidor stdio é um programa na sua própria máquina que o Claude Code inicia e com o qual se comunica pela entrada e saída padrão. O padrão é claude mcp add [options] <name> -- <command> [args...]:
claude mcp add --transport stdio files -- npx -y @modelcontextprotocol/server-filesystem ~/projects
O traço duplo é obrigatório. Tudo o que vem depois dele vai para o servidor sem alterações, e todas as opções do Claude Code (--env, --scope, --transport) precisam vir antes do nome. Para passar uma variável de ambiente ao processo do servidor, use --env:
claude mcp add --transport stdio --env MY_SERVICE_TOKEN=paste-here myservice -- npx -y your-server-package
Substitua your-server-package pelo pacote que o fornecedor documenta. No Windows nativo (não no WSL), npx muitas vezes precisa de um wrapper para que o shell consiga iniciá-lo:
claude mcp add --transport stdio files -- cmd /c npx -y @modelcontextprotocol/server-filesystem C:\Users\you\projects
Três comandos cuidam do gerenciamento do dia a dia:
claude mcp list
claude mcp get files
claude mcp remove files
list mostra todos os servidores configurados, get mostra os detalhes de um servidor, e remove o exclui. Se você já tem a definição de um servidor em JSON, claude mcp add-json <name> '<json>' poupa você de traduzi-la para flags. Dentro de uma sessão do Claude Code, /mcp mostra o status em tempo real e cuida do login.
A extensão do Claude Code e a CLI compartilham uma única configuração MCP, então há dois caminhos e nenhum deles prende você a um só.
/mcp na caixa de chat./mcp de novo e confira se o servidor aparece como Connected.O passo 5 é importante. As mudanças valem para as conversas que você iniciar depois, então um chat já aberto não verá o novo servidor.
Abra o terminal integrado com Ctrl+` (ou Cmd+` no Mac) e execute o mesmo comando claude mcp add que você usaria em qualquer outro lugar. A caixa de diálogo e o comando do terminal salvam na mesma configuração. Aqui está o servidor remoto do GitHub com um token de acesso pessoal:
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
--header "Authorization: Bearer YOUR_GITHUB_PAT"
Um servidor com credenciais inválidas aparece como Failed em /mcp, enquanto um que funciona aparece como Connected.
💡 Dois arquivos de configuração, dois produtos: o VS Code tem suporte próprio a MCP, com um arquivo em
.vscode/mcp.json. Esse arquivo pertence ao chat integrado do VS Code e usa um formato diferente. O Claude Code mantém a própria configuração, então um servidor declarado apenas em.vscode/mcp.jsonnão aparecerá na lista/mcpdo Claude Code.
Você também pode ouvir falar de um servidor chamado ide. A extensão o executa automaticamente para abrir diffs e ler sua seleção, e ele fica oculto em /mcp porque não há nada para configurar.
O escopo define quem vê o servidor e onde ele é armazenado. Escolha-o com --scope (forma abreviada -s).
| Escopo | Carregado em | Compartilhado com a equipe | Armazenado em |
|---|---|---|---|
| local (padrão) | Somente no projeto atual | Não | ~/.claude.json |
| projeto | Somente no projeto atual | Sim, pelo repositório | .mcp.json na raiz do projeto |
| usuário | Todos os projetos da sua máquina | Não | ~/.claude.json |
claude mcp add --transport http stripe --scope local https://mcp.stripe.com
claude mcp add --transport http shared --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic
Minha regra prática: use o local para experimentos e para qualquer coisa que contenha um token pessoal, o projeto para ferramentas que a equipe inteira precisa e o usuário para o pequeno grupo de servidores que você quer em todos os repositórios.
Um servidor de escopo de projeto fica em um arquivo .mcp.json na raiz do repositório, que você versiona. Ele suporta expansão de variáveis de ambiente, então o arquivo nunca precisa conter um segredo:
{
"mcpServers": {
"api-server": {
"type": "http",
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": {
"Authorization": "Bearer ${API_TOKEN}"
}
}
}
}
${VAR} expande para a variável de ambiente, e ${VAR:-default} usa um valor padrão quando a variável não está definida. Cada integrante da equipe define API_TOKEN na própria máquina.
Os colegas veem um pedido de aprovação antes de o Claude Code usar um servidor de .mcp.json em uma sessão interativa. Para redefinir essas escolhas, execute claude mcp reset-project-choices. Execuções não interativas, como claude -p, carregam os servidores do projeto sem pedir confirmação, o que vale a pena lembrar para jobs de CI.
Um servidor pode se autenticar de três formas, e a certa depende do que o fornecedor oferece.
| Método | Melhor para | Como |
|---|---|---|
| Token no cabeçalho | Servidores que emitem um token pessoal | --header "Authorization: Bearer ..." |
| Variável de ambiente | Servidores stdio locais | --env NAME=value |
| OAuth | Servidores hospedados com login pelo navegador | /mcp, ou claude mcp login <name> |
Para OAuth, abra /mcp, selecione o servidor e siga o login no navegador. Pela linha de comando, claude mcp login <name> faz o mesmo, e claude mcp login <name> --no-browser mostra o que você precisa em uma máquina SSH ou sem interface gráfica. Para limpar as credenciais salvas, execute claude mcp logout <name>. Alguns servidores exigem credenciais pré-registradas, que você passa com --client-id, --client-secret e --callback-port ao adicionar o servidor.
Dois hábitos evitam a maioria dos vazamentos. Primeiro, nunca versione um token literal. Coloque ${VAR} em .mcp.json e mantenha o valor real no ambiente do seu shell. Segundo, mantenha os servidores que carregam um token pessoal no escopo local ou de usuário, onde o arquivo fica fora do repositório.
Um servidor concreto deixa tudo isso menos abstrato. O PicassoIA oferece uma conexão MCP que permite a um cliente de IA criar imagens e vídeos a partir de um chat. Ela oferece quatro modelos: PicassoIA Image para texto em imagem, PicassoIA Image Editor Pro para edições, PicassoIA Video para clipes a partir de texto ou de uma imagem, e Seedance 2.5 Lite para vídeo com áudio.
As ferramentas são construídas em torno de tarefas assíncronas. Uma chamada de geração retorna um ID de previsão assim que uma GPU aceita a tarefa, e o cliente então consulta get_generation até o status virar succeeded ou failed. Outras ferramentas incluem edit_image, list_generations, cancel_generation, list_models e get_account. Uma conta pode executar 5 previsões ao mesmo tempo, e esse limite é compartilhado entre todas as suas conexões MCP. O acesso ao MCP depende do seu plano, então confirme na página de preços do PicassoIA antes de depender dele.
claude mcp add --transport http picassoia YOUR_PICASSOIA_MCP_URL
/mcp e selecione picassoia. Se ele pedir login, siga o fluxo no navegador. Se a página de conexões fornecer um token, adicione --header "Authorization: Bearer YOUR_TOKEN" ao comando.Não estou mostrando uma URL aqui de propósito. O PicassoIA exibe a sua depois que você faz login, então use exatamente a URL da sua conta em vez de uma cópia de um artigo.
Como você nomeou o servidor picassoia, suas ferramentas aparecem como mcp__picassoia__<tool>. Experimente algo que use duas delas:
Use o PicassoIA para gerar uma fotografia 16:9 de uma mesa de madeira ao nascer do sol, com um notebook e uma xícara de café, e depois anime-a em um vídeo curto.
O Claude Code pede permissão antes de chamar uma ferramenta nova, então espere um aviso na primeira execução. Se você também quiser comparar como diferentes modelos de linguagem interpretam a mesma instrução, o PicassoIA lista Claude Sonnet 5 e Claude Fable 5 entre seus modelos de linguagem.
A maioria das falhas vem de uma lista curta de causas. Comece com /mcp para ler o status e depois use claude mcp get <name> para ver exatamente o que foi salvo.
| Sintoma | Causa provável | Correção |
|---|---|---|
| Servidor mostra Failed | URL errada ou token inválido | Confira com claude mcp get <name> e depois remova e adicione de novo com os valores certos |
| Servidor ausente no VS Code | A conversa começou antes de você adicioná-lo | Inicie uma nova conversa |
| Servidor stdio cai logo de início no Windows | npx precisa de um wrapper de shell | Use -- cmd /c npx ... |
| Servidor conectado, mas sem ferramentas | Login OAuth não concluído | /mcp e depois autentique, ou claude mcp login <name> |
| Servidor de projeto nunca carrega | A aprovação foi recusada | Execute claude mcp reset-project-choices e aprove de novo |
| Funciona para você, mas não para um colega | Foi salvo no escopo local | Adicione de novo com --scope project |
| Servidor caiu no meio da sessão | Conexão perdida | Execute /mcp reconnect all (v2.1.284 ou posterior) |
Três configurações lidam com servidores lentos. MCP_TIMEOUT define o tempo limite de inicialização do servidor em milissegundos, o que ajuda quando o primeiro download de npx está lento:
export MCP_TIMEOUT=10000
No PowerShell do Windows, o mesmo ajuste é feito com $env:MCP_TIMEOUT = "10000". MAX_MCP_OUTPUT_TOKENS aumenta o limite da saída das ferramentas. O padrão é 25.000 tokens, e o Claude Code avisa você em 10.000. Por fim, um timeout por servidor em .mcp.json (também em milissegundos) dá mais tempo às ferramentas lentas, o que combina com geradores de imagem e vídeo:
{
"mcpServers": {
"slow-tool": {
"type": "http",
"url": "https://example.com/mcp",
"timeout": 600000
}
}
}
Agora você tem o ciclo completo: escolher um transporte, adicionar o servidor, escolher um escopo, fazer login com segurança e corrigir quando algo der errado. A forma mais rápida de sentir o retorno é conectar um servidor que produza algo que você possa ver.
Faça login no PicassoIA, conecte-o ao Claude Code e peça uma fotografia. Gere-a com PicassoIA Image, refine-a com PicassoIA Image Editor Pro e depois dê vida a ela com PicassoIA Video ou Seedance 2.5 Lite. Veja todos os modelos em picassoia.com/en/all-models e comece com um prompt seu.
Escolha seu idioma
