O Protocolo de Contexto de Modelo (MCP) é um protocolo aberto que permite aos LLMs acessar ferramentas externas e fontes de dados. Para mais detalhes sobre MCP, consulte a documentação MCP.

Use servidores MCP de terceiros por sua própria conta e risco. Certifique-se de confiar nos servidores MCP, e seja especialmente cuidadoso ao usar servidores MCP que se comunicam com a internet, pois estes podem expô-lo ao risco de injeção de prompt.

​
Configurar servidores MCP

1

Adicionar um Servidor MCP stdio

# Sintaxe básica
claude mcp add <nome> <comando> [args...]

# Exemplo: Adicionando um servidor local
claude mcp add my-server -e API_KEY=123 -- /path/to/server arg1 arg2
2

Adicionar um Servidor MCP SSE

# Sintaxe básica
claude mcp add --transport sse <nome> <url>

# Exemplo: Adicionando um servidor SSE
claude mcp add --transport sse sse-server https://example.com/sse-endpoint

# Exemplo: Adicionando um servidor SSE com cabeçalhos personalizados
claude mcp add --transport sse api-server https://api.example.com/mcp -e X-API-Key=your-key
3

Adicionar um Servidor MCP HTTP

# Sintaxe básica
claude mcp add --transport http <nome> <url>

# Exemplo: Adicionando um servidor HTTP transmissível
claude mcp add --transport http http-server https://example.com/mcp

# Exemplo: Adicionando um servidor HTTP com cabeçalho de autenticação
claude mcp add --transport http secure-server https://api.example.com/mcp -e Authorization="Bearer your-token"
4

Gerenciar seus servidores MCP

# Listar todos os servidores configurados
claude mcp list

# Obter detalhes para um servidor específico
claude mcp get my-server

# Remover um servidor
claude mcp remove my-server

Dicas:

  • Use a flag -s ou --scope para especificar onde a configuração é armazenada:
    • local (padrão): Disponível apenas para você no projeto atual (era chamado de project em versões mais antigas)
    • project: Compartilhado com todos no projeto via arquivo .mcp.json
    • user: Disponível para você em todos os projetos (era chamado de global em versões mais antigas)
  • Defina variáveis de ambiente com flags -e ou --env (ex., -e KEY=value)
  • Configure o timeout de inicialização do servidor MCP usando a variável de ambiente MCP_TIMEOUT (ex., MCP_TIMEOUT=10000 claude define um timeout de 10 segundos)
  • Verifique o status do servidor MCP a qualquer momento usando o comando /mcp dentro do Claude Code
  • MCP segue uma arquitetura cliente-servidor onde Claude Code (o cliente) pode se conectar a múltiplos servidores especializados
  • Claude Code suporta SSE (Server-Sent Events) e servidores HTTP transmissíveis para comunicação em tempo real
  • Use /mcp para autenticar com servidores remotos que requerem autenticação OAuth 2.0

​
Entendendo escopos de servidor MCP

Servidores MCP podem ser configurados em três níveis de escopo diferentes, cada um servindo propósitos distintos para gerenciar acessibilidade e compartilhamento de servidores. Entender esses escopos ajuda você a determinar a melhor maneira de configurar servidores para suas necessidades específicas.

​
Hierarquia de escopo e precedência

Configurações de servidor MCP seguem uma hierarquia de precedência clara. Quando servidores com o mesmo nome existem em múltiplos escopos, o sistema resolve conflitos priorizando servidores de escopo local primeiro, seguidos por servidores de escopo de projeto, e finalmente servidores de escopo de usuário. Este design garante que configurações pessoais possam sobrescrever as compartilhadas quando necessário.

​
Escopo local

Servidores de escopo local representam o nível de configuração padrão e são armazenados nas suas configurações de usuário específicas do projeto. Esses servidores permanecem privados para você e são acessíveis apenas quando trabalhando dentro do diretório do projeto atual. Este escopo é ideal para servidores de desenvolvimento pessoal, configurações experimentais, ou servidores contendo credenciais sensíveis que não devem ser compartilhadas.

# Adicionar um servidor de escopo local (padrão)
claude mcp add my-private-server /path/to/server

# Especificar explicitamente escopo local
claude mcp add my-private-server -s local /path/to/server

​
Escopo de projeto

