Docs/ Assistente IA/ Servidor MCP

Servidor MCP

Conecte Claude Desktop, Claude Code, Cursor ou qualquer cliente compatível com MCP ao sh0 e gerencie seus deploys por linguagem natural.

O que é MCP

O Model Context Protocol (MCP) é um padrão aberto para conectar assistentes IA a ferramentas e fontes de dados externas. Em vez de copiar e colar saída do terminal em uma janela de chat, o MCP permite que seu assistente IA interaja diretamente com sh0 — listando apps, lendo logs, acionando deploys e diagnosticando problemas.

sh0 inclui um servidor MCP integrado exposto em POST /mcp usando o transporte Streamable HTTP. Qualquer cliente que suporte MCP pode se conectar com nada mais que uma URL e uma chave API.

Conectando Claude Desktop

Adicione o seguinte ao seu arquivo de configuração do Claude Desktop em ~/.claude/claude_desktop_config.json:

~/.claude/claude_desktop_config.json

{
  "mcpServers": {
    "sh0": {
      "type": "url",
      "url": "https://your-server.com/mcp",
      "headers": {
        "Authorization": "Bearer sh0_your_api_key"
      }
    }
  }
}

Substitua your-server.com pelo endereço do seu servidor sh0 e sh0_your_api_key por uma chave API válida. Reinicie o Claude Desktop para carregar a nova configuração.

Conectando Claude Code

Para o Claude Code (o CLI), adicione a mesma configuração ao ~/.claude.json na chave mcpServers:

~/.claude.json

{
  "mcpServers": {
    "sh0": {
      "type": "url",
      "url": "https://your-server.com/mcp",
      "headers": {
        "Authorization": "Bearer sh0_your_api_key"
      }
    }
  }
}

Uma vez configurado, o Claude Code descobrirá e usará automaticamente as ferramentas sh0 quando relevante para seus prompts.

Conectando Cursor

No Cursor, abra Settings → MCP e adicione um novo servidor com a mesma configuração JSON:

Cursor MCP Settings

{
  "mcpServers": {
    "sh0": {
      "type": "url",
      "url": "https://your-server.com/mcp",
      "headers": {
        "Authorization": "Bearer sh0_your_api_key"
      }
    }
  }
}

A configuração é idêntica nos três clientes. Qualquer ferramenta compatível com MCP que suporte o transporte Streamable HTTP funcionará com a mesma URL e credenciais.

Tip

Você pode testar sua conexão MCP com:

curl -X POST https://your-server/mcp -H 'Authorization: Bearer sh0_xxx' -H 'Content-Type: application/json' -d 'undefined,"clientInfo":undefined}}'

Escopos de Chave API

As chaves API controlam quais ferramentas o assistente IA pode acessar. Cada chave recebe um escopo que determina suas permissões:

Escopo	Ferramentas	Descrição
`read`	37 ferramentas	Listar e inspecionar apps, serviços, domínios, logs e métricas. Nenhuma modificação permitida.
`standard`	Read + escrita	Tudo em read, mais criar apps, acionar deploys, atualizar variáveis de ambiente e gerenciar domínios.
`admin`	Todas as 103 ferramentas	Acesso total incluindo configurações do servidor, gerenciamento de usuários, operações de backup e ações destrutivas.

Para criar uma chave API, navegue até Settings → API Keys no dashboard. Escolha o escopo apropriado com base no que você precisa que a IA faça. Para a maioria dos fluxos de desenvolvimento, standard fornece o equilíbrio certo entre capacidade e segurança.

Warning

Use o escopo admin apenas quando a IA precisar realizar operações a nível de servidor. Para o dia a dia de desenvolvimento, standard é recomendado.

Auto-Descoberta

Todas as 103 ferramentas são automaticamente descobertas pelos clientes MCP. Nenhum registro manual de ferramenta é necessário. Quando um cliente se conecta, ele chama o método tools/list, e sh0 responde com o catálogo completo de ferramentas — nomes, descrições e definições de parâmetros em JSON Schema.

A lista de ferramentas é filtrada com base no escopo da chave API. Uma chave com escopo read verá apenas as 37 ferramentas somente leitura, enquanto uma chave admin vê todas as 103.

Gerenciamento de Sessão

O servidor MCP usa sessões para manter estado entre múltiplas requisições dentro de uma conversa. Cada sessão é identificada por um UUID v4 retornado no header de resposta Mcp-Session-Id após a chamada initialize.

Os clientes devem incluir este header em todas as requisições subsequentes. Detalhes da sessão:

Formato do ID: UUID v4 (ex.: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d)
TTL: 1 hora de inatividade
Evicção: Lazy — sessões expiradas são limpas quando novas sessões são criadas
Escopo: Cada sessão herda o escopo da chave API usada durante a inicialização

Solução de Problemas

Problemas comuns ao conectar ao servidor MCP:

Conexão recusada

Verifique que o servidor sh0 está rodando e a porta está acessível. Se conectando de fora da rede local, certifique-se de que seu firewall permite tráfego de entrada na porta da API sh0 (padrão 9000).

HTTPS necessário

Clientes MCP tipicamente requerem HTTPS para conexões remotas. Se você está acessando sh0 pela internet, certifique-se de que seu servidor tem um certificado SSL válido. Conexões locais para localhost ou 127.0.0.1 podem funcionar via HTTP simples.

Ferramentas não aparecem

Se a conexão funciona mas nenhuma ferramenta aparece, o escopo da chave API pode ser muito restrito para as ferramentas esperadas. Verifique se a chave tem o escopo correto em Settings → API Keys. Verifique também que o header Authorization está formatado corretamente como Bearer sh0_....

Sessão expirada

Sessões expiram após 1 hora de inatividade. Se você receber um erro de sessão, o cliente deve reinicializar automaticamente. Se não, reinicie o cliente MCP para criar uma nova sessão.

Getting Started

AI Sandbox