MCP Server & AI Tools

These docs are a queryable data source, not just a website. An assistant with access to them answers from the endpoint shapes and enum values that are live right now, instead of from whatever it memorised about payment APIs in general — which, for a crypto gateway with eleven chains, two public surfaces and a signing scheme of its own, is usually wrong in a way that compiles.

Two ways in: an MCP server for interactive sessions, and plain markdown for everything else.

Connect the MCP server#

The server speaks streamable HTTP at:

https://docs.havala.io/api/mcp

No key, no account. It is read-only and it only ever returns documentation.

Claude Code#

claude mcp add --transport http havala-docs https://docs.havala.io/api/mcp

Cursor, VS Code, and other clients that take JSON#

{
  "mcpServers": {
    "havala-docs": {
      "url": "https://docs.havala.io/api/mcp"
    }
  }
}

Codex#

codex mcp add havala-docs -- npx -y mcp-remote https://docs.havala.io/api/mcp

ChatGPT#

Settings → Connectors → Add connector, then paste https://docs.havala.io/api/mcp as the URL.

Every page also carries a Copy page button with a dropdown that will hand you the config for your client — including a one-click install for VS Code — so you do not have to come back here for the URL.

The tools#

Four tools, all returning markdown or JSON as text.

category is one of the three category ids:

invoices, payments, checkout

invoices and payments are the HMAC-signed merchant gateway (/api/v1/…), called server to server. checkout is the unauthenticated buyer-facing payment-page surface (/checkout/api/v1/…). tier on a listed endpoint marks how central it is: core is the handful a minimum integration actually needs.

Those two surfaces are the whole documented API, and that boundary is the single most useful thing to tell an assistant. Account management — creating a merchant point, setting a webhook URL, rotating a signing secret, choosing which chains to accept — happens in the merchant dashboard and has no endpoint on either surface. list_endpoints will not return one and search_docs will not find one, so a generated call for any of it was invented rather than looked up.

slug is one of the nine guides:

getting-started, authentication, accepting-payments, webhook-setup, supported-chains, hosted-checkout, testing-sandbox, going-live, mcp

locale is en or ru, defaulting to en.

The useful shape of a session is search then fetch: ask something like "how do I verify a Havala webhook signature in Python", and the assistant calls search_docs, pulls the matching guide with get_guide, and writes against the real header names — X-Webhook-Signature: sha256={hex} over the raw body — rather than a plausible invention.

For code generation specifically, get_endpoint is the tool that matters. It returns the parameters, the exact signaturePattern for that method and path, and a real response body, which is enough for an assistant to produce a signed request that the guard actually accepts.

Plain markdown#

Not every tool speaks MCP. The same corpus is served as flat text.

curl https://docs.havala.io/guides/authentication.md
curl https://docs.havala.io/api-reference/invoices/create-invoice.md
curl https://docs.havala.io/api-reference/invoices.md
curl https://docs.havala.io/llms.txt

The .md suffix works on every documentation path, not just guides:

• /guides.md — the guide index
• /guides/{slug}.md — one guide
• /api-reference.md — every category and endpoint
• /api-reference/{category}.md — one category
• /api-reference/{category}/{endpointId}.md — one endpoint
• /sdks.md and /sdks/{language}.md — the client recipes

A locale prefix is understood and selects the guide language: /ru/guides/authentication.md. It affects guide bodies only; endpoint documentation is generated from one shared dataset.

Anything else under those paths returns 404 with a plain-text body, so a crawler that guesses wrong gets a clean answer rather than an HTML error page.

Which one to reach for#

• MCP — an interactive coding session, where the assistant should look things up on demand and you do not know in advance which endpoint you need.
• /llms.txt and /llms-full.txt — indexing the docs into your own search or retrieval system. Start with llms.txt to get the shape, then decide whether the full corpus is worth the tokens.
• .md on one URL, or the Copy page button — grabbing a single page, once, to paste into a chat.

Whichever route you take, treat generated integration code the way you would treat any generated code that moves money: read the signing function line by line against Authentication & Request Signing before you point it at a live key. The canonical string has a conditional line in it, and that is exactly the sort of detail a confident guess gets wrong.