Servidores de escopo de projeto permitem colaboração em equipe armazenando configurações em um arquivo .mcp.json na raiz do seu projeto. Este arquivo é projetado para ser incluído no controle de versão, garantindo que todos os membros da equipe tenham acesso às mesmas ferramentas e serviços MCP. Quando você adiciona um servidor de escopo de projeto, Claude Code automaticamente cria ou atualiza este arquivo com a estrutura de configuração apropriada.

# Adicionar um servidor de escopo de projeto
claude mcp add shared-server -s project /path/to/server

O arquivo .mcp.json resultante segue um formato padronizado:

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

Por razões de segurança, Claude Code solicita aprovação antes de usar servidores de escopo de projeto de arquivos .mcp.json. Se você precisar redefinir essas escolhas de aprovação, use o comando claude mcp reset-project-choices.

​
Escopo de usuário

Servidores de escopo de usuário fornecem acessibilidade entre projetos, tornando-os disponíveis em todos os projetos na sua máquina enquanto permanecem privados para sua conta de usuário. Este escopo funciona bem para servidores de utilitários pessoais, ferramentas de desenvolvimento, ou serviços que você usa frequentemente em diferentes projetos.

# Adicionar um servidor de usuário
claude mcp add my-user-server -s user /path/to/server

​
Escolhendo o escopo certo

Selecione seu escopo baseado em:

  • Escopo local: Servidores pessoais, configurações experimentais, ou credenciais sensíveis específicas para um projeto
  • Escopo de projeto: Servidores compartilhados pela equipe, ferramentas específicas do projeto, ou serviços necessários para colaboração
  • Escopo de usuário: Utilitários pessoais necessários em múltiplos projetos, ferramentas de desenvolvimento, ou serviços usados frequentemente

​
Autenticar com servidores MCP remotos

Muitos servidores MCP remotos requerem autenticação. Claude Code suporta fluxo de autenticação OAuth 2.0 para conexão segura com esses servidores.

1

Adicionar um servidor remoto que requer autenticação

# Adicionar um servidor SSE ou HTTP que requer OAuth
claude mcp add --transport sse github-server https://api.github.com/mcp
2

Autenticar usando o comando /mcp

Dentro do Claude Code, use o comando /mcp para gerenciar autenticação:

> /mcp

Isso abre um menu interativo onde você pode:

  • Ver status de conexão para todos os servidores
  • Autenticar com servidores que requerem OAuth
  • Limpar autenticação existente
  • Ver capacidades do servidor
3

Completar o fluxo OAuth

Quando você seleciona “Autenticar” para um servidor:

  1. Seu navegador abre automaticamente para o provedor OAuth
  2. Complete a autenticação no seu navegador
  3. Claude Code recebe e armazena com segurança o token de acesso
  4. A conexão do servidor torna-se ativa

Dicas:

  • Tokens de autenticação são armazenados com segurança e atualizados automaticamente
  • Use “Limpar autenticação” no menu /mcp para revogar acesso
  • Se seu navegador não abrir automaticamente, copie a URL fornecida
  • Autenticação OAuth funciona com transportes SSE e HTTP

​
Conectar a um servidor MCP Postgres

Suponha que você queira dar ao Claude acesso somente leitura a um banco de dados PostgreSQL para consultas e inspeção de esquema.

1

Adicionar o servidor MCP Postgres

claude mcp add postgres-server /path/to/postgres-mcp-server --connection-string "postgresql://user:pass@localhost:5432/mydb"
2

Consultar seu banco de dados com Claude

> descreva o esquema da nossa tabela de usuários

> quais são os pedidos mais recentes no sistema?

> mostre-me a relação entre clientes e faturas

Dicas:

  • O servidor MCP Postgres fornece acesso somente leitura para segurança
  • Claude pode ajudá-lo a explorar estrutura de banco de dados e executar consultas analíticas
  • Você pode usar isso para entender rapidamente esquemas de banco de dados em projetos desconhecidos
  • Certifique-se de que sua string de conexão use credenciais apropriadas com permissões mínimas necessárias

​
Adicionar servidores MCP de configuração JSON

Suponha que você tenha uma configuração JSON para um único servidor MCP que você quer adicionar ao Claude Code.

1

Adicionar um servidor MCP do JSON

# Sintaxe básica
claude mcp add-json <nome> '<json>'

# Exemplo: Adicionando um servidor stdio com configuração JSON
claude mcp add-json weather-api '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'
2

Verificar se o servidor foi adicionado

claude mcp get weather-api

