Documentation

Two ways in — MCP for agents, CLI for humans and scripts. Same capabilities, different shape.

Two ways in

MCP · For AI agents

One HTTPS endpoint. Tools are discovered at runtime, nothing to install.

CLI · For humans & scripts

Four npm binaries with explicit flags, exit codes and JSON output.

Both surfaces expose the same business capabilities and field semantics. Admin and payment operations are direct MCP tools; merchant nouns and verbs are reached through progressive discovery.

Quick Start

Control plane first — sign in, create a developer, mint an API key. The runtime CLIs then work with that key.

agenzo-cli

❯npm install -g @agenzo/admin-cli @agenzo/token-cli @agenzo/payment-cli @agenzo/merchant-cli

Install the four CLIs (Node.js 22+)

❯agenzo-admin-cli auth login --email you@example.com --idempotency-key login-001

❯

agenzo-admin-cli developers create --developer-name "my-bot" --developer-email you@example.com --bank-beneficiary-name "My Agent LLC" --bank-account-number 1234567890123456 --bank-name "Test Bank" --bank-country US --bank-swift-code TESTUS33 --idempotency-key dev-001

Create a developer (bank details required)

❯

agenzo-admin-cli keys create --developer-id <dev_id> --key-name "Prod Key" --scope token,merchant,payment --idempotency-key key-001

Mint an API key — shown once, save it

❯agenzo-token-cli payment-methods add --api-key <key> --email you@example.com --idempotency-key pm-001

Add a payment method and complete verification

❯agenzo-token-cli --yes payment-tokens create --type vcn --api-key <key> --amount 30 --idempotency-key idem_001

Mint a $30 virtual card

❯agenzo-payment-cli payments capture --api-key <key> --payment-token-id <ptk_id> --idempotency-key chg_001 --yes

Charge that token

❯agenzo-merchant-cli services list --api-key <key>

Discover the merchant capabilities you can fulfil

Full reference below ↓

MCP

The platform speaks MCP over Streamable HTTP, so an agent reaches the same capabilities as the CLI without installing anything. Point any MCP client at the endpoint and send your credential as a header.

Endpoint — `https://agent.agenzo.com/mcp/` (the trailing slash is required, otherwise the handshake fails)
Transport — Streamable HTTP
Production discovery — all capabilities exposed; admin and payment are direct tools, merchant is progressive
Runtime auth — `X-Api-Key: <api key>` for merchant, payment-method, payment-token and capture capabilities
Admin auth — `Authorization: Bearer <access_token>` for control-plane operations. The token expires; refresh it with `agenzo-admin-cli auth login`

Two tool shapes

Production runs full exposure with hybrid discovery. Groups whose capability set is fixed are listed as ordinary tools; merchant services, which grow as providers onboard, are discovered on demand — so the tool list stays small.

Direct tools — admin & payment

Listed individually as `<service>__<verb>` with full parameter schemas. Call them in one step, no drill-down.

orgs__get · developers__create · keys__create · accounts__get · payment_methods__add · payment_tokens__create · payments__capture

Progressive discovery — merchant

Fulfilment services sit behind four meta tools. Always start at list_services and follow each step's hint — do not guess service ids or verbs.

list_services() → describe_service(service) → describe_tool(service, verb) → invoke(service, verb, arguments)

Client configuration

Most MCP clients take a JSON config. Include both headers when one client needs the full surface; the Bearer token expires and must be refreshed with the admin CLI. Clients that require the transport to be named add `"type": "http"` — there is no `transport` key, and clients that validate strictly reject it.

mcp.json

{
  "mcpServers": {
    "agenzo": {
      "url": "https://agent.agenzo.com/mcp/",
      "headers": {
        "X-Api-Key": "<runtime api key>",
        "Authorization": "Bearer <admin access token>"
      }
    }
  }
}

Arguments — snake_case, and the same nested JSON shape as the REST body
Writes — require `idempotency_key`; reuse the same value to retry without duplicating an order or a charge
Errors — returned as `[<code>] <message>`, e.g. `[1001]` for an invalid request

Installation

Requires Node.js 22+. `agenzo-admin-cli` is the control plane and signs in with a Bearer token; `agenzo-token-cli`, `agenzo-payment-cli` and `agenzo-merchant-cli` are runtime planes and take `--api-key` per command.

