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:
Internal surface:
For local development:

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

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.

Initialize

Example request

Example response

List tools

Example response

Call a tool

Request body

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

Example request

Example response

Internal MCP endpoint

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

Required headers

Error codes

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