Hanoo MCP

Gerencie seu próprio servidor Ubuntu para aplicações PHP

Ver em hanoo.io

Documentação

Visão geral

O Model Context Protocol (MCP) permite que um assistente use ferramentas que um serviço oferece. O servidor MCP da Hanoo dá a um assistente ferramentas com escopo definido sobre sua organização, para que ele possa responder com base no que está realmente em execução e, quando explicitamente autorizado, realizar operações de aplicação tipadas. Ele age como a pessoa que criou o token e nunca além do acesso atual dessa pessoa.

Perguntas para fazer

  • "Quais dos meus servidores não estão respondendo, e desde quando?"
  • "O que roda em web-1, e quais versões de PHP estão instaladas lá?"
  • "Por que a última implantação da Shop falhou?"
  • "Quais aplicações ainda estão em PHP 8.2?"
  • "Implante o branch principal configurado da Shop e acompanhe a operação até a conclusão."
  • "Implante uma nova aplicação Laravel 12.x no meu servidor Digital Ocean e me dê a URL da aplicação."

1. Criar um token de API

  1. 1 Entre no painel e abra API tokens, depois New token.
  2. 2 Dê um nome de acordo com onde ele será usado — "Claude Code no meu laptop" — e escolha quando expira: 7, 30 ou 90 dias.
  3. 3 Escolha exatamente o que ele pode fazer. Leituras começam selecionadas; criação de aplicações, implantação, rollback e alterações de configuração são autorizações separadas. Depois, escolha se a permissão cobre tudo o que você pode ver ou apenas servidores e aplicações nomeados.
  4. 4 Crie e copie. Ele é exibido apenas uma vez; a Hanoo guarda somente uma impressão digital e não pode exibi-lo novamente.

Criar tokens requer a permissão api_token.manage. Proprietários a possuem; um proprietário pode concedê-la a qualquer outra pessoa em Team → Edit access. Tokens criados antes da existência das ferramentas de escrita mantêm exatamente o acesso que receberam; para permitir que um assistente faça alterações, crie um novo.

2. Conectar seu assistente

Substitua hnmcp_… pelo seu token, ou defina HANOO_API_TOKEN no seu ambiente. Mantenha tokens fora de arquivos que você envia para o repositório.

Claude Code

Adicione o servidor uma vez, para você, pelo terminal:

terminal

claude mcp add --transport http hanoo https://mcp.hanoo.io/mcp \
  --header "Authorization: Bearer hnmcp_…"

claude mcp list    # hanoo: … ✔ Connected

.mcp.json — compartilhado com sua equipe; cada pessoa define HANOO_API_TOKEN

{
  "mcpServers": {
    "hanoo": {
      "type": "http",
      "url": "https://mcp.hanoo.io/mcp",
      "headers": {
        "Authorization": "Bearer ${HANOO_API_TOKEN}"
      }
    }
  }
}

Cursor

Em .cursor/mcp.json em um projeto, ou ~/.cursor/mcp.json para todos os projetos:

.cursor/mcp.json

{
  "mcpServers": {
    "hanoo": {
      "url": "https://mcp.hanoo.io/mcp",
      "headers": {
        "Authorization": "Bearer ${env:HANOO_API_TOKEN}"
      }
    }
  }
}

VS Code

Em .vscode/mcp.json. O VS Code pede o token uma vez e o armazena com segurança:

.vscode/mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "hanoo-token",
      "description": "Hanoo API token",
      "password": true
    }
  ],
  "servers": {
    "hanoo": {
      "type": "http",
      "url": "https://mcp.hanoo.io/mcp",
      "headers": {
        "Authorization": "Bearer ${input:hanoo-token}"
      }
    }
  }
}

Qualquer outro cliente MCP

Aponte-o para o endpoint via Streamable HTTP e envie o token como cabeçalho bearer. Para verificar um token manualmente:

terminal

curl -s https://mcp.hanoo.io/mcp \
  -H "Authorization: Bearer $HANOO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{
       "io.modelcontextprotocol/protocolVersion":"2026-07-28",
       "io.modelcontextprotocol/clientCapabilities":{}}}}'

ChatGPT, Claude na web, Claude Desktop e mobile

OAuth

Clientes hospedados podem se conectar sem um token para colar. A Hanoo usa descoberta OAuth 2.1, então cada pessoa faz login e aprova apenas o acesso que essa conexão precisa.

  1. 1 Adicione um servidor ou conector MCP personalizado no seu cliente e use https://mcp.hanoo.io/mcp como URL.
  2. 2 Escolha OAuth ou Sign in, se o cliente pedir. A Hanoo abre no seu navegador.
  3. 3 Faça login, escolha a organização, o que a conexão pode fazer, servidores, aplicações e validade, e então aprove. Apenas as leituras que o cliente pede começam selecionadas; cada alteração que ele pode fazer é uma autorização separada. A conexão aparece em API tokens, onde você pode revogá-la imediatamente.

Ferramentas

Um assistente recebe apenas as ferramentas que seu token permite. Listas vêm uma página por vez: passe next_cursor de volta como cursor para a próxima. Cada alteração exige uma idempotency_key: um valor novo por alteração pretendida, reutilizado apenas para repetir a mesma chamada, que então retorna a operação original em vez de iniciar uma segunda. Uma alteração retorna um job_id imediatamente; acompanhe-o com get_job. rollback_deployment também exige confirm_live_change definido como true.

