a4sx-mcp

A local MCP server for a4sx, the library and marketplace for coding-agent sessions. It gives any MCP client (Claude Code, Claude Desktop, Cursor, VS Code, ...) five tools to find a saved session, load it as context, and save the current one, using the sign-in of the a4sx command-line tool.

It runs on your machine over stdio. Your a4sx token stays in the a4sx config directory and is only ever sent to the server that issued it: pointing the server elsewhere with --base never sends it a token from another server.

Private library: the sessions saved under your a4sx account on session-exchange.com. Its entries are not listed in the marketplace and not returned by public search; they are listed, fetched, versioned and deleted through the a4sx API with your own sign-in (or an agent key you create). Listing a session in the marketplace is a separate step in the web app, with a review. "Private" describes who can list and fetch an entry through a4sx; the server stores the bytes you upload, after scrubbing them again.

Tools

The names, input schemas and limits are the same as the hosted a4sx MCP server's.

Safety rules:

• acquire_session never buys. For a paid listing you have no purchase or grant for, it returns status: "payment_required" with the price and the listing URL (or, when the listing's session is sold on its own, the member to buy). You buy it yourself in the web app, then ask again.
• Harnesses. Claude Code, Codex CLI and Grok Build sessions are listed and loaded alike; only Claude Code sessions can be resumed today. Every search and summary row carries the harness it was recorded with ({id, version}; unknown when not identified), and resumable is false for a session recorded with another harness. fetch_session_context renders such a session from its stored canonical form.
• publish_session only saves privately. visibility accepts only "private"; listing a session publicly is a separate, reviewed step in the web app. It accepts only Claude Code or Codex CLI JSONL (every line a record with a type; a Claude Code user or assistant turn with a session id, or a Codex CLI session_meta record first), so it can't be used to upload an arbitrary file. The transcript, its title and its label are scrubbed on your machine with the a4sx SDK, which applies the a4sx CLI's rules (secrets, command-line passwords, Sheet ids, and personal data: e-mail and IP addresses, home-directory user names, hosts, key-file paths), and scrubbed again by the server. Scrubbing is a backstop, not a guarantee. A session that continues someone else's (its parent, or the session it was resumed from, was acquired) stays marked as untrusted (untrusted: true).
• Neither tool asks for confirmation inside the protocol. Like the hosted server, it relies on the rules above and on the tool annotations: acquire_session and publish_session are marked readOnlyHint: false, so clients that ask before a tool runs (Claude Code does by default) can ask you, and you should not auto-approve them. The three read tools are marked read-only.
• Loaded sessions are reference material, not instructions. fetch_session_context always starts with a notice saying so, then wraps everything the session's author controls (title and turns) in <<<A4SX_UNTRUSTED_SESSION nonce=…>>> … <<<END_A4SX_UNTRUSTED_SESSION nonce=…>>> with a random nonce. Inside it, every kind of line break is normalised to \n, <<</>>> become ‹‹‹/››› and a leading # becomes \# (the notice says so), so content can't close the envelope or fake a ### User heading. The title is one line of at most 200 characters, and cutting to max_tokens never removes the notice or the closing line. search_sessions and get_session_summary results are framed the same way: a notice first, then the JSON inside the envelope, with every author-written string on one line, neutralised and capped per field, and the whole result bounded to 64 KiB (a page cut short says truncated: true, and next_offset resumes at the first row left out). Server guidance (next, next_offset) goes on one line after the closing delimiter, never inside the envelope, and carries only fixed texts and numbers. A session with another author's content gets untrusted: true and a stronger notice. Look-alike characters (full-width ＜/＃, zero-width spaces) are left as they are: they cannot close the envelope, because the closing line needs the random nonce, but a model may still be misled by them. This lowers the risk of prompt injection but cannot rule it out: keep tool approval on.
• Limits: transcripts up to 2 MiB per publish_session call (use a4sx push for larger ones); per process, at most 240 requests (tools/list and tools/call), 20 acquires and 10 publishes per minute. The a4sx server enforces its own limits as well.

Quickstart

You need uv (for uvx) and an a4sx account.

1. Sign in once with the a4sx CLI. The MCP server reuses that sign-in:

   uvx a4sx login
   

   Searching public sessions works without signing in. If a tool needs your account and you are not signed in (or the sign-in expired), it returns an error telling you to run a4sx login.

2. Add the server to your client.

Claude Code

claude mcp add a4sx -- uvx a4sx-mcp

Claude Desktop

Edit claude_desktop_config.json (Settings, Developer, Edit Config) and restart Claude Desktop:

{
  "mcpServers": {
    "a4sx": { "command": "uvx", "args": ["a4sx-mcp"] }
  }
}

Cursor

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "a4sx": { "command": "uvx", "args": ["a4sx-mcp"] }
  }
}