❯ npm install -g @agenzo/admin-cli @agenzo/token-cli @agenzo/payment-cli @agenzo/merchant-cli

added 4 packages in 6s

Authentication

Login

Sign in via magic link, then click the link in your inbox. First-time emails are auto-registered and prompt for an organization name; if registration requires an invitation code the CLI asks for it. Credentials are stored under `~/.agenzo-admin-cli/`.

❯ agenzo-admin-cli auth login --email you@example.com --idempotency-key login-001

ℹ Magic link sent to you@example.com
⠋ Waiting for verification...
✓ Logged in as Acme Corp (org_01HZ...)

Logout

Sign out of the current organization and drop the local credentials. Signing back in needs another magic link.

❯ agenzo-admin-cli auth logout

✓ Logged out from Acme Corp
  Local credentials removed

Configuration

Set API host

Point the CLI at another environment. Accepts a full URL or a profile name. Default: `https://agent.agenzo.com` (production).

❯ agenzo-admin-cli config set-host https://agent-dev.agenzo.com

✓ API host updated
  Host        https://agent-dev.agenzo.com

Show configuration

Display the current API host and the active organization.

❯ agenzo-admin-cli config show

  API Host    https://agent.agenzo.com
  Active Org  org_01HZ... (Acme Corp)

Reset API host

Return the API host to the production default.

❯ agenzo-admin-cli config reset-host

✓ API host reset
  Host        https://agent.agenzo.com

Organizations

View current organization

Show the name, id, email and status of the active organization.

❯ agenzo-admin-cli orgs get

  ID          org_01HZ...
  Name        Acme Corp
  Email       admin@acme.com
  Status      ACTIVE

Update organization

Renaming takes effect immediately. Changing the email requires confirming a verification link.

❯ agenzo-admin-cli orgs update --name "New Name" --idempotency-key org-name-001

✓ Organization updated
  Name        New Name

❯ agenzo-admin-cli orgs update --email new@example.com --idempotency-key org-email-001

ℹ Verification email sent to new@example.com

List organizations

List every organization signed in locally. The active one is marked with *.

❯ agenzo-admin-cli orgs list

  ID              Name            Status
* org_01HZ...     Acme Corp       ACTIVE
  org_02AB...     Beta Inc        ACTIVE

Switch organization

Change the active organization. The target must already be signed in locally.

❯ agenzo-admin-cli orgs switch <org_id>

✓ Switched to Beta Inc (org_02AB...)

Developers

Bank details are mandatory for every developer regardless of billing mode — they are the payout target. Missing flags are prompted interactively; under `--yes` a missing one fails with `PARAM_INVALID`.

Create a developer

Required: `--developer-name`, `--developer-email`, and the bank group (`--bank-beneficiary-name`, `--bank-account-number`, `--bank-name`, `--bank-country`, `--bank-swift-code`). Optional: `--billing-mode` (`pay_per_call` default, or `monthly_settlement`, which provisions a settlement account). Returns the `developer_id` you need for keys.

❯ agenzo-admin-cli developers create --developer-name "my-bot" --developer-email agent@example.com --bank-beneficiary-name "My Agent LLC" --bank-account-number 1234567890123456 --bank-name "Test Bank" --bank-country US --bank-swift-code TESTUS33 --idempotency-key dev-001

✓ Developer created
  ID          dev_01HZ...
  Name        my-bot
  Bank        ************3456
  Status      ACTIVE

List developers

List the developers under the active organization. One email can back only one developer per organization.

❯ agenzo-admin-cli developers list

  ID              Name            Email               Status
  dev_01HZ...     my-bot          agent@example.com   ACTIVE

Get developer details

Show one developer in full. The bank account number is always masked to the last four digits.

❯ agenzo-admin-cli developers get <developer_id>

  ID          dev_01HZ...
  Name        my-bot
  Billing     pay_per_call
  Bank        ************3456

Update a developer

Update the name or email. The stored bank account is left alone unless you pass a `--bank-*` flag — then the whole account is replaced, so every required bank field must resolve.

❯ agenzo-admin-cli developers update <developer_id> --name "New Name" --idempotency-key dev-update-001

✓ Developer updated
  Name        New Name

API Keys

