# octapi-mcp

octapi for agents. One package: an MCP server and a CLI over a brand's WhatsApp number,
inbox, customer book, catalogue and diary — the same records the brand's front desk runs on.

## Install into Claude Code

    claude mcp add octapi -- npx -y octapi-mcp mcp

Then, in the dashboard, Account → API keys → New key, and:

    npx octapi-mcp login ok_live_…

Or set `OCTAPI_API_KEY`. The consumer tools (`find_businesses`, `get_business`) need no key.

## Try it from a terminal

    npx octapi-mcp whoami
    npx octapi-mcp list_conversations status=human
    npx octapi-mcp list_catalogue
    npx octapi-mcp check_availability offering_id=… date=2026-09-20
    npx octapi-mcp book offering_id=… starts_at=2026-09-20T10:00:00+08:00 name="Mrs Chan" phone=85291234567
    npx octapi-mcp tools

## Tools

Business (through a key): `whoami`, `list_conversations`, `read_conversation`, `send_message`,
`set_conversation_status`, `list_customers`, `get_customer`, `create_customer`, `list_catalogue`,
`list_hours`, `check_availability`, `book`, `cancel_appointment`, `diary`, `list_knowledge`, `poll_events`.

Inbound messages can also be pushed: set a webhook URL on the key (Account → API keys) and
every customer message is POSTed as JSON, signed `X-Octapi-Signature: t=…,v1=…` (HMAC-SHA256
of `<t>.<body>` with the key's webhook secret).

Consumer (no key): `find_businesses`, `get_business` — across every brand that chose to be listed.

Phone numbers are digits with the country code and no plus. Times are ISO 8601 with an
offset; dates are `YYYY-MM-DD` in the brand's time zone. Every result is JSON.

A key acts as one brand with one role. Reads are free; sends draw down the brand's credits
once metering ships. Nothing here is a model: bring your own.