Skip to content
Alcarta

Connect over MCP

Alcarta implements MCP streamable HTTP at /mcp. It does not provide a stdio transport.

Transport requirements

Section titled “Transport requirements”

Every request includes:

Authorization: Bearer <JWT>
Accept: application/json, text/event-stream

Alcarta accepts MCP revisions 2025-11-25, 2025-06-18, and 2025-03-26. Ask for the newest revision your client supports. Tasks are available only when the negotiated revision is 2025-11-25.

Initialize

Section titled “Initialize”
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {"name": "acme-triage", "version": "1.0.0"}
  }
}

The response header contains Mcp-Session-Id. Echo it on every later request together with the negotiated MCP-Protocol-Version. Then send the standard notifications/initialized notification.

A session is bound to the token ID that created it and has a sliding 24-hour lifetime. An unknown, expired, or cross-token session returns 404 session_not_found; initialize again. End it with DELETE /mcp.

List tools

Section titled “List tools”
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

A fresh, fully authorized session advertises six names:

  • settings_toggle_advanced_tools
  • email_query
  • email_act
  • email_await
  • email_requests
  • get_identity

The list is also filtered by effective grants, so a narrow token can see fewer. The 23 other granular names are hidden, not disabled. Call settings_toggle_advanced_tools {"enabled":true} to advertise all authorized granular tools for that session. A hidden granular tool remains callable by name when the token has its scope.

Call a tool

Section titled “Call a tool”

Start with identity discovery:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {"name": "get_identity", "arguments": {}}
}

Then read messages:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "email_query",
    "arguments": {
      "select": {
        "mailbox_id": "mbx_…",
        "folder": "inbox",
        "filter": {"seen": false},
        "limit": 10
      },
      "view": "summary"
    }
  }
}

structuredContent is authoritative. By default, Alcarta also serializes the same JSON into a text content block for clients that do not expose structured results. Operators can opt out of the duplicate text block only when every connected client is known to consume structuredContent.

Error layers

Section titled “Error layers”
  • HTTP errors cover credentials, origin validation, protocol headers, and rate limits.
  • JSON-RPC errors cover unknown methods/tools and malformed parameters.
  • Actionable domain errors return a tool result with isError: true and a structured error object.

Always inspect isError; a JSON-RPC success response can contain a refused tool operation.