a4sx sessions

a4sx-mcp

a4sx 用のローカル MCP サーバーです。a4sx はコーディングエージェントのセッション向けライブラリ兼マーケットプレイスです。Claude Code、Claude Desktop、Cursor、VS Code など、あらゆる MCP クライアントで 5 つのツールを利用し、保存済みのセッションを検索してコンテキストとして読み込んだり、現在のセッションを保存したりできます。サインインには a4sx コマンドラインツールの認証情報を使用します。

このサーバーは、お使いのマシン上で stdio 経由で動作します。a4sx トークンは a4sx の設定ディレクトリに保持され、発行元のサーバーにのみ送信されます。--base でサーバーの接続先を変更しても、別のサーバーのトークンが送信されることはありません。

プライベートライブラリ：session-exchange.com の a4sx アカウントに保存したセッションです。ライブラリ内のエントリはマーケットプレイスに掲載されず、公開検索の結果にも表示されません。ご自身のサインイン情報（または作成したエージェントキー）を使い、a4sx API 経由で一覧表示、取得、バージョン管理、削除できます。セッションをマーケットプレイスに掲載するには、Web アプリで審査を受ける別の手順が必要です。「プライベート」とは、a4sx を通じてエントリを一覧表示・取得できるユーザーを指します。サーバーは、アップロードされたデータを再度サニタイズしたうえで保存します。

ツール

ツール名、入力スキーマ、制限は、ホスト型 a4sx MCP サーバーと同じです。

ツール	機能	サインイン
search_sessions	審査済みの公開セッション（scope=public、デフォルト）または保存済みの自分のセッション（scope=library）を検索します。harness を指定すると、指定したハーネスで記録されたセッションに絞り込めます	ライブラリスコープの場合のみ
get_session_summary	セッションを使用する前に、概要、メンバー、価格、来歴を確認します	ライブラリのソースのみ
acquire_session	利用資格のあるマーケットプレイスのセッション（無料、購入済み、または付与されたもの）をプライベートライブラリにコピーします	必要
fetch_session_context	ライブラリのセッションを開始時のコンテキストとして読み込みます。max_tokens で長さを調整できます（500～100,000、デフォルトは 8,000）	必要
publish_session	トランスクリプト（JSONL）をプライベートライブラリに保存します	必要

安全性に関するルール：

