MCP tools

The catalog

26 tools, one catalog, deliberately ordered read-before-write. The identical catalog is served over MCP at /mcp, over REST at POST /tools/:name, and enumerable at GET /tools.

Mounting

ALL/mcpMCP streamable HTTP, stateless — Bearer key auth

mcp client config

{
  "mcpServers": {
    "agentpush": {
      "type": "http",
      "url": "https://<your-agentpush-host>/mcp",
      "headers": { "Authorization": "Bearer apk_…" }
    }
  }
}

The MCP surface is workspace-scoped exactly like REST: the Bearer key resolves your workspace, and tools see only its contacts, events, provider accounts and routes. Tool descriptions embedded in the catalog are written for agents — session-window rules, blocked-send semantics and safe-usage hints are part of the tool contract itself.

Contacts & threads

Tool	Tag	What it does
`find_contact`	read	Look up a person by identifier (phone, email) or `contact_id`; returns identifiers, attributes and reachable channels, or `found: false`.
`upsert_contact`	write	Create a contact (no id) or update one (with id) — identifiers and attributes.
`read_thread`	read	Full message thread (sent + received) for a contact, all channels merged, sorted by date.

Sending

Tool	Tag	What it does
`send_message`	write	Send to one person — text, template or media. Returns `sent` / `queued` / `blocked` (with reason + suggestion) / `failed`.
`send_broadcast`	write	Send one message to a whole audience; returns a `broadcast_id` plus per-recipient results.
`upload_media`	write	Upload a file (public URL or base64) to a channel provider; returns a reusable `media_id`.
`list_templates`	read	List pre-approved message templates per locale — required for out-of-session WhatsApp sends.
`preview_segment`	read	Count + sample who matches a segment, without sending. Call it before every `send_broadcast`.

Delivery & analytics

Tool	Tag	What it does
`check_delivery`	read	Delivery status of one message (`queued → sent → delivered → read`, or `failed` / `bounced`) or aggregate stats for a broadcast.
`get_stats`	read	Aggregated delivery counts by status, filterable by channel, direction, broadcast and time window.
`get_spend`	read	Projected send cost (USD): total + per-channel breakdown over billable outbound events.
`get_ttr`	read	Time-to-response stats — p50 and p95 (ms) from each inbound to the first outbound reply.
`get_capabilities`	read	What each configured channel supports: `text`, `media`, `templates`, `groups`, `reactions`.

Draft & approve

Tool	Tag	What it does
`messaging_draft`	write	Create a pending draft (does not send); returns `draft_id` + preview. In-memory, ephemeral.
`messaging_preview`	read	Render a draft or inline payload (e.g. markdown→HTML for email) without sending or creating anything.
`messaging_approve`	write	Approve a draft and SEND it — the only sending path in this family. Requires `confirm: true`.
`messaging_list`	read	List drafts, optionally filtered by channel and/or status.
`messaging_attachment_fetch`	read	Lazily fetch inbound attachment bytes by (`message_id`, `attachment_id`) — polling only captures metadata.

Inbound routes

Tool	Tag	What it does
`inbound_route_list`	read	List routing rules, filterable by enabled status or `provider_account_id`.
`inbound_route_get`	read	Fetch one route by id (workspace-scoped).
`inbound_route_create`	write	Create a rule — match type, channel scope, dispatch mode, `notify_url` / `notify_secret` (secret encrypted at rest, never echoed back).
`inbound_route_update`	write	Partial update; the resulting row is re-validated against the cross-field rules.
`inbound_route_set_enabled`	write	Enable or disable a route without touching its other fields.
`inbound_route_delete`	write	Hard delete — no undo.

Requests & signals

Tool	Tag	What it does
`poll_inbound`	read	Poll journaled inbound Requests for a `source` from a time cursor — the wake-by-poll path. Never returns the notifies agentpush itself dispatched.
`dispatch_request`	write	Fire-and-forget outbound POST of an arbitrary payload to a URL — egress-guarded, always journaled (dispatched/failed), never throws.