Skip to content

Protocol and errors

For people writing their own MCP client, or debugging one. Clients like Claude and Cursor handle all of this for you.

Streamable HTTP, stateless. POST one JSON-RPC 2.0 message to https://dash.alethman.com/api/mcp and read one JSON answer (Content-Type: application/json). There is no session id and no server-sent event stream, so:

  • GET (which would open a stream) and DELETE (which would end a session) answer 405 with Allow: POST.
  • Send Accept: application/json, text/event-stream as the transport asks; the answer is always plain JSON.
  • One message per POST. A JSON-RPC batch (an array) answers 400.
  • A body over 64 KB answers 413.
  • A notification, or a response to the server, has no id and answers 202 with no body.

The server speaks 2025-06-18 (its preference), 2025-03-26 and 2024-11-05. initialize echoes the version the client asks for when it is one of these, and offers 2025-06-18 otherwise. After that, a request whose MCP-Protocol-Version header names a version the server does not speak answers 400.

Method Answers
initialize protocolVersion, capabilities: { tools: { listChanged: false } }, serverInfo (alethman), and instructions for the assistant
ping {}
tools/list The tools the key’s scopes reach (Tools)
tools/call { content: [{ type: "text", text }] }, with isError: true when the tool failed
resources/list, resources/templates/list, prompts/list Empty lists, so clients that ask anyway stay quiet
anything else JSON-RPC error -32601, method not found

The tool list never changes during a connection (listChanged: false); it depends only on the key’s scopes.

A tool’s text is the endpoint’s JSON, at most 40,000 characters (about the most any client accepts in one tool result, even for headlines in Indic scripts).

  • A list that would run longer is cut from the end of its longest list, and gains a field saying so:

    "truncated": {
    "list": "data",
    "returned": 31,
    "of": 50,
    "note": "Cut to fit one answer. Ask for fewer with limit, or narrow with a filter, or page on with next_cursor."
    }

    For list_signals, next_cursor then points just after the last article kept, so nothing is skipped.

  • A Markdown report (get_report, the default format there) comes in pages, cut at a heading where one falls. Each page but a single one ends like this:

the end of page 1
…
---
Page 1 of 3. Call get_report with page: 2 for the next.

Two kinds, and the difference matters to a client:

Refusals before the message is read are HTTP errors whose body is a JSON-RPC error with code: -32001 and the REST API’s status and code in data:

HTTP 401
{
"jsonrpc": "2.0",
"id": null,
"error": {
"code": -32001,
"message": "That key is not valid. It may have been revoked or have expired.",
"data": { "status": 401, "code": "invalid_key" }
}
}
HTTP data.code Why
401 unauthenticated, invalid_key No key, or a key that is not valid (Authentication)
403 forbidden_origin The request carried an Origin header from another website. MCP clients that are not browsers send none.
409 workspace_not_ready The workspace has not finished setup
429 rate_limited The key’s 120 a minute, or the bad-key limit; see Retry-After

Malformed messages answer a JSON-RPC error with the standard codes: -32700 (not JSON, HTTP 400), -32600 (not a JSON-RPC 2.0 request, a batch, an unsupported protocol version, or a body over 64 KB with HTTP 413), -32601 (unknown method), -32602 (tools/call without a known tool name, or with arguments that are not an object), -32603 (a failure on Alethman’s side, HTTP 500).

A tool’s own failure (an argument out of range, a story or report not found, a scope the key lacks) is a normal result with isError: true and the reason as text, so the assistant can read it and try again:

tools/call → get_story with a story outside the workspace
{
"jsonrpc": "2.0",
"id": 9,
"result": {
"content": [{ "type": "text", "text": "No story with that id." }],
"isError": true
}
}

The messages are the REST API’s, so the Errors page applies.