Protocol and errors
For people writing their own MCP client, or debugging one. Clients like Claude and Cursor handle all of this for you.
Transport
Section titled “Transport”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) andDELETE(which would end a session) answer 405 withAllow: POST.- Send
Accept: application/json, text/event-streamas 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.
Versions
Section titled “Versions”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.
Methods
Section titled “Methods”| 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.
Results and their size
Section titled “Results and their size”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_cursorthen 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:
…---Page 1 of 3. Call get_report with page: 2 for the next.Errors
Section titled “Errors”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:
{ "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:
{ "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.