Servidores MCP

Conecte servidores MCP locais ou remotos para dar aos agentes acesso a mais ferramentas e informações.

Inspecione os servidores conectados

Digite /extensions e pressione c para abrir o navegador MCP somente leitura.

1. Selecione um servidor e pressione Enter para inspecionar suas ferramentas e seus prompts.
2. Selecione uma ferramenta para inspecionar seu esquema de entrada.
3. Selecione um prompt e pressione i para invocá-lo.
4. Pressione r para atualizar o estado da conexão ou e para mostrar o arquivo de configurações e a entrada do servidor exatos que devem ser editados.

Etapas 1 e 4. A lista expõe a identidade e a projeção atuais; atualize ou abra a entrada proprietária nas configurações a partir daqui.

O navegador distingue servidores conectados, declarados, com conexão perdida e indisponíveis, por isso é o local mais rápido para confirmar se uma configuração está ativa.

Etapas 2 e 3, de ponta a ponta. Esquemas de ferramentas e prompts são inspecionados no navegador; uma execução bem-sucedida prova que a ferramenta selecionada realmente funciona.

Configure servidores

Adicione um mapa mcpServers a ~/.clarvis/settings.json para servidores pessoais ou a .clarvis/settings.json para servidores específicos do projeto. Cada chave do mapa se torna o nome do servidor:

{
  "mcpServers": {
    "workspace-tools": {
      "type": "stdio",
      "command": "bun",
      "args": ["run", "tooling/local-mcp.ts"],
      "env": {
        "SERVICE_TOKEN": "${SERVICE_TOKEN}"
      },
      "resources": true
    },
    "remote-docs": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_TOKEN}"
      }
    }
  }
}

Substitua o comando e a URL do exemplo por servidores que você controla. Mantenha as credenciais em variáveis de ambiente: referências ${NAME} são resolvidas quando o Clarvis se conecta, portanto os segredos não precisam ser armazenados em settings.json.

Escolha o transporte

• stdio exige command. Ele também pode usar args, env, env_vars, cwd, shared e resources, mas não pode usar url, headers nem credenciais remotas.
• http e sse exigem uma URL http:// ou https:// bem-formada. Eles podem usar headers e resources, mas não podem usar command, args, env nem shared.
• Omitir type seleciona stdio.

Todos os transportes podem definir startup_timeout_sec, tool_timeout_sec, enabled, required, enabled_tools e disabled_tools. As listas de ferramentas permitidas e negadas não podem se sobrepor. Em stdio, env_vars encaminha somente as variáveis do host nomeadas, além do mapa env explícito. Um servidor remoto pode nomear bearer_token_env_var e mapear nomes de cabeçalhos HTTP para nomes de variáveis com env_http_headers, mantendo os valores das credenciais fora das configurações. expandVariables é verdadeiro por padrão; use falso somente quando outro formato de pacote já for responsável pela expansão de placeholders.

Defina shared: true somente quando um processo stdio de longa duração puder atender com segurança a execuções sobrepostas. Uma conexão compartilhada não oferece suporte a elicitação MCP, portanto não a use em um servidor que se autentica fazendo uma pergunta ao operador.

O suporte a recursos fica ativado por padrão. Quando um servidor anuncia recursos, o Clarvis adiciona <server>.list_resources e <server>.read_resource; defina resources: false para suprimi-los.

Autorize um servidor remoto

Quando um servidor HTTP ou SSE solicita OAuth, a CLI local interativa e o modo local --print abrem a página de autorização no navegador padrão. Um desafio pode chegar durante a conexão, durante a descoberta de ferramentas ou recursos, ou em uma solicitação posterior. O Clarvis aceita apenas endpoints e redirecionamentos OAuth HTTPS (além de HTTP em um host de loopback), verifica um valor de estado descartável, troca o callback com PKCE, valida o issuer quando o servidor de autorização o informa e repete uma vez a operação recusada.

Você pode continuar usando o Clarvis enquanto autoriza um servidor no navegador. Esse servidor fica indisponível na execução atual, e um aviso temporário explica o motivo sem entrar no histórico da conversa. Depois de autorizar, use /reconnect ou inicie uma nova execução.

Cabeçalhos declarados no servidor MCP ficam restritos às solicitações do recurso na origem configurada. Solicitações OAuth de descoberta, registro e token não os herdam, mesmo quando o recurso e o servidor de autorização compartilham uma origem, e as credenciais criadas pelo fluxo OAuth têm precedência.

Registros e tokens são armazenados fora das configurações em ~/.clarvis/state/mcp-oauth.json, isolados por workspace, proprietário e URL canônica do servidor. O Clarvis cria esse arquivo com permissões privadas nas plataformas que oferecem esse recurso e não coloca seu conteúdo em prompts, traces nem logs. Um kernel remoto ou sem interface não tem autoridade para abrir o navegador e falha explicitamente quando a autorização interativa é necessária; nesse host, configure uma credencial explícita baseada em cabeçalho.

Configurações OAuth avançadas ficam no objeto oauth do servidor. client_id usa um cliente público pré-registrado; uma client_metadata_url HTTPS ativa descoberta por Client ID Metadata Document; caso contrário, o Clarvis usa registro dinâmico quando o servidor oferece suporte. callback_url precisa ser HTTPS ou HTTP loopback, ter caminho diferente da raiz e não conter query nem fragmento. callback_port escolhe a porta do listener local. Um client id configurado tem precedência sobre a descoberta por metadados e o registro dinâmico.

Referencie um servidor a partir de um agente

Use <server>.<tool> para identificar uma ferramenta em configurações e hooks. Por exemplo, remote-docs.search identifica a ferramenta search do servidor remote-docs.

O modelo pode receber apenas o nome curto quando ele é válido e único. Se houver conflito com outra ferramenta ou um nome reservado, o Clarvis usa um nome qualificado. Isso não muda o nome completo usado nas configurações.

Servidores fornecidos por um plugin recebem o namespace do plugin:

quality-kit:checks.lint

Aqui, quality-kit é o plugin, checks é o servidor e lint é a ferramenta. Use o nome completo nas listas de ferramentas dos agentes e nos padrões match dos hooks.

A confiança no workspace se aplica

Um repositório não aprovado pode declarar servidores MCP, mas o Clarvis os retém em vez de iniciá-los ou se conectar a eles. O Clarvis pede o fingerprint protegido exato ao entrar no workspace; use /workspace-trust depois para revisar, aprovar ou revogar. A aprovação vale para o workspace, não para um servidor individual.

Veja também

• Hooks
• Plugins
• Referência de extensões