Hanoo MCP

Manage your own Ubuntu server for PHP applications

Documentation

Overview

The Model Context Protocol (MCP) lets an assistant use tools a service provides. Hanoo's MCP server gives an assistant seven read-only tools over your organization, so it can answer from what is actually running — not from what it guesses. It acts as the person who made the token, and never beyond what that person may see.

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?”

1. Create an API token

1 Sign in to the dashboard and open API tokens, then New token.
2 Name it after where it will live — “Claude Code on my laptop” — and choose when it expires: 7, 30 or 90 days.
3 Choose what it may read — servers, applications, deployments, operations — and whether that covers everything you can see or only the servers and applications you pick.
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.

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 Code

Add the server once, for you, from the terminal:

terminal

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

claude mcp list    # hanoo: … ✔ Connected

.mcp.json — shared with your team; each person sets HANOO_API_TOKEN

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

Cursor

In .cursor/mcp.json in a project, or ~/.cursor/mcp.json for every project:

.cursor/mcp.json

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

VS Code

In .vscode/mcp.json. VS Code asks for the token once and stores it securely:

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

Any other MCP client

Point it at the endpoint over Streamable HTTP and send the token as a bearer header. To check a token by hand:

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 on the web, Claude Desktop and mobile

OAuth

Hosted clients can connect without a token to paste. Hanoo uses OAuth 2.1 discovery, so each person signs in and approves only the access that connection needs.

1 Add a custom MCP server or connector in your client and use https://mcp.hanoo.io/mcp as its URL.
2 Choose OAuth or Sign in, if the client asks. Hanoo opens in your browser.
3 Sign in, choose the organization, reads, servers, applications and expiry, then approve. The connection appears under API tokens, where you can revoke it immediately.

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.

Tool	What it reads	Token needs
whoami	The organization, member and token this connection acts as, and what it may read right now.	Any token
list_servers	Servers, newest first: whether the agent is answering, OS, agent version, applications, any operation in progress.	Servers
get_server	One server: hardware, installed PHP versions, latest CPU, memory and disk use, and its applications.	Servers
list_applications	Applications, optionally on one server: type, state, server, primary domain, PHP version.	Applications
get_application	One application: domains and TLS, PHP runtime, source (Git repository and branch, or package) and its latest deployment.	Applications (and Deployments for the latest deployment)
list_deployments	An application’s Git deployments: state, commit, branch, timing, whether it failed, and each pipeline step’s outcome — never its output.	Deployments
get_job	One operation by its job_ id: what it does, its state, timing, a fixed failure status and its history.	Operations

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.

Read-only
No tool changes anything. There is no tool to run a command, deploy, restart or delete.
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 appears in the Audit Log with the person and the token it came through. A web page cannot call the endpoint at all.

Limits

Requests

About 60 a minute per token. Beyond that: 429, with Retry-After.

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 kind of read. 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.

404 or 405

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