MCP server

Available

The Emithook MCP server (@emithook/mcp) exposes the management API as Model Context Protocol tools, so an AI assistant (Claude, Cursor, an internal agent) can query and operate Emithook in natural language — "show failed deliveries to ep_razorpay in the last hour", "redrive the DLQ for that endpoint", "create an endpoint with the Shopify preset".

Every tool is a thin wrapper over the same scoped key (via @emithook/sdk) — there is no capability here the API doesn't have. If you are an agent, read the Glossary before calling tools: the arguments below use those exact entity names.

Connect

The server runs locally over stdio and talks to the API with your key:

// add to your MCP client config (e.g. Claude Desktop)
{
  "mcpServers": {
    "emithook": {
      "command": "npx",
      "args": ["-y", "@emithook/mcp"],
      "env": {
        "EMITHOOK_API_KEY": "ek_live_…",
        "EMITHOOK_SCOPE": "read"
      }
    }
  }
}

Env var	Purpose
EMITHOOK_API_KEY	Required. The scoped key the tools act under.
EMITHOOK_SCOPE	Operator-declared scope (read | write | admin, default read) — caps which tools are exposed. Never widens the key; the API enforces the real scope regardless.
EMITHOOK_BASE_URL	API base override (self-host).
EMITHOOK_INBOX_MONGO_URL + EMITHOOK_ORG_ID	Enable the inbox tools (read the MX emails store for that org). EMITHOOK_INBOX_MONGO_DB optional. Absent ⇒ inbox tools report "inbox not configured".

Auth, scopes & safety

• Read tools are safe by default. A read-scoped key can call them; they never mutate state.
• Write tools require a write (or admin) key and an explicit confirmation: the registry appends a confirm boolean to every write tool's schema, so the call is a no-op until the client passes confirm: true. With a read scope the write tools aren't exposed at all.
• Tools inherit the key's organization; an agent can never reach across orgs.

Tool class	Min scope	Confirmation
list_*, get_*, search_*, summarize_thread, get_metrics	read	none (safe)
send_webhook, replay_event, redrive_dlq, create_endpoint, create_destination, rotate_endpoint_secret	write	confirm: true required

Tool catalog

Query (read-safe)

Tool	Arguments	Returns
list_events	status? (delivered|failed|retrying|dlq), endpoint?, event_type?, since?, until?, cursor?, limit?	A page of events.
get_event	id	One event with all its delivery attempts.
list_destinations	type?, validation?, cursor?, limit?	Registry destinations.
list_domains	—	Custom domains with verification state + DNS records.
get_metrics	key (an endpoint or destination id)	Pre-aggregated rollups for that id.

Email inbox (agent-native)

The headline of the MX engine: hand an agent its own address and let it reason over its mail. All read-safe; they read the MX emails store directly and activate only when EMITHOOK_INBOX_MONGO_URL + EMITHOOK_ORG_ID are set (otherwise they report "inbox not configured").

Tool	Arguments	Returns
list_emails	alias, cursor?, limit?	An alias's messages, newest first — from/to, subject, received, auth result, attachments, parsed text body.
get_email	message_id	One email in full: headers + parsed body + SPF/DKIM/DMARC result.
search_emails	query, alias?, limit?	Newest-first matches across subject / from / body, optionally within one alias.
summarize_thread	alias, subject	The alias's messages sharing that subject (Re:/Fwd: stripped), oldest first, for the model to summarize. Returns the thread — it does not itself summarize.

Operate (write — confirm: true required)

Tool	Arguments	Effect
send_webhook	destination, event_type, payload, headers?, idempotency_key?	Send one webhook to a destination id or HTTPS URL.
replay_event	id	Re-deliver a single event (flagged webhook-replayed).
redrive_dlq	endpoint?, since?	Bulk-replay dead-lettered events.
create_endpoint	slug, path?, preset?, destinations?[]	Create an inbound endpoint.
create_destination	name, type, url?, config?	Register an outbound destination (created pending validation).
rotate_endpoint_secret	id, secret	Set an endpoint's inbound verify secret (write-only, never echoed).

Example session

Agent: "What's failing for ep_razorpay in the last hour?"
 → get_metrics(key="ep_razorpay")
 → list_events(endpoint="ep_razorpay", status="failed", since="2026-06-22T05:00:00Z")
 → get_event(id="evt_01JX…")               # inspect the 5xx body

Agent: "Replay the dead-lettered ones."
 → redrive_dlq(endpoint="ep_razorpay", confirm=true)   # ⚠ write — needs confirm

See also

• API conventions — the scopes, IDs and errors these tools share.
• CLI — the same operations from a terminal.
• Glossary — entity definitions used in every argument.