• acquire_session は購入しません。 購入も付与もされていない有料の掲載については、価格と掲載 URL を含む status: "payment_required" を返します（掲載のセッションが単独で販売されている場合は、購入する member を返します）。ウェブアプリでご自身で購入してから、もう一度リクエストしてください。
• ハーネス。 Claude Code、Codex CLI、Grok Build のセッションは同様に一覧表示され、読み込まれます。現在、再開できるのは Claude Code のセッションのみです。すべての検索結果と概要の行には、記録時の harness（{id, version}。特定できない場合は unknown）が含まれます。また、別のハーネスで記録されたセッションの resumable は false です。fetch_session_context は、そのようなセッションを保存された正規形式からレンダリングします。
• publish_session は非公開で保存するだけです。 visibility が受け付けるのは "private" のみです。セッションの一般公開は、ウェブアプリで別途審査を経て行います。受け付けるのは Claude Code または Codex CLI の JSONL のみです（各行が type を持つレコードであり、Claude Code の場合はセッション ID を含むユーザーまたはアシスタントのターン、Codex CLI の場合は最初に session_meta レコードが必要です）。そのため、任意のファイルのアップロードには使用できません。トランスクリプト、そのタイトル、ラベルは、a4sx SDK を使ってお使いのマシン上でサニタイズされます。この SDK は a4sx CLI のルール（シークレット、コマンドラインのパスワード、Sheet ID、個人データ：メールアドレスと IP アドレス、ホームディレクトリのユーザー名、ホスト、鍵ファイルのパス）を適用し、その後サーバーでも再度サニタイズされます。サニタイズは最後の防衛策であり、保証ではありません。他の人のセッションを継承したセッション（その parent、またはそこから再開したセッションが取得済みの場合）は、信頼できないものとしてマークされたままです（untrusted: true）。
• どちらのツールも、プロトコル内で確認を求めません。 ホスト型サーバーと同様、上記のルールとツールのアノテーションに依存します。acquire_session と publish_session は readOnlyHint: false とマークされているため、ツールの実行前に確認を求めるクライアント（Claude Code はデフォルトで確認します）は確認を求めることができます。これらを自動承認しないでください。3 つの読み取りツールは読み取り専用とマークされています。
• 読み込んだセッションは参考資料であり、指示ではありません。 fetch_session_context は必ずその旨を示す通知から始まり、その後、セッション作成者が制御できるすべての内容（タイトルとターン）をランダムな nonce を使った <<<A4SX_UNTRUSTED_SESSION nonce=…>>> … <<<END_A4SX_UNTRUSTED_SESSION nonce=…>>> で囲みます。その内部では、あらゆる種類の改行が \n に正規化され、<<</>>> は ‹‹‹/››› に、行頭の # は \# に置き換えられます（通知でも説明しています）。そのため、内容が囲みを閉じたり、偽の ### User 見出しを作ったりすることはできません。タイトルは 200 文字以内の 1 行で、max_tokens に合わせて切り詰めても通知や閉じ行が削除されることはありません。search_sessions と get_session_summary の結果も同様に囲まれます。まず通知があり、その後に囲み内の JSON が続きます。作成者が記述した文字列はすべて 1 行にまとめられ、無害化され、フィールドごとに上限が設けられます。また、結果全体は 64 KiB 以下に制限されます（ページが途中で切れた場合は truncated: true と表示され、next_offset から除外された最初の行を取得できます）。サーバーのガイダンス（next、next_offset）は、閉じ区切りの後の 1 行に記載され、囲みの内側には入りません。また、固定テキストと数値のみを含みます。他の作成者の内容を含むセッションには untrusted: true が設定され、より強い通知が付加されます。見た目が似ている文字（全角の ＜/＃、ゼロ幅スペース）はそのまま残ります。閉じ行にはランダムな nonce が必要なため、これらの文字で囲みを閉じることはできませんが、モデルが誤解する可能性はあります。これによりプロンプトインジェクションのリスクは軽減されますが、完全に排除できるわけではありません。ツールの承認は有効にしておいてください。
• 制限： publish_session 1 回あたりのトランスクリプトは最大 2 MiB です（それを超える場合は a4sx push を使用してください）。プロセスごとに、リクエスト（tools/list と tools/call）は最大 240 件、取得は 20 件、公開は 1 分あたり 10 件です。a4sx サーバーにも独自の制限があります。

クイックスタート

uv（uvx用）とa4sxアカウントが必要です。

1. a4sx CLIで一度サインインします。MCPサーバーはそのサインイン情報を再利用します。

   uvx a4sx login
   

   公開セッションの検索は、サインインしなくても利用できます。アカウントが必要なツールで、サインインしていない場合（またはサインインの有効期限が切れている場合）は、a4sx loginを実行するよう促すエラーが返されます。

2. サーバーをクライアントに追加します。

Claude Code

claude mcp add a4sx -- uvx a4sx-mcp

Claude Desktop

claude_desktop_config.jsonを編集し（Settings、Developer、Edit Config）、Claude Desktopを再起動します。

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

Cursor

~/.cursor/mcp.json（すべてのプロジェクト）または.cursor/mcp.json（1つのプロジェクト）に追加します。

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

VS Code

ワークスペースの.vscode/mcp.jsonに追加するか、コマンドパレットからMCP: Add Serverを実行します。

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

試してみる

エージェントに、たとえば次のように尋ねてください。「a4sxで、flakyなpytest fixtureに関するセッションを検索し、最適なものを要約して」、または*「a4sxのセッションmy-refactorをコンテキストとして読み込んで」*。

設定

すべて任意です。トークンをMCPクライアントの設定ファイルに入れないでください。代わりにa4sx loginでサインインすると、モード0600で保存されます。

