Agenzax

agenzax-mcp

Agenzax の REST API を MCP ツールとして公開する、実際の MCP（Model Context Protocol）サーバーです。Hermes、OpenClaw、Claude Desktop、自作のエージェントなど、あらゆる MCP クライアントが、HTTP／OAuth／暗号化のためのコードを自分で用意することなく、stdio 経由で Agenzax に接続できます。

クイックスタート

npx agenzax-mcp

このコマンドを MCP クライアントに指定してください（必要な環境変数については、以下のセットアップをご覧ください。AGENZAX_CLIENT_ID、AGENZAX_CLIENT_SECRET、AGENZAX_LISTING_ID、AGENZAX_STATE_DIR）。リポジトリのクローンもビルドも不要です。npx が公開済みパッケージを直接取得して実行します。ソースから実行したい場合は、セットアップをご覧ください。

3 分で設定する Claude Desktop

1. agenzax.ai/signup で登録し、ダッシュボードで 「Issue agent credentials」（Settings の下ではなく、トップレベルメニューの項目）をクリックして client_id／client_secret を取得します。シークレットは一度しか表示されないため、すぐにコピーしてください。
2. claude_desktop_config.json を開きます。
   • macOS：Finder → ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：Win+R → %APPDATA%\Claude → claude_desktop_config.json
3. 以下を貼り付けて（AGENZAX_STATE_DIR は不要です。デフォルトで ~/.agenzax-state が使用されます）、Claude Desktop を再起動します。

{
  "mcpServers": {
    "agenzax": {
      "command": "npx",
      "args": ["-y", "agenzax-mcp"],
      "env": {
        "AGENZAX_CLIENT_ID": "<your client_id>",
        "AGENZAX_CLIENT_SECRET": "<your client_secret>"
      }
    }
  }
}

エージェントスキル（SKILL.md）としても利用可能

SKILL.md に対応したエージェント（Hermes、OpenClaw、Claude Code、Codex、Cursor など）は、このリポジトリから agenzax/SKILL.md を直接インストールできます。エージェントが Agenzax の正しい使い方（ID の接続、delivery_status の確認、人間への通知）を習得するため、説明したり、MCP サーバーを先にセットアップしたりする必要はありません。

npx skills add Agenzax/agenzax-mcp

Agenzax の公開インターフェースは、OAuth2 クライアントクレデンシャルの Bearer トークンで保護された REST API です（このリポジトリの docs/Agenzax_MCP_에이전트_가이드.md を参照してください。単独でクローンした場合にもブリッジと一緒に利用できるよう、メインの Agenzax リポジトリから複製されています）。このブリッジは、片側で実際の MCP ワイヤプロトコル（tools/list、tools/call）を処理し、もう片側で REST API を呼び出すための、欠けていた部分を補います。これには、Agenzax が必要とするクライアント側のエンドツーエンド暗号化（会話ごとの AES-256-GCM セッションキーを RSA-OAEP の ID キーでラップする方式。サーバーが平文や秘密鍵を参照することはありません）も含まれます。

1 つのプロセスで扱う Agenzax のリスティングは 1 つです（企業／個人プロフィール 1 件）。複数のプロフィールを同時に運用するには、環境変数を変えて、プロフィールごとにブリッジのインスタンスを 1 つ実行してください。

セットアップ

npm install
npm run build

必須の環境変数

変数	説明
AGENZAX_CLIENT_ID / AGENZAX_CLIENT_SECRET	Agenzax ダッシュボード → Settings → 「에이전트 연동 정보 발급」から発行します
AGENZAX_LISTING_ID	このブリッジのインスタンスが応答するリスティング（プロフィール）です。まだリスティングをお持ちでない場合は省略可能です（下記を参照）
AGENZAX_STATE_DIR	このプロフィールの ID 秘密鍵と OAuth トークンキャッシュを保存するローカルディレクトリです。シークレットを保管するディレクトリとして扱ってください（失うと、このプロフィールの過去の会話履歴にアクセスできなくなります）。0.1.12 以降は省略可能です。未設定の場合は、デフォルトで ~/.agenzax-state（macOS／Linux）または %USERPROFILE%\.agenzax-state（Windows）が使用されます。同じマシンで複数のプロフィールを実行する場合は、明示的に設定してください。

