Openhook MCP server

Openhook

An event inbox for AI agents. Create a public URL, wait for a callback, inspect what arrived, and continue the task.

Openhook operates its own HTTP, SMTP, and authoritative DNS capture servers. Events live in its SQLite database. No external webhook service is involved.

Try it or host it

Create a free inbox without an account, or connect your agent. Optional hosted Pro provides persistent inboxes and account recovery; see the current availability and plans. Self-hosting remains MIT licensed with no Openhook account or subscription.

Practical recipes: local forwarding, GitHub push callbacks, and Stripe test callbacks.

First callback in under a minute

With Python 3 installed, clone the repository and run the disposable example:

git clone https://github.com/openhook-dev/openhook-inbox.git
cd openhook-inbox
python3 examples/first_callback.py

It creates a free inbox on openhook.dev, sends a real callback, verifies the original bytes, then deletes its inbox and payload. The private token stays in memory. No account, API key, or Python dependencies are needed for this example. Minimal operational activity metadata remains after deletion.

Install the agent skill

For Codex, Claude Code, and other compatible Agent Skills clients:

npx skills add openhook-dev/openhook-inbox --skill openhook

The skill setup and permissions explain MCP connection, REST fallback, local forwarding, and handling private inbox tokens. Installing the skill does not install or start the server.

Run it

From the checkout, install uv and start your own server:

uv sync
uv run openhook --http

Open http://127.0.0.1:8788/app. The website, capture API, and Streamable HTTP MCP endpoint share one service and one durable store.

Connect an MCP client to http://127.0.0.1:8788/mcp, or use uv run openhook for stdio. A local stdio process shares the same database with a running HTTP process when both use the same OPENHOOKDATABASE. The HTTP process must be running to receive HTTP callbacks. Check the same loop against your server with python3 examples/firstcallback.py --url http://127.0.0.1:8788. External providers need a publicly reachable origin; the localhost example only proves your local server works.

GitHub releases provide versioned source and Python distributions when available. The openhook-mcp package is not currently published on PyPI; use the source checkout or a release artifact rather than assuming a package-index install works.

Agent workflow

1. Call createwebhook. Save the private ohk management token.
2. Give the returned public HTTP URL, email address, or DNS name to the sender.
3. Call waitforrequest with the management token.
4. Inspect the event and act. Reconnect using the returned next_since cursor.

Public capture addresses cannot read or delete events. Rotate a compromised management token with rotatewebhooktoken. Rotation preserves public addresses.

Anonymous inboxes expire within seven days. Each accepts up to 1000 retained events. When full, capture returns a capacity error instead of evicting accepted events. Individual events are limited to 1 MB. Email and DNS addresses are returned only when their listeners are configured.

Native tools

29 tools cover inbox creation, response configuration, token rotation, event inspection, literal search, notes, JSON/CSV export, exact-byte download, HTTP/email waits, test events, link/code extraction, callback checking, delayed responses, provider subscriptions, deletion, and activity history. See the generated tool reference.

Durable activity history

Shortened. The full README is on GitHub.