Keys are bound to a developer: tokens and cards created with one key are invisible to another. The key format is `sk_<env>_...` — `sk_prod_` in production, `sk_test_` elsewhere.

Create an API key

Required: `--developer-id` and `--key-name`. `--scope` is a comma-separated subset of `token`, `merchant`, `payment` and defaults to all three. The full key is printed once — save it.

❯ agenzo-admin-cli keys create --developer-id <dev_id> --key-name "Prod Key" --scope token,merchant,payment --idempotency-key key-001

✓ API key created
  ID          key_01HZ...
  Scope       token,merchant,payment

⚠ Save this key now. You will not see it again.
  Key         sk_prod_a1b2c3d4...

List API keys

List a developer's keys. Only prefixes are returned, never the full value.

❯ agenzo-admin-cli keys list --developer-id <dev_id>

  ID              Name          Prefix              Status
  key_01HZ...     Prod Key      sk_prod_a1b2...     ACTIVE

Get API key details

Show one key's prefix, scope, status and last use.

❯ agenzo-admin-cli keys get <key_id>

  ID          key_01HZ...
  Prefix      sk_prod_a1b2...
  Scope       token,merchant,payment
  Status      ACTIVE

Rotate an API key

Issue a new secret for an existing key. The old secret stops working immediately.

❯ agenzo-admin-cli keys rotate <key_id> --idempotency-key key-rotate-001

✓ API key rotated

⚠ Save this key now. You will not see it again.
  Key         sk_prod_n3w5ecr3t...

Disable an API key

Permanently disable a key.

❯ agenzo-admin-cli keys disable <key_id> --idempotency-key key-disable-001

✓ API key disabled
  ID          key_01HZ...

Settlement Accounts

Query a settlement account

Auto-created for `monthly_settlement` developers; returns `account: null` for `pay_per_call` ones (a read, not an error). `balance` is in minor units as a string.

❯ agenzo-admin-cli accounts get --developer-id <dev_id>

  Developer   dev_01HZ...
  Balance     3000000
  Currency    CNY

Payment Methods

Runtime plane — every command takes `--api-key` (sent as `X-Api-Key`). Adding a payment method is asynchronous: the CLI prints a URL, the cardholder completes the browser step, and the CLI polls to a terminal status.

Add a payment method (3DS)

Prompts for card number, expiry (MMYY) and CVV, then returns a `verification_url` the cardholder opens in a browser for 3DS. The process polls until the card is ACTIVE, so keep it alive. `--mode dropin` runs the hosted Drop-in flow instead, with no card details at the terminal.

❯ agenzo-token-cli payment-methods add --api-key <key> --email user@example.com --idempotency-key pm-add-001

  ID                pm_01HZ...
  Status            PENDING
  Verification URL  https://...
⠋ Waiting for 3DS...
✓ Payment method ACTIVE

Add a payment method (UnionPay)

`--payment-brand unionpay` starts enrollment without collecting card details in the terminal. Open the returned `enroll_url`, complete passkey authentication, then let the command poll or run `unionpay-status` later. `--member` is required and caller-defined; reuse the same value for this user.

❯ agenzo-token-cli payment-methods add --payment-brand unionpay --member <member_id> --api-key <key> --email user@example.com

  ID            pm_01HZ...
  Status        PENDING
  Enroll URL    https://...
⠋ Polling every 5s...
✓ Card ACTIVE (UnionPay ****1234)

❯ agenzo-token-cli payment-methods unionpay-status <pm_id> --api-key <key>

List payment methods

List added payment methods, optionally scoped to one member. Both brands share the same field shape, with `payment_brand` telling them apart.

❯ agenzo-token-cli payment-methods list --api-key <key>

  ID              Brand        Last Four   Status
  pm_01HZ...      Mastercard   6789        ACTIVE
  pm_02AB...      UnionPay     1234        ACTIVE

❯ agenzo-token-cli payment-methods list --api-key <key> --member <member_id>

Get payment method details

Show one card. Use it to check verification status later if a poll timed out (PENDING → ACTIVE or FAILED).

❯ agenzo-token-cli payment-methods get <pm_id> --api-key <key>

  ID          pm_01HZ...
  Brand       UnionPay
  Last Four   1234
  Status      ACTIVE

Disable a payment method

Disable a card and cascade-revoke every active payment token under it.

