Connect an AI assistant to Hanoo

Overview

The Model Context Protocol (MCP) lets an assistant use tools a service provides. Hanoo's MCP server gives an assistant scoped tools over your organization, so it can answer from what is actually running and, when explicitly granted, perform typed application operations. It acts as the person who made the token and never beyond that person's live access.

Things to ask

• “Which of my servers are not responding, and since when?”
• “What runs on web-1, and which PHP versions are installed there?”
• “Why did the last deployment of Shop fail?”
• “Which applications are still on PHP 8.2?”
• “Deploy the configured main branch of Shop and follow the operation to completion.”
• “Deploy a new Laravel 12.x application in my Digital Ocean server and give me the application url.”

1. Create an API token

1. 1

   Sign in to the dashboard and open API tokens, then New token.

2. 2

   Name it after where it will live — “Claude Code on my laptop” — and choose when it expires: 7, 30 or 90 days.

3. 3

   Choose exactly what it may do. Reads start selected; application creation, deploy, rollback and configuration changes are separate opt-ins. Then choose whether the grant covers everything you can see or only named servers and applications.

4. 4

   Create it and copy it. It is shown once; Hanoo keeps only a fingerprint and cannot show it again.

Creating tokens needs the api_token.manage permission. Owners have it; an owner can give it to anyone else from Team → Edit access. Tokens made before write tools existed keep exactly the access they were given; to let an assistant make changes, create a new one.

2. Connect your assistant

Replace hnmcp_… with your token, or set HANOO_API_TOKEN in your environment. Keep tokens out of files you commit.

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

claude mcp list    # hanoo: … ✔ Connected

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

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

{
  "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}"
      }
    }
  }
}

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":{}}}}'

Tools

An assistant is offered only the tools its token allows. Lists come a page at a time: pass next_cursor back as cursor for the next one. Every change takes an idempotency_key: a fresh value per intended change, reused only to retry that same call, which then returns the original operation instead of starting a second one. A change returns a job_id at once; follow it with get_job. rollback_deployment also needs confirm_live_change set to true.

Security

An assistant is a new kind of caller: it reads whatever it is shown, and it can be steered by what it reads. The MCP server is built around that.

• Typed changes only

  Write tools reuse Hanoo’s normal validation, authorization, signed jobs, operation locks, idempotency and audit trail, and appear only when the token was explicitly granted them. There is no generic API proxy, arbitrary command, delete, restore or credential tool.

• As you, never more

  A token can hold only access you have, and every call is checked against your access at that moment. If an owner narrows your access or removes you, your tokens narrow or stop on their next call.

• Never a secret

  Environment values; SSH passwords, public or private keys; deploy keys; database usernames, passwords, connection details, SQL statements and results; tokens; and raw job payloads or output are never returned.

• Safe text and failures

  Names, domains and commit messages are treated as untrusted data and scrubbed for hidden instructions and credential-shaped values. Free-form backend errors never leave Hanoo; failed work is reported only as operation_failed.

• Tokens you can trust

  Shown once, stored only as a fingerprint, always expiring, limited to what you choose, and revoked instantly from API tokens.

• Everything is recorded

  Every call and every accepted platform action appears in the Audit Log with the person and exact token it came through. A web page cannot call the endpoint at all.

Limits

Requests

60 a minute per token, shared across every API worker. Beyond that: 429, with Retry-After.

Changes

10 a minute per token, counted inside the request budget. Refused attempts count too.

Request size

64 KB

Lifetime

API tokens: 7, 30 or 90 days. OAuth access: 1 hour; connection: up to 90 days.

Tokens per person

25 active, per organization

Troubleshooting

401 invalid_token

The token is missing, mistyped, revoked or expired — or your access no longer includes API tokens. A hosted client should sign in again; a manual client must send Authorization: Bearer hnmcp_….

permission_denied from a tool

The token does not include that operation. Create one that does; a token’s access cannot be changed after it is made.

not_found from a tool

The server, application or operation does not exist, or it is outside what this token may see.

403 origin_not_allowed

The request came from a web page. Use a desktop, editor or command-line client.

429 rate_limited

Wait for the number of seconds in Retry-After, then continue.

rate_limited from a write tool

The token made 10 changes this minute. Wait the number of seconds in the message, then retry with the same idempotency_key.

idempotency_key_reused

That key was already used for a different change. Use a new key for a new change; reuse a key only to retry the identical call.

“Hanoo refused this change” with another code

The change failed the same checks as in the dashboard — for example server_busy while another operation runs on that server, or a release that is not a successful retained one. Inspect it with get_application or list_deployments, then retry.

404 or 405

Use the endpoint exactly — https://mcp.hanoo.io/mcp — and POST, which every MCP client does.