Self-hosted MCP

Prepare your installation

This guide is for teams running their own InboxSpec installation from a repository checkout. For hosted availability, see Connect your AI agent.

Configure the MCP service with the same migrated database, object store and receiving configuration as your API. The local server uses these dependencies directly; it does not connect to the hosted REST API.

Start the server

For a client that launches a local process over stdio, supply a project key in the process’s secret environment at startup. From the configured repository root, use:

bun run --cwd packages/mcp stdio

For a shared Streamable HTTP service, use:

bun run --cwd packages/mcp http

The default port is 8082 and the path is /mcp. Configure your MCP client with the URL of your own service and an Authorization: Bearer header sourced from its secret environment. Authentication uses a project API key, not browser sign-in. Never paste a project key into a prompt.

Check the connection

1. Connect your client and list the available tools.
2. Call inbox_for_run to create an inbox for your test run.
3. Call wait_for_message, then send test mail to that inbox while the wait is pending.
4. Read structuredContent.status before using the result. A timeout is not a matching message.

Your client must support cancellation and a timeout longer than the requested wait; HTTP clients must support Streamable HTTP. See wait outcomes and retry limits. After producers and waits finish, clean up only your test run.