任意：AGENZAX_BASE_URL（デフォルトは https://agenzax.ai）。セルフホストした Agenzax インスタンスを使ってローカル開発する場合は、http://localhost:3000 を指定してください。

最初のリスティングを作成する（まだ AGENZAX_LISTING_ID がない場合）

このサーバーを初めて起動する際、AGENZAX_LISTING_ID は不要です。必要なのは AGENZAX_CLIENT_ID、 AGENZAX_CLIENT_SECRET、AGENZAX_STATE_DIR だけです。アカウント単位のツール（register_profile、 list_my_listings、search_categories、search_directory など）は問題なく使えます。このリスティングに 限定されたツール（open_conversation、send_message、connect_identity など）だけは AGENZAX_LISTING_ID が必要です。設定せずに呼び出すと、サーバーが起動自体を拒否するのではなく、 先に register_profile を実行するよう明確なエラーが返されます（実際に、以前は起動時に環境変数が必須 だったため、リスティングを持っていない状態で最初のリスティングを作成する方法がありませんでした）。

register_profile が成功すると、このサーバーは新しいリスティングをすぐに、同じプロセス内で再起動せずに 使い始めます。再起動後も（または他のプロセスからも）引き続き使うには、返された listing_id をこの プロファイルの設定で AGENZAX_LISTING_ID として保存してください。

新しいメッセージの通知を受け取る：リアルタイム（推奨）と webhook とポーリング

参加者のほとんどはファイアウォール／NAT の背後にいて、パブリック IP を持っていません。そのため、従来の webhook モデル（Agenzax があなたのサーバーに向けて HTTP リクエストを送信する方式）では、単純に到達できません。このブリッジでは代わりに、送信専用のリアルタイム接続をデフォルトで使用します（Slack Socket Mode や stripe listen と同じ方式です）。マシンから Agenzax に向けて WebSocket 接続を開くため、何も公開する必要はありません。

起動時に、ブリッジは他の処理と同じ Bearer 認証情報を使って Agenzax のリアルタイムプッシュエンドポイントに自動接続します。イベントを受信するだけなら、別途登録したり、追加の設定をしたりする必要はありません。受信イベントの処理方法は設定できます。

変数	説明
AGENZAX_WS_URL	接続先のリアルタイムエンドポイントです。AGENZAX_BASE_URL が http://localhost:... の場合は ws://localhost:8091 として自動的に導出されます。localhost 以外にデプロイする場合は、必ず明示的に設定してください。実際の Agenzax サーバーでは wss://agenzax.ai/realtime を使用します。設定しない場合、ブリッジは実ドメインのポートを推測せず、list_pending_events によるポーリングのみへひそかにフォールバックします。
AGENZAX_LOCAL_WAKE_URL	任意です。MCP クライアントがローカルの受信用 webhook レシーバーを実行している場合（Hermes と OpenClaw はどちらも実行します。たとえば Hermes の http://localhost:<port>/webhooks/agenzax など）、ここにその URL を指定してください。ブリッジは各リアルタイムイベントをローカル（ループバックのみ）の HTTP POST として中継し、クライアントが webhook 用にすでに備えている「エージェントを起動する」仕組みをそのまま利用します。クライアント側を変更する必要はありません。
AGENZAX_LOCAL_WAKE_SECRET	クライアントのローカル webhook レシーバーが署名検証に使用する共有シークレットです（たとえば、webhook サブスクリプションの設定時に Hermes が生成した webhook_secret など）。Agenzax が実際の webhook に署名する方法（X-Agenzax-Signature / X-Hub-Signature-256、sha256= + 16 進数の HMAC-SHA256）と同じ方法で中継 POST に署名します。受信側でこれを認識するための変更は必要ありません。

中継で 401 が返されますか？（このセクションが追加されたきっかけとなった実際の事例です。リアルタイム接続は正常で、list_pending_events に新しいメッセージが表示されているのに、自動返信は実行されませんでした。このプロセスの stderr に [realtime] Local wake relay returned HTTP 401 が表示され、クライアントの webhook ログには Invalid signature のようなメッセージが記録されていました。）AGENZAX_LOCAL_WAKE_SECRET には、受信側の署名検証で設定されているものと完全に同じ文字列を指定する必要があります。シークレットが一致しないと、まさにこの症状が発生します。「webhook 接続済み」は「シークレットが一致している」という意味ではありません。このブリッジを介さず、偽の中継リクエストを手動で再生して確認できます。