Dicas:

  • Certifique-se de que o JSON esteja adequadamente escapado no seu shell
  • O JSON deve estar em conformidade com o esquema de configuração do servidor MCP
  • Você pode usar -s global para adicionar o servidor à sua configuração global em vez da específica do projeto

​
Importar servidores MCP do Claude Desktop

Suponha que você já tenha configurado servidores MCP no Claude Desktop e queira usar os mesmos servidores no Claude Code sem reconfigurá-los manualmente.

1

Importar servidores do Claude Desktop

# Sintaxe básica 
claude mcp add-from-claude-desktop
2

Selecionar quais servidores importar

Após executar o comando, você verá um diálogo interativo que permite selecionar quais servidores você quer importar.

3

Verificar se os servidores foram importados

claude mcp list

Dicas:

  • Este recurso funciona apenas no macOS e Windows Subsystem for Linux (WSL)
  • Ele lê o arquivo de configuração do Claude Desktop de sua localização padrão nessas plataformas
  • Use a flag -s global para adicionar servidores à sua configuração global
  • Servidores importados terão os mesmos nomes que no Claude Desktop
  • Se servidores com os mesmos nomes já existirem, eles receberão um sufixo numérico (ex., server_1)

​
Usar Claude Code como um servidor MCP

Suponha que você queira usar o próprio Claude Code como um servidor MCP ao qual outras aplicações podem se conectar, fornecendo-lhes as ferramentas e capacidades do Claude.

1

Iniciar Claude como um servidor MCP

# Sintaxe básica
claude mcp serve
2

Conectar de outra aplicação

Você pode se conectar ao servidor MCP Claude Code de qualquer cliente MCP, como Claude Desktop. Se você estiver usando Claude Desktop, pode adicionar o servidor MCP Claude Code usando esta configuração:

{
  "command": "claude",
  "args": ["mcp", "serve"],
  "env": {}
}

Dicas:

  • O servidor fornece acesso às ferramentas do Claude como View, Edit, LS, etc.
  • No Claude Desktop, tente pedir ao Claude para ler arquivos em um diretório, fazer edições, e mais.
  • Note que este servidor MCP está simplesmente expondo as ferramentas do Claude Code ao seu cliente MCP, então seu próprio cliente é responsável por implementar confirmação do usuário para chamadas de ferramentas individuais.

​
Usar recursos MCP

Servidores MCP podem expor recursos que você pode referenciar usando menções @, similar a como você referencia arquivos.

​
Referenciar recursos MCP

1

Listar recursos disponíveis

Digite @ no seu prompt para ver recursos disponíveis de todos os servidores MCP conectados. Recursos aparecem junto com arquivos no menu de autocompletar.

2

Referenciar um recurso específico

Use o formato @servidor:protocolo://recurso/caminho para referenciar um recurso:

> Você pode analisar @github:issue://123 e sugerir uma correção?

> Por favor, revise a documentação da API em @docs:file://api/authentication
3

Múltiplas referências de recursos

Você pode referenciar múltiplos recursos em um único prompt:

> Compare @postgres:schema://users com @docs:file://database/user-model

Dicas:

  • Recursos são automaticamente buscados e incluídos como anexos quando referenciados
  • Caminhos de recursos são pesquisáveis de forma difusa no autocompletar de menção @
  • Claude Code automaticamente fornece ferramentas para listar e ler recursos MCP quando servidores os suportam
  • Recursos podem conter qualquer tipo de conteúdo que o servidor MCP forneça (texto, JSON, dados estruturados, etc.)

​
Usar prompts MCP como comandos slash

Servidores MCP podem expor prompts que se tornam disponíveis como comandos slash no Claude Code.

​
Executar prompts MCP

1

Descobrir prompts disponíveis

Digite / para ver todos os comandos disponíveis, incluindo aqueles de servidores MCP. Prompts MCP aparecem com o formato /mcp__nomeservidor__nomeprompt.

2

Executar um prompt sem argumentos

> /mcp__github__list_prs
3

Executar um prompt com argumentos

Muitos prompts aceitam argumentos. Passe-os separados por espaço após o comando:

> /mcp__github__pr_review 456

> /mcp__jira__create_issue "Bug no fluxo de login" high

Dicas:

  • Prompts MCP são descobertos dinamicamente de servidores conectados
  • Argumentos são analisados baseados nos parâmetros definidos do prompt
  • Resultados de prompt são injetados diretamente na conversa
  • Nomes de servidor e prompt são normalizados (espaços tornam-se sublinhados)