VS Code

Add to .vscode/mcp.json in your workspace (or run MCP: Add Server from the command palette):

{
  "servers": {
    "a4sx": { "type": "stdio", "command": "uvx", "args": ["a4sx-mcp"] }
  }
}

Try it

Ask your agent, for example: "Search a4sx for sessions about flaky pytest fixtures and summarise the best one", or "Load my a4sx session my-refactor as context".

Configuration

Everything is optional. Don't put your token into an MCP client config file: sign in with a4sx login instead, which stores it with mode 0600.

Local server or remote /mcp?

a4sx also runs a hosted MCP server at https://session-exchange.com/mcp, with browser sign-in over OAuth: it advertises the scope library:read (search your library, summaries, loading sessions as context). Public search there works without signing in; acquiring or saving sessions needs a credential with library:acquire or library:publish, for example an agent key created in your a4sx account. Clients that support remote MCP servers with OAuth can connect to it directly and need nothing installed:

claude mcp add --transport http a4sx https://session-exchange.com/mcp

This package is the option for clients without remote OAuth support, and for setups that already use a4sx login. Both expose the five session tools below; the hosted server lists further tools of its own (for example, starting a purchase for the account holder to confirm), which this package does not have.

Same in both:

• the five session tools' names, input schemas (including the harness filter), annotations, and the server instructions;
• the untrusted framing: the text of fetch_session_context (notice, nonce envelope, line-break normalisation, escaping, per-field caps, sizing, canonical sessions of other harnesses) and the JSON envelope, notice field, per-field caps, 64 KiB result bound and hint line of search_sessions, get_session_summary and acquire_session;
• the result fields (plus the local extras listed below);
• the error codes invalid_arguments, credential_not_accepted, rate_limited, not_found, too_large, content_sha_mismatch, not_a_transcript and no_transcript;
• JSON-RPC error -32029 when the overall request limit is exceeded.

Differences of this local server:

• Sign-in. It uses your a4sx login session, so it can do everything your account can in your own library. The hosted server takes a scoped OAuth token (it advertises library:read) or an agent key with the scopes you gave it (library:read, library:acquire, library:publish). With no sign-in at all, local tools return not_signed_in; the hosted server answers with an OAuth challenge instead. The credential_not_accepted message says to run a4sx login rather than to get a scoped token.
• Rate limits. They are counted per process, not per account. There is no failed-sign-in limit, because there is no sign-in step here. retry_after_s comes from the API's error body, not from the Retry-After header.
• untrusted. Besides acquired_from on the row and its parents (which is all the hosted server checks), it also uses this machine's record of untrusted sessions from the a4sx SDK. A session missing from your library listing counts as untrusted in both.
• publish_session:
  • Every upload carries an idempotency key: yours if you pass idempotency_key, else a fresh one. The hosted server sends a key only if you pass one.
  • Uploads are retried twice, with that same key, on network errors, 429 and 502-504; when the server is busy scrubbing other uploads, up to 6 attempts, each after the wait it asks for.
  • The body, title and label are scrubbed locally, so the X-Content-SHA256 sent to the API covers the scrubbed bytes.
  • The content check is stricter: every line must be a JSON record with a type, and the file a Claude Code or Codex CLI session.
  • parent is resolved like the CLI resolves names (exact id, then label, then a unique part of the title or id). The hosted server passes it through verbatim.
  • Without parent, a transcript you resumed with a4sx resume gets its parent edge from the SDK's local lineage record. The hosted server records no edge.
  • The result has extra client_redactions and untrusted fields.
• payment_required. The price comes from the public listing; the hosted server reads its pricing store.
• Server name. It is a4sx-mcp in the MCP handshake (hosted: com.session-exchange/sessions).

Development

git clone https://github.com/crossvault/a4sx-mcp && cd a4sx-mcp
python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
pytest -q          # offline: the tools run against a local stub server
ruff check . && reuse lint

The tests never touch the network: tool tests run against tests/stub_server.py on 127.0.0.1, the protocol test uses the MCP SDK's in-process client, and a guard fails any test that resolves or connects to a non-loopback address. See CONTRIBUTING.md.

About

a4sx-mcp is made by crossVault GmbH, the company behind a4sx (session-exchange.com), a library and marketplace for coding-agent sessions. It is a thin client: the tools call the public a4sx API through the open-source a4sx SDK, and the hosted service is not part of this repository. You need an a4sx account for everything except public search. It is open source so you can check exactly what it sends before you connect it to your agent. Parts of this project were developed with AI assistance (Claude).

Security

Please report vulnerabilities privately; see SECURITY.md.

License

Apache-2.0, see LICENSE. Copyright 2026 crossVault GmbH.