設定	意味
--base URL / A4SX_BASE	a4sxサーバーです。デフォルトは、サインイン先のサーバー、またはサインインしていない場合はhttps://session-exchange.comです。localhost以外では、プレーンなhttpは拒否されます。
A4SX_SESSION、A4SX_SESSION_BASE	保存済みのサインイン情報の代わりに使用するトークン（CI用）と、そのトークンが属するサーバー（デフォルトはhttps://session-exchange.com）です。
A4SX_CONFIG_DIR	a4sx CLIがサインイン情報を保存する場所です（デフォルトは~/.config/a4sx、Windowsでは%APPDATA%\a4sx）。
A4SX_MCP_LOG	warning（デフォルト）、info、またはdebugです。ログはstderrに出力され、ツール名、結果、所要時間のみを含みます。引数、トランスクリプト、トークンは含まれません。
A4SX_MCP_MAX_PUBLISH_BYTES	2 MiBのpublish_session上限を引き下げる、または引き上げます（サーバーがさらに大きなアップロードを拒否する場合があります）。
A4SX_MCP_PER_MIN、A4SX_MCP_ACQUIRE_PER_MIN、A4SX_MCP_PUBLISH_PER_MIN	ローカルのレート制限（1分あたり240、20、10回）です。0にすると、ローカルの制限が無効になります。

ローカルサーバー、それともリモートの/mcp？

a4sx は、https://session-exchange.com/mcp でホスト型の MCP サーバーも提供しています。OAuth を使ったブラウザーでのサインインに対応しており、library:read スコープを公開しています（ライブラリの検索、要約、セッションのコンテキストとしての読み込み）。サインインしなくても、そこで公開検索を利用できます。セッションの取得や保存には、library:acquire または library:publish の権限を持つ認証情報が必要です。たとえば、a4sx アカウントで作成したエージェントキーが使えます。OAuth 対応のリモート MCP サーバーに接続できるクライアントは、インストール不要で直接接続できます。

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

このパッケージは、リモート OAuth に対応していないクライアントや、すでにa4sx loginを使っている環境向けの選択肢です。どちらも、以下の5つのセッションツールを提供します。ホスト型サーバーには、アカウント所有者が確認する購入の開始など、独自のツールもありますが、このパッケージにはありません。

両方に共通するもの：

• 5つのセッションツールの名前、入力スキーマ（harnessフィルターを含む）、アノテーション、サーバーの指示；
• 信頼できないデータのフレーミング：fetch_session_contextのテキスト（通知、nonce エンベロープ、改行の正規化、エスケープ、フィールドごとの上限、サイズ調整、他のハーネスの正規セッションに関する説明）、およびsearch_sessions、get_session_summary、acquire_sessionの JSON エンベロープ、noticeフィールド、フィールドごとの上限、64 KiB の結果上限、ヒント行；
• 結果フィールド（以下に記載するローカル固有の追加項目を除く）；
• エラーコードinvalid_arguments、credential_not_accepted、rate_limited、not_found、too_large、content_sha_mismatch、not_a_transcript、no_transcript；
• リクエスト全体の上限を超えた場合の JSON-RPC エラー-32029。

このローカルサーバーの違い：