❯ agenzo-token-cli payment-methods disable <pm_id> --api-key <key> --idempotency-key pm-disable-001

✓ Payment method disabled
  Tokens revoked: 3

Payment Tokens

Runtime plane (`--api-key`). Tokens are single-use — mint a new one per transaction. `--idempotency-key` is required and never auto-generated. Select the payment method with `--payment-method-id`, or use `--card <number>` to match the last four digits.

Amount units differ per flag and are not interchangeable: `--amount` for VCN is USD decimal (the CLI converts it to integer cents on the wire), `--amount` for X402 is USDC micro-units, `--unionpay-amount` is a decimal string forwarded verbatim, and `payments capture` reports integer cents.

Virtual card (VCN)

Mint a one-time virtual card. `--amount` is USD decimal, 0.01–500.00. Optional: `--currency` (default USD), `--member`.

❯ agenzo-token-cli --yes payment-tokens create --type vcn --api-key <key> --payment-method-id <pm_id> --amount 30 --idempotency-key idem_001

✓ VCN created
  Token ID    ptk_01HZ...
  Card        4242 **** **** 1234
  Limit       $30.00
  Status      ACTIVE

Network token

Get a network token plus a one-time cryptogram. The real card number never leaves the vault. The selected payment method determines whether the credential is returned synchronously or through UnionPay checkout.

❯ agenzo-token-cli --yes payment-tokens create --type network-token --api-key <key> --payment-method-id <pm_id> --idempotency-key idem_002

✓ Network Token created
  Token ID      ptk_01HZ...
  Last Four     1234
  Cryptogram    AgAAAAAABk4DFkZGJhY2...
  Status        ACTIVE

Network token (UnionPay)

`unionpay-create` returns a PENDING token and `checkout_url` immediately. Open that URL, complete passkey authentication, then poll with `payment-tokens get` until ACTIVE. Select the UnionPay payment method with `--payment-method-id`; `--unionpay-amount` is a decimal string, recipient name plus email or phone is required, and no `--member` is sent.

❯ agenzo-token-cli payment-tokens unionpay-create --api-key <key> --payment-method-id <unionpay_pm_id> --unionpay-amount 174.58 --recipient-first-name Ada --recipient-last-name Lovelace --recipient-email ada@example.com --idempotency-key idem_006

  Payment Token ID   ptk_01HZ...
  Status             PENDING
  Checkout URL       https://...
⠋ Polling every 5s...
✓ Token ACTIVE (cryptogram issued)

❯ agenzo-token-cli payment-tokens get <ptk_id> --api-key <key>

X402 signature

Sign an EIP-712 payment backed by the selected payment method. `--amount` is in USDC smallest units (1 USDC = 1,000,000). Send the returned signature in your `X-PAYMENT` header.

❯ agenzo-token-cli --yes payment-tokens create --type x402 --api-key <key> --payment-method-id <pm_id> --pay-to 0xABC... --amount 1000000 --nonce abc123 --network base --deadline 1777457396 --idempotency-key idem_003

✓ X402 signature created
  Token ID     ptk_01HZ...
  Amount       1.000000 USDC
  Network      base
  Signature    eyJhbGciOiJFUzI1NiIs...

List payment tokens

List tokens, optionally filtered by `--type` (`vcn`, `network-token`, `x402`) and `--member`.

❯ agenzo-token-cli payment-tokens list --api-key <key>

  Token ID        Type             Status      Summary
  ptk_01HZ...     vcn              ACTIVE      **** 1234 | $30.00
  ptk_02AB...     network_token    ACTIVE      UnionPay | **** 1234

❯ agenzo-token-cli payment-tokens list --api-key <key> --type vcn --member <member_id>

Get payment token details

Show one token; the shape varies by type. Use it to poll an async UnionPay token that has not turned ACTIVE yet. Add `--reveal` only when you actually need the full card number.

❯ agenzo-token-cli payment-tokens get <ptk_id> --api-key <key>

  Token ID        ptk_01HZ...
  Type            vcn
  Status          ACTIVE
  Limit           $30.00
  Balance         $25.50

Revoke a payment token

Revoke an active token — a VCN is closed and settled. Tokens already in a terminal state cannot be revoked.

❯ agenzo-token-cli payment-tokens revoke <ptk_id> --api-key <key> --idempotency-key token-revoke-001

✓ Payment token revoked
  Status      REVOKED

Charging a Token

`agenzo-payment-cli` does one thing: charge a token that already exists. The amount, currency and fee were fixed when the token was minted, so capture takes neither — only which token to charge.

Capture a payment

Required: `--api-key`, `--payment-token-id` and `--idempotency-key` (unique per charge, sent as a header). The platform reads the brand off the token record and routes to the right rail, so `--payment-brand` is only ever an assertion — a mismatch errors. Amounts come back as integer cents.

❯ agenzo-payment-cli payments capture --api-key <key> --payment-token-id <ptk_id> --idempotency-key chg-2026-07-03-001 --yes

{
  "charge_no": "chg_...",
  "payment_brand": "unionpay",
  "amount_cents": 1200,
  "fee_cents": 0,
  "total_cents": 1200,
  "currency": "USD",
  "pay_status": "success"
}

`pay_status` is `success`, `failed` or `pending`. A `pending` result means the gateway had not settled within the platform's poll window — retry with the same `--idempotency-key` to read the outcome; it will not double-charge.

Merchant Fulfilment

`agenzo-merchant-cli` fulfils real-world commerce. Each capability is a noun, and the set grows over time — run `services list` to see what is live today. The key must carry `merchant` scope. Writes need `--idempotency-key`; output defaults to JSON.

ride-elife

Ride-hailing: price a trip, book it, then track or cancel. Note that `get` and `cancel` take the `ride_id` from `book`, not the `rio_...` order id.

Representative workflow

quote → book → get (poll) → cancel

hotel-redaug

Hotel booking: search, inspect rooms, price a rate, then create and settle an order. `create-order` only locks inventory; `pay-order` is the separate step that charges.

Representative workflow

search → hotel-detail → quote → create-order → pay-order → get (poll)

flight-flink

International flights, including after-sales. Ticketing is asynchronous, so poll `get-order`. Rebooking has its own paid step: `change-pay` charges the fee from `change-detail` and only then triggers change ticketing — it is the step most often missed. Refunds run `refund-apply → refund-detail → refund-confirm`.

Representative workflow

search → verify → create-order → pay-order → get-order · change-search → change-apply → change-detail → change-pay → get-order

orders

One read-only index across every provider — use it for a generic "my orders" request. Switch to a domain noun's `list-orders` once you know the business and need its specific fields.

Representative workflow

list (--order-type / --status) → get --order-id

CLI ↔ MCP

The same capability under both surfaces. CLI verbs are hyphenated; MCP tool names replace hyphens with underscores. Merchant capabilities are reached through `invoke` rather than being listed one tool per verb.

CLI	MCP	Auth
`agenzo-admin-cli orgs / developers / keys / accounts`	`orgs__get · developers__create · keys__create · accounts__get`	Bearer token
`agenzo-token-cli payment-methods`	`payment_methods__add · list · get · disable`	X-Api-Key
`agenzo-token-cli payment-tokens`	`payment_tokens__create · list · get · revoke`	X-Api-Key
`agenzo-payment-cli payments capture`	`payments__capture`	X-Api-Key
`agenzo-merchant-cli services list`	`list_services()`	X-Api-Key
`agenzo-merchant-cli ride-elife book`	`invoke("ride-elife", "book", {...})`	X-Api-Key
`agenzo-merchant-cli hotel-redaug pay-order`	`invoke("hotel-redaug", "pay-order", {...})`	X-Api-Key
`agenzo-merchant-cli flight-flink change-pay`	`invoke("flight-flink", "change-pay", {...})`	X-Api-Key
`agenzo-merchant-cli orders list`	`invoke("orders", "list", {...})`	X-Api-Key

Global Options

--help, -h — Show help for any command; add `--format json` for a machine-readable schema
--version, -v — Show the CLI version
--format <table|json> — Output shape. `agenzo-merchant-cli` defaults to json, the others to table
--api-key <sk_...> — Runtime credential for token, merchant and payment commands. Takes the full key string, not the key id
--yes — Non-interactive mode for automation. Nothing is prompted, so every required flag must be supplied
--idempotency-key <key> — Sent as the Idempotency-Key header on writes. Required, never auto-generated; reuse it to retry safely