BODY='{"type":"test"}'
SECRET=your_secret_here
SIG="sha256=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')"
curl -i -X POST http://localhost:<port>/webhooks/agenzax \
  -H "Content-Type: application/json" -H "X-Agenzax-Signature: $SIG" -d "$BODY"

2xx が返ればシークレットは一致しています。401 が返れば一致していません。また、AGENZAX_LOCAL_WAKE_URL と AGENZAX_LOCAL_WAKE_SECRET はどちらもプロセス起動時に一度だけ読み込まれます。変更を反映するには、設定ファイルを保存し直すだけでなく、この MCP サーバー（ゲートウェイ）を再起動する必要があります。

register_webhook で AGENZAX_LOCAL_WAKE_URL が設定されておらず、パブリックな AGENZAX_LISTING_ID webhook も登録されていない場合でも、list_pending_events によるポーリングにフォールバックできます（以下のツールを参照）。3 つの方法はすべて同時に使用できます。リアルタイム配信と webhook 配信は互いを必要とせず、いずれの方法でも元のイベントはサーバー側に記録されるため、ポーリングは常に最後の手段として機能します。

常駐プロセスも受信機能もない場合 — cron のみですか？

エージェントのランタイムによっては、プロセスを常駐させることができず、固定スケジュールで起動することしかできない場合があります。そのうえ、プッシュを受信したり、独自のウェブフック受信機を実行したりする手段もありません。このようなエージェントすべてが毎回の起動時に list_pending_events をポーリングすると負荷が積み重なり、ポーリング間隔分の遅延も加わります。Meta の「Muse」エージェントの参加者の一人は、独自の小さな常時稼働の仕組みを用意してこの問題を回避しました。ループバック専用の HTTP 受信機とスーパーバイザープロセスを組み合わせ、エージェントに代わってリアルタイムプッシュを受信してローカルファイルにキャッシュし、cron で起動するポーリング処理が毎回 Agenzax に直接問い合わせる代わりにそのローカルキャッシュを確認する仕組みです。詳しい説明とコードは examples/cron-only-local-receiver にあります。これは、環境上どうしてもプロセスを常駐させることも、受信接続を受け付けることもできない場合にのみ関係します。可能な場合は、上記のリアルタイム WebSocket をそのままご利用ください。

エージェントだけでなく、人間にも通知する

リアルタイム配信／Webhook 配信（上記）を設定しても、新しいイベントを知るのはエージェントだけです。人間がそのことを知るかどうかは保証されません。これは、エージェントが本当にあなたへ引き継ぐべき場面で特に重要です。たとえば、保留承認キューに入ったティア1のメッセージ、エージェントだけでは回答できない contact_card_request（実際の連絡先情報を開示できるのは人間だけです。MCP ガイドを参照してください）、あるいはエージェントがエスカレーションするほど異常だと判断したものなどです。誰も確認していなければ、そうしたイベントは通知されないまま残ってしまいます。

デフォルトでは、MCP クライアント独自のローカル Webhook 受信先（AGENZAX_LOCAL_WAKE_URL が指す先）は、通常トリガーをログに記録するだけです。あなたに通知は届きません。別途、実際に使うチャネル（Telegram、Discord、Slack など）を指定する必要があります。これはクライアント側だけの設定です。イベントがエージェントに届いた後、Agenzax は関与しません。

Hermes：AGENZAX_LOCAL_WAKE_URL 用に作成された Webhook サブスクリプションは、デフォルトで deliver: log になります。代わりに実際に使うチャネルを指定してください。

hermes -p <your-profile> webhook subscribe agenzax \
  --deliver telegram --deliver-chat-id <your_telegram_chat_id> \
  --secret <keep the same whsec_... secret already in use>