FerramentaO que fazO que o token precisa
whoamiA organização, o membro e o token pelos quais esta conexão age, e o que ela pode fazer agora.Qualquer token
list_serversServidores, do mais recente ao mais antigo: se o agente está respondendo, SO, versão do agente, aplicações, qualquer operação em andamento.Servers
get_serverUm servidor: hardware, versões de PHP instaladas, CPU mais recente, uso de memória e disco, e suas aplicações.Servers
list_applicationsAplicações, opcionalmente em um servidor: tipo, estado, servidor, domínio principal, versão de PHP.Applications
get_applicationUma aplicação: domínios e TLS, runtime PHP, fonte (repositório Git e branch, ou pacote) e sua implantação mais recente.Applications (e Deployments para a implantação mais recente)
list_deploymentsImplantações Git de uma aplicação: estado, commit, branch, tempo, se falhou, e o resultado de cada etapa do pipeline — nunca sua saída.Deployments
get_jobUma operação pelo seu job_ id: o que faz, seu estado, tempo, um status de falha fixo e seu histórico.Operations
create_applicationCria uma aplicação a partir do catálogo fixado da Hanoo e retorna seu job de provisionamento assinado. Criar seu banco de dados é uma permissão separada.Create applications; opcionalmente create databases
deploy_applicationImplanta um branch Git através da chave de implantação somente leitura mantida no servidor da aplicação.Trigger deployments
rollback_deploymentTorna uma versão retida bem-sucedida ativa novamente após reconhecimento explícito. Não reverte migrações de banco de dados.Roll back releases
update_application_settingsAltera a raiz validada da aplicação e a raiz web relativa através de um job assinado seguro contra rollback.Change application settings
update_application_php_settingsSubstitui o conjunto completo nomeado e tipado de configurações PHP e PHP-FPM. Nunca aceita texto de configuração bruto.Change application settings

Segurança

Um assistente é um novo tipo de chamador: ele lê tudo o que é mostrado a ele, e pode ser direcionado pelo que lê. O servidor MCP é construído em torno disso.

  • Apenas alterações tipadas

    Ferramentas de escrita reutilizam a validação, autorização, jobs assinados, bloqueios de operação, idempotência e trilha de auditoria normais da Hanoo, e aparecem apenas quando o token recebeu explicitamente essas permissões. Não há proxy de API genérico, comando arbitrário, exclusão, restauração ou ferramenta de credenciais.

  • Como você, nunca além

    Um token pode conter apenas acesso que você tem, e cada chamada é verificada contra seu acesso naquele momento. Se um proprietário reduzir seu acesso ou removê-lo, seus tokens reduzem ou param na próxima chamada.

  • Nunca um segredo

    Valores de ambiente; senhas SSH, chaves públicas ou privadas; chaves de implantação; nomes de usuário, senhas, detalhes de conexão, instruções SQL e resultados de banco de dados; tokens; e payloads ou saídas brutas de jobs nunca são retornados.

  • Texto seguro e falhas

    Nomes, domínios e mensagens de commit são tratados como dados não confiáveis e limpos de instruções ocultas e valores com formato de credencial. Erros de backend de forma livre nunca saem da Hanoo; trabalho com falha é relatado apenas como operation_failed.

  • Tokens em que você pode confiar

    Exibidos uma vez, armazenados apenas como impressão digital, sempre com expiração, limitados ao que você escolhe, e revogados instantaneamente em API tokens.

  • Tudo é registrado

    Cada chamada e cada ação de plataforma aceita aparece no Audit Log com a pessoa e o token exato pelo qual passou. Uma página web não pode chamar o endpoint de forma alguma.

Limites

Requisições

60 por minuto por token, compartilhadas entre todos os workers de API. Acima disso: 429, com Retry-After.

Alterações

10 por minuto por token, contadas dentro do orçamento de requisições. Tentativas recusadas também contam.

Tamanho da requisição

64 KB

Vida útil

Tokens de API: 7, 30 ou 90 dias. Acesso OAuth: 1 hora; conexão: até 90 dias.

Tokens por pessoa

25 ativos, por organização

Solução de problemas

401 invalid_token

O token está ausente, digitado incorretamente, revogado ou expirado — ou seu acesso não inclui mais tokens de API. Um cliente hospedado deve fazer login novamente; um cliente manual deve enviar Authorization: Bearer hnmcp_….

permission_denied de uma ferramenta

O token não inclui essa operação. Crie um que inclua; o acesso de um token não pode ser alterado após sua criação.

not_found de uma ferramenta

O servidor, aplicação ou operação não existe, ou está fora do que este token pode ver.

403 origin_not_allowed

A requisição veio de uma página web. Use um cliente de desktop, editor ou linha de comando.

429 rate_limited

Aguarde o número de segundos em Retry-After e continue.

rate_limited de uma ferramenta de escrita

O token fez 10 alterações neste minuto. Aguarde o número de segundos na mensagem e repita com a mesma idempotency_key.

idempotency_key_reused

Essa chave já foi usada para uma alteração diferente. Use uma nova chave para uma nova alteração; reutilize uma chave apenas para repetir a chamada idêntica.

"Hanoo refused this change" com outro código

A alteração falhou nas mesmas verificações do painel — por exemplo, server_busy enquanto outra operação roda naquele servidor, ou uma versão que não é uma versão retida bem-sucedida. Inspecione com get_application ou list_deployments e repita.

404 ou 405

Use o endpoint exatamente — https://mcp.hanoo.io/mcp — e POST, que todo cliente MCP faz.