MCP

Assistant Cloud exposes a stateless Model Context Protocol endpoint for agents that need to inspect a project's runs, usage, threads, scores and topics. It uses the backend host and an API key, and the API key strategy still requires Aui-Workspace-Id even though the tools scope their reads to the project.

The MCP endpoint

POST /v1/mcp

The server identifies itself as { name: "assistant-cloud", version: "1.0.0" }. It creates no MCP session because the transport is configured without a session id generator. Every exposed tool has annotations: { readOnlyHint: true }.

POST /v1/mcp
Authorization: Bearer sk_aui_proj_…
Aui-Workspace-Id: usr_000000000000000000000000
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "list_runs", "arguments": { "limit": 50 } }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"runs\":[],\"next_cursor\":null}"
      }
    ]
  }
}

The body is a JSON-RPC 2.0 message as the MCP streamable HTTP transport defines it; initialize and tools/list use the same envelope, and the tool sections below show only the result each tool returns.

The successful tool result is { content: [{ type: "text", text: JSON.stringify(result) }] }. A tool failure adds isError: true and serializes { error: message } as the text result. Only the messages in this table pass through unchanged. Every other tool failure becomes Request failed.

The endpoint and all eight tools are read only. They do not create sessions or write project data, so repeating a successful read is idempotent. A client should send the same backend URL, API key and workspace header on every request.

list_runs

List runs in the authenticated project. System runs are excluded, as they are from the project run read.

{ "limit": 50 }

{ "runs": [], "next_cursor": null }

Results are ordered by created_at DESC, id DESC. The cursor is base64url encoded JSON containing created_at as an ISO value and id. Pass next_cursor unchanged to the next call. An invalid cursor produces the Invalid run cursor tool error.

get_run

Get one run and its spans from the authenticated project.

{ "run_id": "run_000000000000000000000000" }

{ "id": "run_000000000000000000000000", "spans": [] }

The result is the project run object with spans. Spans are ordered by start_ms ASC, span_index ASC. This tool does not use a cursor. A missing run produces the Run not found tool error.

usage_daily

Get daily usage for the authenticated project.

{ "from": "2026-09-01", "to": "2026-09-17", "group_by": "model" }

{
  "days": [
    {
      "day": "2026-09-17",
      "provider": null,
      "model_id": null,
      "runs": 0,
      "errors": 0,
      "input_tokens": 0,
      "output_tokens": 0,
      "total_tokens": 0,
      "cost_usd": 0
    }
  ]
}

Without group_by, every day in the range is returned with zero filled values. With group_by=model, rows are grouped by day, provider and model as stored, with no zero fill, and provider or model_id can be null. runs counts kind = run rows. errors counts kind = run rows with status = error. Token and cost sums include kind = sampling rows. This tool has no cursor. An invalid date produces Invalid usage day range, and an invalid span produces Usage day range must span at most 366 days.

usage_period

Get the current usage period for the authenticated project.

{}

{
  "plan": "free",
  "period_start": "2026-09-01T00:00:00.000Z",
  "period_end": "2026-10-01T00:00:00.000Z",
  "active_users": 0,
  "included": 200,
  "cap": 200,
  "capped_at": null,
  "thread_titles": {
    "used": 0,
    "completed": 0,
    "included": 500,
    "cap": 500,
    "capped_at": null
  }
}

The result is the full usage period object. period_start and period_end are the UTC calendar month boundaries. active_users is the greater of the stored period count and the sum of period users by day. included and cap come from the limits resolved for the project. This tool has no cursor. A missing project fails with a message outside the passthrough table, so the tool answers Request failed.

list_threads

List threads in the authenticated project.

{ "limit": 50 }

{ "threads": [], "next_cursor": null }

The project scope includes every workspace, including archived threads. Results are ordered by created_at DESC, id DESC. The cursor is base64url encoded JSON containing created_at as an ISO value and id. Pass next_cursor unchanged to the next call. An invalid cursor produces Invalid cursor.

get_thread

Get one thread and its messages from the authenticated project.

{ "thread_id": "thread_0qzof3jPoDwr7K3agyJN3D4U" }

{ "thread": {}, "messages": [] }

The result includes the thread and its messages. Messages are mapped to ThreadMessageDTO and ordered by height ASC, created_at ASC, id ASC. This tool has no cursor. A missing thread produces Thread not found.

list_scores

List scores in the authenticated project.

{ "name": "quality", "limit": 50 }

{ "scores": [], "next_cursor": null }

Scores are ordered by created_at DESC, id DESC. Each score contains id, thread_id, message_id, run_id, name, data_type, value, string_value, source, author_id, comment, created_at and updated_at; value is a number or null. The cursor is base64url encoded JSON containing created_at and id. Pass next_cursor unchanged. An invalid cursor produces Invalid cursor.

list_topics

List topics and thread counts in the authenticated project.

{}

{ "topics": [] }

Each topic has id, name, created_at, updated_at and thread_count. Topics are ordered by thread_count DESC, name ASC. This tool has no cursor.

Configure a client

Use the MCP URL and both required headers in your client. The Claude Code command is:

claude mcp add --transport http assistant-cloud https://backend.assistant-api.com/v1/mcp --header "Authorization: Bearer sk_aui_proj_…" --header "Aui-Workspace-Id: usr_000000000000000000000000"

Clients configured through an mcpServers file, such as Cursor, use the same values:

{
  "mcpServers": {
    "assistant-cloud": {
      "url": "https://backend.assistant-api.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer sk_aui_proj_…",
        "Aui-Workspace-Id": "usr_000000000000000000000000"
      }
    }
  }
}

Create a key for this MCP client, scope its use to this tool, give it an expiry and revoke it when the client is no longer needed. The key grants read access to the whole project, so do not reuse it for unrelated access.