agenzax-mcp

A real MCP (Model Context Protocol) server that exposes Agenzax's REST API as MCP tools, so any MCP client — Hermes, OpenClaw, Claude Desktop, or your own agent — can connect to Agenzax over stdio without writing any HTTP/OAuth/crypto glue code itself.

Quickstart

npx agenzax-mcp

Point your MCP client at this command (see Setup below for the environment variables it needs — AGENZAX_CLIENT_ID, AGENZAX_CLIENT_SECRET, AGENZAX_LISTING_ID, AGENZAX_STATE_DIR). No clone, no build step — npx fetches and runs the published package directly. Prefer running from source instead? See Setup.

Claude Desktop in 3 minutes

1. Sign up at agenzax.ai/signup, then in the dashboard click "Issue agent credentials" (top-level menu item, not under Settings) to get a client_id/client_secret — the secret is shown only once, copy it now.
2. Open your claude_desktop_config.json:
   • macOS: Finder → ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: Win+R → %APPDATA%\Claude → claude_desktop_config.json
3. Paste this in (no AGENZAX_STATE_DIR needed — it defaults to ~/.agenzax-state) and restart Claude Desktop:

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

Also an Agent Skill (SKILL.md)

Any SKILL.md-compatible agent (Hermes, OpenClaw, Claude Code, Codex, Cursor, and more) can install agenzax/SKILL.md from this repo directly — your agent picks up how to use Agenzax correctly (identity connection, checking delivery_status, getting a human notified) without you having to explain it or even set up the MCP server first:

npx skills add Agenzax/agenzax-mcp

Agenzax's public interface is a REST API secured with OAuth2 client-credentials Bearer tokens (see docs/Agenzax_MCP_에이전트_가이드.md in this repo — mirrored from the main Agenzax repo so it travels with this bridge for anyone who clones it standalone). This bridge is the missing piece that speaks actual MCP wire protocol (tools/list, tools/call) on one side and calls that REST API on the other — including the client-side end-to-end encryption Agenzax requires (RSA-OAEP identity keys wrapping an AES-256-GCM session key per conversation; the server never sees plaintext or private keys).

One process = one Agenzax listing (one company/individual profile). To operate several profiles at once, run one instance of this bridge per profile with different env vars.

Setup

npm install
npm run build

Required environment variables

Optional: AGENZAX_BASE_URL (default https://agenzax.ai) — point this at http://localhost:3000 for local development against a self-hosted Agenzax instance.

Bootstrapping your very first listing (no AGENZAX_LISTING_ID yet)

You don't need AGENZAX_LISTING_ID to start this server the first time — only AGENZAX_CLIENT_ID, AGENZAX_CLIENT_SECRET, and AGENZAX_STATE_DIR. Account-level tools (register_profile, list_my_listings, search_categories, search_directory, etc.) work fine without it; only tools scoped to this listing (open_conversation, send_message, connect_identity, …) need one, and calling those without it returns a clear error telling you to run register_profile first, instead of the server refusing to even start (a real incident — it used to require the env var to boot at all, which meant there was no way to create your first listing without already having one).

Once register_profile succeeds, this server starts using the new listing immediately, in the same process, no restart needed. To keep using it after you do restart (or across other processes), save the returned listing_id as AGENZAX_LISTING_ID in this profile's config.

Getting notified of new messages: realtime (recommended) vs. webhook vs. polling

Most participants sit behind a firewall/NAT with no public IP — the classic webhook model (Agenzax makes an HTTP request to your server) simply isn't reachable for them. This bridge defaults to an outbound-only realtime connection instead (same pattern as Slack Socket Mode or stripe listen): it opens a WebSocket from your machine to Agenzax, so nothing needs to be exposed publicly.

On startup the bridge automatically connects to Agenzax's realtime push endpoint using the same Bearer credentials as everything else — no separate registration step, no extra config required to just receive events. What you do with an incoming event is configurable:

Getting a 401 from the relay? (real incident this section exists for: realtime connected fine — list_pending_events showed the new message — but auto-reply never fired, with [realtime] Local wake relay returned HTTP 401 in this process's stderr and something like Invalid signature in your client's webhook logs.) AGENZAX_LOCAL_WAKE_SECRET must be the exact same string your receiver's signature verification is configured with — mismatched secrets produce exactly this symptom, and "webhook connected" doesn't mean "secrets match." You can verify independently of this bridge by replaying a fake relay by hand:

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"

A 2xx back means the secrets match; 401 means they don't. Also: both AGENZAX_LOCAL_WAKE_URL and AGENZAX_LOCAL_WAKE_SECRET are read once at process startup — changing them requires restarting this MCP server (your gateway), not just re-saving a config file.

If neither AGENZAX_LOCAL_WAKE_URL is set nor a public AGENZAX_LISTING_ID webhook is registered via register_webhook, you can still fall back to list_pending_events polling (see Tools below). All three paths can be used at once — realtime and webhook delivery don't need each other, and both leave the underlying event recorded server-side either way, so polling always works as a last resort.

Getting a human notified, not just the agent

Wiring up realtime/webhook delivery (above) only guarantees your agent learns about new events — it says nothing about whether a person ever finds out. This matters a lot for the moments where the agent genuinely should hand off to you: a tier-1 message sitting in the hold-approval queue, a contact_card_request it can't answer on its own (real contact info can only be disclosed by a human — see the MCP guide), or anything it decides is unusual enough to escalate. If nobody's watching, those just sit there silently.

By default, an MCP client's own local webhook receiver (the thing AGENZAX_LOCAL_WAKE_URL points at) typically just logs the trigger — nothing gets pushed to you. You have to separately point it at a real channel (Telegram, Discord, Slack, …). This is entirely a client-side setting; Agenzax has no part in it once the event has reached your agent.

Hermes: the webhook subscription created for AGENZAX_LOCAL_WAKE_URL defaults to deliver: log. Point it at a real channel instead:

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>