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:Authentication
/mcp/serverrequires a valid Clerk bearer token./internal/tools/mcprequires the internal service token and thex-allternit-user-idheader.
Supported JSON-RPC methods
Tool catalog
Thetools/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: