MCP Servers API

Overview

The MCP Servers API lets allternit-api act as an MCP server. External MCP clients can connect to /mcp/server with a Clerk bearer token and call the same tool registry exposed by the REST tool routes. The surface uses the MCP Streamable HTTP transport: single JSON-RPC requests with plain JSON responses, stateless and without server-initiated push. An internal variant at /internal/tools/mcp is available for the local Gizzi runtime’s MCP client, gated by the internal service token and x-allternit-user-id.

Base URL

Clerk-authenticated surface:

https://api.allternit.com/mcp/server

Internal surface:

https://api.allternit.com/internal/tools/mcp

For local development:

http://127.0.0.1:8013/mcp/server
http://127.0.0.1:8013/internal/tools/mcp

Authentication

/mcp/server requires a valid Clerk bearer token.
/internal/tools/mcp requires the internal service token and the x-allternit-user-id header.

See Authentication.

Supported JSON-RPC methods

Method	Description
`server/discover`	Supported protocol versions, capabilities, server info, and instructions (MCP 2026-07-28).
`initialize`	Legacy handshake (2025-11-25 and earlier): negotiated version, capabilities, server info.
`ping`	Health check.
`tools/list`	List available tools.
`tools/call`	Execute a tool by name.
`resources/list`, `resources/read`, `resources/templates/list`	The `ui://` Views behind the agent tools.

Tool catalog

The tools/list response includes:

Native host tools: shell.exec, file.read, file.write, file.list, file.exists, file.remove, system.info, system.env, http.get, http.post, time.now.
Office-engine Markdown conversion tools.
Tools from attached MCP servers registered in the dispatcher.

Attached servers

The same /mcp mount also serves the routes that manage which external MCP servers are attached (their tools then appear in tools/list):

Method	Path	Description
`GET` / `POST`	`/mcp/servers`	List or attach an MCP server.
`GET` / `DELETE`	`/mcp/servers/:id`	Get or detach an attached server.
`GET` / `POST`	`/mcp/connectors`	List or create MCP connectors.
`DELETE`	`/mcp/connectors/:id`	Remove a connector: ends its event subscriptions, deletes its stored OAuth tokens and agent bindings, then the row. `204`; `404` when it isn’t the caller’s. MCP Apps › Remove calls it.
`POST`	`/mcp/test`	Test a connection to an MCP server.
`GET`	`/mcp/oauth/callback`	OAuth callback for MCP servers that require it.

Protocol versions

The server speaks both MCP eras on the same endpoint:

2026-07-28 (stateless). No handshake. Put the version in every request’s params._meta["io.modelcontextprotocol/protocolVersion"] (and the MCP-Protocol-Version header). Results carry resultType: "complete" and _meta["io.modelcontextprotocol/serverInfo"]; list and read results also carry ttlMs and cacheScope: "private". An unknown version is refused with -32022 and the list of supported versions.
2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. Send initialize first, as before. An unknown version in initialize gets 2025-06-18.

If you send Mcp-Method or Mcp-Name headers, they must match the body; a mismatch is HTTP 400 with -32020. An Mcp-Name in the =?base64?…?= form is decoded before the comparison. List results (tools/list, prompts/list, resources/list, resources/templates/list) come back in one canonical order in both eras: ascending by name, uri or uriTemplate (byte order). The same rule applies on every Allternit MCP endpoint, including attached servers’ tools and the connector endpoints.

curl -X POST https://api.allternit.com/mcp/server \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: server/discover" \
  -d '{
    "jsonrpc": "2.0",
    "id": "d1",
    "method": "server/discover",
    "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28" } }
  }'

{
  "jsonrpc": "2.0",
  "id": "d1",
  "result": {
    "resultType": "complete",
    "supportedVersions": ["2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"],
    "capabilities": { "tools": { "listChanged": false }, "resources": { "listChanged": false } },
    "_meta": { "io.modelcontextprotocol/serverInfo": { "name": "allternit-api", "version": "0.1.0" } },
    "instructions": "Read-only access to the caller's Allternit agents and their runs. …",
    "ttlMs": 60000,
    "cacheScope": "private"
  }
}

Initialize (legacy clients)

Example request

curl -X POST https://api.allternit.com/mcp/server \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "example-client", "version": "1.0.0" }
    }
  }'

Example response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": { "tools": { "listChanged": false }, "resources": { "subscribe": false, "listChanged": false } },
    "serverInfo": { "name": "allternit-api", "version": "0.1.0" },
    "instructions": "Read-only access to the caller's Allternit agents and their runs. …"
  }
}

List tools

curl -X POST https://api.allternit.com/mcp/server \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

Example response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "shell.exec",
        "description": "Execute a shell command on the allternit-api host.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "command": { "type": "string" },
            "cwd": { "type": "string" }
          },
          "required": ["command"]
        }
      }
    ]
  }
}

Call a tool

Request body

Field	Type	Description
`name`	string	Tool name.
`arguments`	object	Tool arguments.

