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 /api/v1/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/api/v1/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/api/v1/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/api/v1/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/api/v1/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`	As 45 ferramentas de leitura	Listar e inspecionar apps, serviços, domínios, logs e métricas. Nenhuma modificação permitida.
`deploy`	Leitura + deploy	Tudo o que read permite, mais fazer deploy, reverter, reiniciar, iniciar, parar e escalar aplicações existentes. Não pode criar nem excluir aplicações, alterar a sua configuração ou domínios, executar comandos nem criar chaves de API.
`admin`	Todas as 106 ferramentas	Acesso total: criação de aplicações (`create_app`, `upload_app`, `deploy_template`, `deploy_compose`), ferramentas do sandbox, definições do servidor, gestão de usuários, backups e ações destrutivas. Nenhuma chave, nem mesmo uma admin, pode criar outra chave de API.

Para criar uma chave de API, vá a Configurações → Chaves API no painel. Escolha o âmbito conforme o que a IA precisa fazer. Para o trabalho diário em aplicações existentes, deploy oferece o equilíbrio certo entre capacidade e segurança. As chaves criadas antes da v1.10.2 com o âmbito standard são lidas como deploy.

Warning

Use o âmbito admin apenas quando a IA precisar criar ou excluir aplicações, alterar a configuração ou executar comandos. Para fazer deploy e reiniciar aplicações existentes, recomenda-se deploy.

Auto-Descoberta

Todas as 106 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 é a mesma para todas as chaves: tools/list devolve as 106 ferramentas (45 de leitura, 45 de escrita, 16 destrutivas). O escopo da chave é verificado quando uma ferramenta é chamada: uma chave read que chama uma ferramenta de escrita recebe “API key scope 'read' cannot execute 'write' risk tools”.

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.

Primeiros passos

Sandbox de IA