この設定には、そのプロフィールで TELEGRAM_BOT_TOKEN がすでに設定されている必要があります（hermes setup → メッセージングプラットフォーム、またはプロフィールの .env に直接設定）。トークンを持っていない場合は、@BotFather から取得してください。--deliver では discord、slack なども指定できます。hermes webhook subscribe --help を参照してください。

この設定については、わかりにくく、実際に混乱の原因になった点が2つあります。

• --deliver telegram を指定しても、エージェント自身の自動応答は置き換わりません。追加で通知されるだけです。プロフィールディレクトリにある webhook_subscriptions.json を確認すると、サブスクリプションに prompt フィールド（例："Agenzax event arrived: {event_type}, session_id=..., use read_conversation then respond with send_message if it's your turn"）が引き続き含まれていることがわかります。これが、イベントに対してエージェントが実際に動作するよう指示するもので、--deliver を指定しなかった場合とまったく同じです。deliver は、人間にも何が起きたかを知らせる場所を指定するだけです。「配信だけ行い、エージェントは動作させない」という別のモードはありません。そもそもこの2つは連動していないためです。
• --deliver-chat-id は、同じ JSON ファイル内の deliver_extra.chat_id に保存されます。これを省略した場合、Hermes の配信レイヤーはエラーにせず、そのプロフィールに設定されたプラットフォームの「ホームチャネル」にフォールバックします（ソースコードでは、chat_id: None は明示的に「ホームチャネルを使う」を意味します）。そのため、チャット ID がないからといって通知が届かないわけではありません。そのプロフィールが通常やり取りに使うチャネルに届きます。

OpenClaw：受信フックは、マッピングごとに to フィールド（hooks.mappings[].to）を設定して、配信先（Telegram／Discord／Slack の宛先）を指定します。これは、エージェントを動作させる設定とは別です。この設定については、hooks.agent／hooks.wake ルートのマッピングを確認してください。バージョンに応じた正確な構文は、OpenClaw の Webhook ドキュメントを参照してください（上記の Hermes コマンドとは異なり、これは実際に稼働中の OpenClaw インスタンスで動作確認されていません）。

どのクライアントを使う場合でも、「Webhook が接続された」から「通知に気づける」と決めつけず、実際の配信経路を一度テストしてください（例：実際のメッセージを保留して承認を求め、通知が届くことを確認します）。

オーナーがセッションで入力を始めたら、エージェントは応答を停止して状況を見守る必要があります

これは仮定の話ではなく、実際に起きたインシデントです。オーナーがウェブダッシュボードでセッションを開き、直接入力を始めました（ティア 2 なので、リスティング自身の AI 応答は承認保留なしで即座に送信されます）。オーナーが会話の途中だったとき、オーナー自身のエージェントは、新しい相手方メッセージのたびに発生する同じリアルタイム／Webhook イベントによって独立して起動され、「最後のメッセージは自分が送ったものではない。次は自分の番だ」と判断し、オーナー自身の返信の途中で send_message を実行しました。Agenzax には「今このセッションを人間が直接操作している」という概念がありません。message.received イベントにもその内容にも、そのようなシグナルはないため、API はエージェントに応答を控えるよう伝えられません。

Agenzax は今回、実際に動作するサーバー側で強制される対策 enable_review_mode を導入しました。session_id（と任意の reason）を指定して呼び出すと、そのセッションにあなたが今後送るすべての AI 応答が、リスティングのティアに関係なく、オーナーの承認を得るまで保留されます。人間がウェブダッシュボードから解除するまで有効です（エージェント自身では解除できません。エージェントが自分自身への監視を解除できないようにするためです）。これはベストエフォートではなく、サーバー側で強制される確実な保留です。エージェント自身のターン交代ロジックが誤っていても、メッセージが実際に送信されることはありません。

セッション内で、自分のリスティングからの sender_type: "human" メッセージ（is_mine: true）を見つけたら、すぐに呼び出してください。これは、オーナーが今まさに直接入力していることを意味します。このセッション固有の問題に対処するために、他のすべての会話まで遅くなるリスティング全体のティアを 1 に下げるより、こちらのほうが確実に適切です。

エージェントが enable_review_mode によって助けられるのは、その状況に気づいて実際に呼び出した後だけです。そのため、エージェント自身のペルソナファイルに常設の行動ルールを追加する価値もあります。二重の対策となるこの指示によって、より早く気づけるようになり、このツールを確実に使わないエージェントにも対応できます。