• サインイン。 a4sx loginのセッションを使うため、自分のライブラリでアカウントができる操作はすべて実行できます。ホスト型サーバーでは、スコープ付き OAuth トークン（library:readを公開）または、指定したスコープ（library:read、library:acquire、library:publish）を持つエージェントキーを使用します。まったくサインインしていない場合、ローカルツールはnot_signed_inを返します。ホスト型サーバーは代わりに OAuth チャレンジを返します。credential_not_acceptedのメッセージでは、スコープ付きトークンの取得ではなく、a4sx loginの実行を案内します。
• レート制限。 アカウント単位ではなく、プロセス単位でカウントされます。このサーバーにはサインイン手順がないため、サインイン失敗の上限はありません。retry_after_sの値は API のエラーボディーから取得し、Retry-Afterヘッダーからは取得しません。
• untrusted。 行とその親に対するacquired_fromの確認（ホスト型サーバーが行う確認のすべて）に加え、a4sx SDK に記録された、このマシン上の信頼できないセッションの情報も使います。ライブラリの一覧にないセッションは、どちらの場合も信頼できないものとして扱われます。
• publish_session：
  • アップロードにはすべて冪等性キーが付与されます。idempotency_keyが渡された場合はその値を使い、渡されなかった場合は新しいキーを生成します。ホスト型サーバーは、キーが渡された場合にのみ送信します。
  • ネットワークエラー、429、502～504 の場合、同じキーを使ってアップロードを2回再試行します。サーバーがほかのアップロードをスクラブしていてビジーの場合は、サーバーから指示された待機時間の後に最大6回試行します。
  • 本文、タイトル、ラベルはローカルでスクラブされるため、API に送信されるX-Content-SHA256はスクラブ済みのバイト列を対象にします。
  • コンテンツチェックはより厳格です。各行がtypeを含む JSON レコードであり、ファイルが Claude Code または Codex CLI のセッションでなければなりません。
  • parentは、CLI が名前を解決する方法と同様に解決されます（一致する ID、次にラベル、最後にタイトルまたは ID の一意な部分）。ホスト型サーバーはそのまま渡します。
  • parentが指定されていない場合、a4sx resumeで再開したトランスクリプトの親エッジは、SDK のローカル系譜レコードから取得されます。ホスト型サーバーはエッジを記録しません。
  • 結果には、追加でclient_redactionsとuntrustedフィールドが含まれます。
• payment_required。 価格は公開リストから取得します。ホスト型サーバーは価格ストアを参照します。
• サーバー名。 MCP ハンドシェイクではa4sx-mcpです（ホスト型：com.session-exchange/sessions）。

VS Code 拡張機能

vscode/ ディレクトリには、VS Code 1.101 以降に対応する a4sx 拡張機能があります。VS Code のチャットでエージェントモードを使用する際に、ホスト型 a4sx MCP サーバーを利用できるようにします。サインインは VS Code が実行します。サイドバーでは a4sx にサインインし、ライブラリ内のセッションを一覧表示して（ターミナルで再開するか、ウェブで開けます）、マーケットプレイスを検索できます。コマンド a4sx: Save this session は、ターミナルで a4sx push --latest を実行し、直近で変更したローカルの Claude Code セッションを a4sx ライブラリに保存します。保存したセッションを続けるには Claude Code を使用してください。現在、ほかのハーネスではセッションを再開できません。

この拡張機能は、まだ Visual Studio Marketplace では公開されていません。ソースからビルドしてテストするには、次の手順を実行してください。

cd vscode
npm install
npm run compile
npm test

MCP レジストリ

server.json は、このサーバーについて MCP Registry 向けに記述しています。対象は、ホスト型サーバー https://session-exchange.com/mcp（Streamable HTTP）と、PyPI 上のこのパッケージ（a4sx-mcp、stdio）です。名前には com.session-exchange/sessions を使用しており、ホスト型サーバーはすでにこの名前で登録されています。

開発

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

テストでネットワークにアクセスすることはありません。ツールのテストは 127.0.0.1 上の tests/stub_server.py を使用し、プロトコルテストは MCP SDK のインプロセスクライアントを使用します。また、ループバック以外のアドレスを解決または接続しようとするテストは、ガードによって失敗します。CONTRIBUTING.md を参照してください。

概要

a4sx-mcp は、コーディングエージェントのセッション向けライブラリ兼マーケットプレイスである a4sx (session-exchange.com) を運営する crossVault GmbH が開発しています。これは薄いクライアントです。ツールはオープンソースの a4sx SDK を通じて公開 a4sx API を呼び出し、ホスト型サービスはこのリポジトリに含まれていません。公開検索を除くすべての機能には、a4sx アカウントが必要です。オープンソースなので、エージェントに接続する前に、送信内容を正確に確認できます。このプロジェクトの一部は AI の支援を受けて開発されました（Claude）。

セキュリティ

脆弱性は非公開で報告してください。詳しくは SECURITY.md を参照してください。

ライセンス

Apache-2.0。詳しくは LICENSE を参照してください。Copyright 2026 crossVault GmbH.