Tools whose names contain a . are first dispatched to attached MCP servers; otherwise they run through the internal tool registry.

Example request

curl -X POST https://api.allternit.com/mcp/server \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "time.now",
      "arguments": {}
    }
  }'

Example response

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      { "type": "text", "text": "2026-08-13T10:00:00Z" }
    ],
    "isError": false
  }
}

Internal MCP endpoint

The internal endpoint uses the same JSON-RPC contract but is intended for peer services.

Required headers

Header	Description
`Authorization`	`Bearer <internal-service-token>`.
`x-allternit-user-id`	User id the request is running as.
`x-allternit-organization-id`	Optional organization id.

MCP Events (mcp.allternit.com)

The public edge at https://mcp.allternit.com/mcp (agents server, scope agents:read) and https://mcp.allternit.com/mcp/bots/<bot id> (vendor bot connector, scope bots:act) supports the MCP Events extension with webhook delivery. Both advertise it in server/discover (and in a legacy initialize answer):

"capabilities": { "tools": { "listChanged": false }, "events": { "listChanged": false } }

Method	What it does
`events/list`	The events this server offers, with `inputSchema` (filter arguments) and `payloadSchema`.
`events/subscribe`	Create or refresh a webhook subscription. Idempotent: the same caller, URL, name and arguments always map to the same `id`.
`events/unsubscribe`	End a subscription. Always answers `{}`.

The edge answers these itself; your computer doesn’t need to be awake. Subscriptions last 24 hours by default, up to 7 days (ttlMs: null is clamped to 7 days); subscribe again before refreshBefore to keep them. Deliveries are signed with Standard Webhooks using the whsec_ secret you supply, and carry X-MCP-Subscription-Id. See the MCP Events guide for the event catalog, the verification challenge, and delivery rules.

Code	Name	When
`-32602`	InvalidParams	Bad arguments, a non-https or private callback URL, or a `whsec_` secret outside 24–64 bytes.
`-32011`	NotFound	The event isn’t offered by this server (`data.kind: "event"`).
`-32012`	Forbidden	A vendor bot connector asked for another bot’s events.
`-32013`	ResourceExhausted	50 live subscriptions per app and server (`data.limit: "subscriptions"`).
`-32014`	Unsupported	A delivery mode other than `webhook`.
`-32015`	CallbackEndpointError	Your callback didn’t pass verification; `data.reason` is `connection_refused`, `timeout`, `tls_error`, `http_4xx`, `http_5xx` or `challenge_failed`.

Owners see and end subscriptions through the cloud API: GET /api/v1/mcp/approvals lists each approved app’s subscriptions, DELETE /api/v1/mcp/events/subscriptions/:id ends one (the callback gets a signed terminated message, reason: "ended_by_owner"), and GET /api/v1/events/catalog returns every event with a plain-words title and the servers that offer it. Fields and errors are in Seeing and ending subscriptions. Opening https://mcp.allternit.com/ (or the server URL in a browser) shows a short page with the server URLs, protocol versions and event catalog.

Error codes

JSON-RPC errors are returned with standard JSON-RPC error codes:

Code	Meaning
`-32001`	MCP tunnel auth failed.
`-32601`	Method not found.
`-32700` to `-32603`	Standard JSON-RPC parse/invalid-request/internal errors.

HTTP status codes:

Status	Meaning
`200 OK`	Successful JSON-RPC response.
`202 Accepted`	JSON-RPC notification received (no `id`).
`400 Bad Request`	Malformed JSON-RPC request or missing `x-allternit-user-id`.
`401 Unauthorized`	Missing or invalid auth token.

Platform API

Legal

Overview

Agency API (Preview)

LLM Gateway

Agents & Runtime

Work Queue & Deployments

Files, Webhooks & Sandbox

Tools & Connectors

Collaboration & Workflows

Infrastructure & Platform

Canvases

Onboarding

A Labs

Playground

Users & Profiles

Overview

Base URL

Authentication

Supported JSON-RPC methods

Tool catalog

Attached servers

Protocol versions

Initialize (legacy clients)

Example request

Example response

List tools

Example response

Call a tool

Request body

Example request

Example response

Internal MCP endpoint

Required headers

MCP Events (mcp.allternit.com)

Error codes

​Overview

​Base URL

​Authentication

​Supported JSON-RPC methods

​Tool catalog

​Attached servers

​Protocol versions

​Initialize (legacy clients)

​Example request

​Example response

​List tools

​Example response

​Call a tool

​Request body

​Example request

​Example response

​Internal MCP endpoint

​Required headers

​MCP Events (mcp.allternit.com)

​Error codes

​Related pages

Overview

Base URL

Authentication

Supported JSON-RPC methods

Tool catalog

Attached servers

Protocol versions

Initialize (legacy clients)

Example request

Example response

List tools

Example response

Call a tool

Request body

Example request

Example response

Internal MCP endpoint

Required headers

MCP Events (mcp.allternit.com)

Error codes

Related pages