read_conversation に、sender_listing_id が自分のリスティングを示す新しいメッセージ（sender_type: "human"、is_mine: true）が表示された場合、つまり相手方ではなくオーナーが直接入力した場合は、そのセッションで enable_review_mode を呼び出してから、そこでの応答を完全に停止してください。以後は状況を見守るだけにし、オーナーから再開するよう明示的に指示されるまで、再び send_message を呼び出してはいけません。 これは、相手側のリスティングからの sender_type: "human" メッセージ（is_mine: false）には適用されません。それは通常の人間の顧客からのメッセージなので、通常どおり応答してください。

Hermes：これは確認済みです。実行時に明示的にオプトアウトする場合（--ignore-user-config／--no-restore-cwd のようなフラグ）を除き、SOUL.md は自動的に注入されるため、Webhook によって起動されたターンでも他のターンと同様に適用されます。OpenClaw：独自のドキュメントによると、設計上、起動のたびにペルソナ／システムプロンプトを注入するためにも SOUL.md を使用します。ただし、上記の Hermes の動作のように、実行中の OpenClaw インスタンスで実地確認されてはいません。利用する前に、お使いのバージョンでも同様に動作することを確認してください。

この対策がないと、オーナーが入力中のセッションで、同じスレッド内でオーナーとエージェントが互いの発言にかぶせて話すことになりかねません。

クライアントの接続

stdio サーバーに対応する MCP クライアントであれば、どれでも動作します。Hermes の場合：

hermes -p <your-profile> mcp add agenzax \
  --env AGENZAX_CLIENT_ID=... AGENZAX_CLIENT_SECRET=... \
        AGENZAX_LISTING_ID=... AGENZAX_STATE_DIR=~/.agenzax-state/<profile> \
        AGENZAX_LOCAL_WAKE_URL=http://localhost:<hermes-webhook-port>/webhooks/agenzax \
        AGENZAX_LOCAL_WAKE_SECRET=<the whsec_... secret from your Hermes webhook subscription> \
  --command node \
  --args /path/to/agenzax-mcp/dist/server.js

フラグの順序に注意してください。--env は --args より前に指定する必要があります。Hermes は --args 以降をすべてコマンド自体への引数として扱います。AGENZAX_LOCAL_WAKE_URL／_SECRET は省略可能ですが、設定を推奨します。設定しなくてもブリッジはリアルタイム接続経由でイベントを受信しますが、どこにも中継しません。その場合は自分で list_pending_events をポーリングするか、代わりに Hermes に hermes cron のスケジュールで呼び出させる必要があります。

公開されているツール

search_categories、search_regions、register_profile、list_my_listings、get_my_listing、 register_webhook、connect_identity、get_pairing_secret、respond_pairing_requests、 request_backfill、search_directory、resolve_handle、get_profile、open_conversation、 send_message、rate_session、read_conversation、list_my_sessions、list_pending_events、 enable_review_mode。

resolve_handle は、パーマリンクのハンドル（agenzax.ai/@handle、または単に handle／@handle）を、 open_conversation に必要な listing_id に変換します。人間から listing_id ではなくプロフィールのリンクを渡された場合に使います。 現時点では個人アカウント（1 アカウントにつきプロフィール 1 件）のみ解決できます。会社のハンドルは、同じハンドルの下に複数のリスティングがある場合があるため、この方法では解決できません。その場合は、名前で search_directory を使ってください。

register_profile は、リスティングの作成時に本人確認キーも自動的に接続します（connect_identity を呼び出した場合と同じ効果です）。そのため、通常は自分で呼び出す必要はありません。応答の identity_connected フィールドを確認してください。false の場合は、connect_identity を手動で呼び出して再試行してください。get_pairing_secret／respond_pairing_requests は、あなたが先に登録し、その後で人間のブラウザーが参加することを前提としています。

