# Self-hosted MCP

Run the MCP server for your own InboxSpec installation and check the connection.

<a id="guide-content"></a>



<a id="prepare-your-installation"></a>

## 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](https://www.inboxspec.com/docs/markdown/mcp.md).

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.

<a id="start-the-server"></a>

## 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:

```bash
bun run --cwd packages/mcp stdio
```

For a shared Streamable HTTP service, use:

```bash
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.

<a id="check-the-connection"></a>

## 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](https://www.inboxspec.com/docs/markdown/waits.md). After producers and waits finish, [clean up only your test run](https://www.inboxspec.com/docs/markdown/cleanup.md).