Skip to content
akari v0.5.1 docs Log in
View as Markdown Edit on GitHub

Agent access

akari serves a remote Model Context Protocol endpoint, so a coding agent can read your whole session history without opening a browser. It exposes the same surface the web UI shows (the overview analytics, the projects index, the session feed, and a session's full transcript) plus the raw data behind it: tool-call bodies from the content store, and the lossless bytes a session was ingested from. It is read-only by construction; no tool creates, changes, or deletes anything.

The endpoint is at /mcp on your server, over Streamable HTTP:

https://akari.example.com/mcp

Connect it once from your harness. In Claude Code:

claude mcp add --transport http akari https://akari.example.com/mcp

On first use the harness opens your browser to akari, which recognizes the session you are already signed in to and asks you to approve the connection. The browser sign-in is the authentication; no credential is passed to the agent.

Behind that click is the OAuth 2.1 flow MCP defines, with akari acting as both the resource and the authorization server. The agent registers itself, redirects through a PKCE-protected authorization request, and exchanges the result for a read-only access token that refreshes on its own. The token carries the read scope and nothing more. You can revoke it any time from the Account page's Connected apps section, which disconnects the agent and invalidates its tokens at once.

For the flow to advertise correct URLs behind a reverse proxy, set AKARI_PUBLIC_URL to the server's external origin (Self-hosting).

Connecting without a browser

A harness that cannot run the browser flow authenticates with a read-scope API token instead. Create one on the account page (the read scope is read-only, the counterpart of the push-only ingest and the read-write full) and pass it as a bearer token:

claude mcp add --transport http akari https://akari.example.com/mcp \
  --header "Authorization: Bearer <read-token>"

A read token reaches only the MCP endpoint: it cannot push sessions or drive the write surface. It does not expire until you revoke it.

The tools

Every tool is read-only and sees every internal session, the same surface a signed-in user sees. Fetch data top-down: overview and list_projects for the lay of the land, list_sessions to find runs, get_session for a transcript, then read_tool_body or get_session_raw to go deeper on one.

Tool Returns
whoami The account the credential authenticates as: user id, username, and whether it is an admin.
overview Fleet usage for a trailing window: cost, tokens by class, session count, a daily series, and by-model and by-agent breakdowns. Also lists the accounts present, so their ids can scope later calls.
list_projects Every project, most recently active first, each with its session count and token and cost totals.
get_project One project's identity, its windowed analytics (optionally narrowed by agent, user, or machine), and the agents, users, and machines that ran in it.
list_sessions The cross-project session feed with filters and a facet rail, paged.
get_session One session's header and a window of its transcript: messages, thinking, tool-call metadata, attachments, and subagents.
read_tool_body A tool call's input or result body from the content store, by the hash the tool call carries.
get_session_raw The lossless bytes a session was ingested from, behind the parsed projection.

Parameters that govern paging through a large history:

  • Trailing windows. overview, get_project, and list_sessions take days; 0 or omitted means all of history.
  • Paging the feed. list_sessions returns up to 500 rows and a next_cursor; pass it back as cursor to walk the whole feed. It also returns a facet rail (busiest agents, users, machines, projects) whose values are the exact strings to pass back as filters.
  • Paging a transcript. get_session returns a bounded window of messages (set include_transcript: false for just the header). When transcript.has_more is true, pass the window's next_after as transcript_after to fetch the next page.
  • Fetching bodies. Tool bodies are not inlined in get_session; take the input_sha256 or result_sha256 off a tool call and pass it, with the session_id that references it, to read_tool_body. Text returns as text, binary as base64, capped by max_bytes.

What the MCP sees

The MCP surface mirrors the web UI: the same sessions, the same visibility rule (every internal session, exactly what a signed-in user sees), plus get_session_raw for the ingested bytes, which the web UI does not surface. It exposes no account or token management and no way to publish, delete, or write; those stay on the full-scope web surface.

Next: Self-hosting -> run the server yourself.