Technical

For developers and agent builders

The endpoints an agent calls, and how to run your own inbox.

Read the docs GitHub Deploy to Cloudflare Let your AI install it

For the plain version, read How it works.

What it is

One repository, two runtimes

The same TypeScript code runs on Cloudflare Workers and on Node. CI tests both.

  • Open source

    Six packages, the inbox app, an email gateway and this website. Decision records in docs/adr explain the design.

  • Run it where you like

    Workers with D1, queues and cron, or Node with one SQLite file. Each instance serves one business.

  • Licence

    MIT for everything: the server, the apps, the UI, the spec and the SDK, which verifies webhooks.

The doors

Four doors: REST, MCP, email and a web page

All of this works today unless marked.

Read the API docs
Discovery
GET /.well-known/agent-inbox.json Names the instance, its item types, trust tiers and doors. Email is not listed.
REST
GET /openapi.json · /v1/* 55 operations: 11 public, 44 under /v1/owner. Built from the same schemas as the MCP tools.
MCP public
POST /mcp 11 tools for a customer's agent, no sign-in. acknowledge_receipt counter-signs a receipt.
MCP owner
POST /mcp/owner 34 tools for the owner and their AI. OAuth 2.1 with PKCE, or an owner API key.
Email in
POST /v1/email/inbound Raw MIME. Off until you set an inbound secret in Settings and send it in X-Inbox-Email-Secret. Emails become messages or replies, not bookings yet.
Web form
GET / · /p/book · /p/quote · /p/message The business's own page, for people with no agent: services, free times, a quote, a message. In its name and the visitor's language, no script. Requests go through the same doors as an agent's (channel form), priced bookings through the confirm step.
Idempotency
Idempotency-Key · idempotency_key A repeated request with the same key gets the same answer: 200 with Idempotent-Replayed: true, never a second booking.
Access tokens
access_token · x-access-token Given to a caller with no key, so they can read, cancel or follow up on their item later.
Errors
application/problem+json A code, a message, and fields[{path, problem, message}] for each bad field.

Try it

Try the live instance

To book something and watch it land, use the demo shop. inbox.surfingdog.ai is our own instance; its public doors need no key either.

One call to start with

curl https://inbox.surfingdog.ai/v1/business

Returns the business name, domain, timezone, currency, languages and item types. No key needed, cached for five minutes.

Run it

Four ways to set it up

Same software each way.

  • Let your AI do it

    Give one line to Claude, Codex or Grok. It sets up the server, your subdomain and email in.

    Get the line

  • Cloudflare Workers

    One click on your own account. A database and a queue are created for you.

    Deploy to Cloudflare

  • Your own server

    Node 22.16, 24 or 26. Clone, install, build, run.

    Read the quickstart

  • Hosted by us

    We run it for you, at an address on your own domain. Free, or Pro at $10, €10 or £9 a month.

    Get your agent inbox

Connect your AI

Let your own AI run the inbox

Claude, ChatGPT or any Streamable HTTP client can work the inbox for you.

How to connect

POST /mcp/owner

Each instance is its own OAuth server. Clients use OAuth 2.1 with PKCE and a Client ID Metadata Document, so nothing is registered by hand. Dynamic registration and owner API keys work too.

34 tools cover items, replies, the catalogue, opening hours, rules, webhooks and settings. Eight scopes, shown on the consent screen in plain words, limit what a client can do.

Contribute

Help build it

Read the decision records before you change the architecture.

  • The code

    Every change must pass the tests on Node and on workerd.

    Open the repository

  • How to work on it

    The toolchain and the rules of the repository.

    Read contributing

  • Ask for something

    Say what you need, and vote on what others have asked for.

    Feature requests

It is all MIT: you can run a changed copy as a service, or build it into your own product, without publishing your changes.