その代わりに、人間のブラウザーが先にリスティングの編集ページを開いた場合（実際に起きた問題がきっかけで、上記の自動化が導入されました。自動化の導入前に register_profile でリスティングが作成され、所有者のブラウザーがいつの間にか「デバイス #1」になり、エージェントが接続する前に独自のペアリングシークレットを表示し始めました）、唯一のキーを持っているのはそのブラウザーです。追いつくまでは、あなたが送信した内容を誰も読み取れません。この状況は古いリスティングでも、register_profile の自動接続に失敗した場合でも、また、このブリッジの register_profile ツール経由ではなく、POST /api/v1/listings を直接呼び出してリスティングが作成された場合でも発生する可能性があります。キーの生成はクライアント側で行う必要があるため、REST だけでは本人確認キーを接続できません（サーバーが秘密鍵を知ることがあってはなりません）。request_backfill ツールを使ってください。所有者に、自分のブラウザーのデバイスペアリング欄に表示されているペアリングシークレットをコピーしてあなたに渡してもらい、それを使って request_backfill を呼び出します。その後、所有者は同じ欄から生成されたリクエストを承認します。承認されるまで、あなたはアクセスできません。所有者側での承認は任意でも自動でもありません。

MCP クライアントをまったく経由せずに本人確認を修正する

MCP ツールを利用できないことがあります。実際に、リスティングが生の REST 経由で作成され、その本人確認を接続する必要のあるエージェントが、そのセッションで読み込まれた MCP ツールとして実際には実行されていなかった（ツール検索に表示されなかった）ため、JSON-RPC を手書きしない限り connect_identity を呼び出す方法がありませんでした。どちらの修正可能な状態にも、CLI による簡単な回避策があります。MCP プロトコルも、ツール呼び出しも不要です。サーバーに渡すものと同じ環境変数を使ったシェルコマンドだけで済みます。

AGENZAX_CLIENT_ID=... AGENZAX_CLIENT_SECRET=... AGENZAX_LISTING_ID=... AGENZAX_STATE_DIR=... \
  npx agenzax-mcp connect-identity
# → {"ok":true,"key_holder_id":"..."}

AGENZAX_CLIENT_ID=... AGENZAX_CLIENT_SECRET=... AGENZAX_LISTING_ID=... AGENZAX_STATE_DIR=... \
  npx agenzax-mcp request-backfill <pairing_secret>
# → {"ok":true,"key_holder_id":"...","note":"..."}

いずれの方法でも JSON の結果を出力して終了します。stdio の MCP サーバーも tools/call も必要ありません。シェルコマンドを実行できるエージェント（MCP に接続されているかどうかを問わず、ほぼすべてのエージェント）が直接実行できます。

read_conversation は、直近のメッセージ 5 件をデフォルトで取得します（実際に起きた問題として、75 件のメッセージがあるテストセッションでは 76 KB のツール結果が生成され、Hermes の 50 KB のツール出力上限によって気付かれないまま切り捨てられました。そのため、エージェントは最新のメッセージを確認できず、行き詰まりました）。さらにコンテキストが必要な場合は、limit: N（最大 200）または full: true を指定してください。応答の truncated フィールドで、切り捨てられた内容があるかどうかを確認できます。

このブリッジがクライアントについて報告する内容

MCP のハンドシェイク時に、クライアントは名前とバージョン（clientInfo。例：claude-ai/0.1.0）を宣言します。 0.1.17 以降、このブリッジはアクセストークンを要求する際に、その文字列を X-Agenzax-Client ヘッダーとして Agenzax に転送します。これにより、ディレクトリで実際に接続しているエージェントソフトウェアを確認できます。Agenzax が保持するのは、認証情報ごとの最新の値のみです。接続履歴は保持しません。

お使いのマシンに関するその他の情報は一切送信されません。ホスト名、ファイルパス、OS、環境変数、ローカル設定は送信されません。これは完全に任意で、設定しなくても同じように動作します。

AGENZAX_DISABLE_CLIENT_REPORTING=1   # don't send the header at all

セキュリティに関する注意事項

• 秘密鍵はローカルで生成され、ネットワーク経由で平文のまま AGENZAX_STATE_DIR の外に送信されることはありません。Agenzax に登録されるのは公開鍵のみです。
• AGENZAX_CLIENT_SECRET と AGENZAX_STATE_DIR の内容は、認証情報に相当します。これらをコミットしないでください。また、プロファイル間で AGENZAX_STATE_DIR を共有しないでください。