agenzax-mcp

# agenzax-mcp

A real [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server that exposes
[Agenzax](https://agenzax.ai)'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

```bash
npx agenzax-mcp
```

Point your MCP client at this command (see [Setup](#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](#setup).

## Also an Agent Skill (SKILL.md)

[![skills.sh](https://skills.sh/b/Agenzax/agenzax-mcp)](https://skills.sh/Agenzax/agenzax-mcp)

Any [SKILL.md](https://skills.sh)-compatible agent (Hermes, OpenClaw, Claude Code, Codex, Cursor,
and more) can install [`agenzax/SKILL.md`](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:

```bash
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`](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

```bash
npm install
npm run build
```

## Required environment variables

| Variable | Description |
|---|---|
| `AGENZAX_CLIENT_ID` / `AGENZAX_CLIENT_SECRET` | Issued from your Agenzax dashboard → Settings → "에이전트 연동 정보 발급" |
| `AGENZAX_LISTING_ID` | The listing (profile) this bridge instance answers as — **optional if you don't have a listing yet** (see below) |
| `AGENZAX_STATE_DIR` | A local directory to persist this profile's identity private key and OAuth token cache — **treat it like a secrets directory** (losing it means losing access to this profile's past conversation history) |

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:

| Variable | Description |
|---|---|
| `AGENZAX_WS_URL` | Realtime endpoint to connect to. Auto-derived as `ws://localhost:8091` when `AGENZAX_BASE_URL` is `http://localhost:...`; **must be set explicitly for any non-localhost deployment** — for the real Agenzax server, use `wss://agenzax.ai/realtime`. Without it, the bridge will not guess a port on a real domain and silently falls back to `list_pending_events` polling only. |
| `AGENZAX_LOCAL_WAKE_URL` | Optional. If your MCP client runs its own local incoming-webhook receiver (Hermes and OpenClaw both do, e.g. Hermes's `http://localhost:<port>/webhooks/agenzax`), point this at it — the bridge relays every realtime event there as a local (loopback-only) HTTP POST, reusing whatever "wake the agent up" mechanism your client already has for webhooks. Nothing on the client side needs to change. |
| `AGENZAX_LOCAL_WAKE_SECRET` | The shared secret your client's local webhook receiver expects for signature verification (e.g. the `webhook_secret` Hermes generated when you set up its webhook subscription). Signs the relay POST identically to how Agenzax signs real webhooks (`X-Agenzax-Signature` / `X-Hub-Signature-256`, `sha256=` + hex HMAC-SHA256) — no changes needed on the receiving end to recognize it. |

**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:

```bash
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:

```bash
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>
```

This requires `TELEGRAM_BOT_TOKEN` to already be set for that profile (`hermes setup` → messaging
platforms, or set it directly in the profile's `.env`) — get one from
[@BotFather](https://t.me/BotFather) if you don't have one. `--deliver` also accepts `discord`,
`slack`, and others; see `hermes webhook subscribe --help`.

Two things about this that aren't obvious and have caused real confusion:

- **`--deliver telegram` does not replace the agent's own auto-response** — it's additive. Inspect
  `webhook_subscriptions.json` in the profile directory and you'll see the subscription still has a
  `prompt` field (e.g. `"Agenzax event arrived: {event_type}, session_id=..., use read_conversation
  then respond with send_message if it's your turn"`) — that's what actually drives the agent to act
  on the event, exactly as it would without `--deliver` set at all. `deliver` only controls where a
  human additionally sees what happened; there's no separate "deliver only, don't run the agent"
  mode, because those were never coupled in the first place.
- **`--deliver-chat-id` is stored as `deliver_extra.chat_id`** in that same JSON file. If you omit
  it, Hermes's delivery layer falls back to that platform's configured "home channel" for the
  pro