# MCP

Use Connect agent in your project to set up Claude Code, Codex or another MCP client with a project key.

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



<a id="mcp-availability-and-connection"></a>

## Connect your AI agent

Create a test inbox, wait for email and read its verification code from your agent.

Connect to hosted InboxSpec at `https://api.inboxspec.com/mcp` with your project key. No local server is needed.

<a id="use-inboxspec-today"></a>

## 1\. Save your project key

In the console, choose your project and open Connect agent in the sidebar to create a dedicated key and follow the setup. You can also manage keys under Credentials. Save its show-once value as `INBOXSPEC_API_KEY` in the environment that launches your client. Keep it out of prompts and configuration files.

Set the key in a Bash terminal

Run this command, paste your saved key at the hidden prompt and press Enter. Launch your client from this same terminal. The key stays out of shell history.

```bash
read -r -s -p 'InboxSpec project key: ' INBOXSPEC_API_KEY
export INBOXSPEC_API_KEY
printf '\n'
```

The key selects your project. Use a dedicated test project and review tool calls that delete messages or clean up a run. This release uses project keys; it does not offer browser sign-in.

<a id="choose-your-mcp-client"></a>

## 2\. Choose your client

<a id="mcp-claude-code"></a>

Claude Code

Add the InboxSpec entry to your project’s `.mcp.json`. Keep any existing server entries.

```json
{
  "mcpServers": {
    "inboxspec": {
      "type": "http",
      "url": "https://api.inboxspec.com/mcp",
      "timeout": 300000,
      "headers": {
        "Authorization": "Bearer ${INBOXSPEC_API_KEY}"
      }
    }
  }
}
```

Start Claude Code with the key in its environment, approve this project’s MCP configuration and open `/mcp` to check the connection. The configuration reads the key from your environment each time.

<a id="mcp-codex"></a>

Codex

Add this entry to `~/.codex/config.toml`, then launch Codex with the key in its environment:

```text
[mcp_servers.inboxspec]
url = "https://api.inboxspec.com/mcp"
bearer_token_env_var = "INBOXSPEC_API_KEY"
tool_timeout_sec = 300
```

Open `/mcp` to check that InboxSpec is connected. If a shared background server was started without the key, launch this session with `codex --no-daemon` from the configured terminal.

<a id="mcp-other-clients"></a>

Other MCP clients

Use Streamable HTTP at `https://api.inboxspec.com/mcp`. Configure `Authorization: Bearer` with your project key using the client’s secret storage, and allow 300 seconds per tool call.

Your client must support bearer headers and cancellation. Clients that require browser sign-in cannot use this setup. Do not use the legacy SSE transport.

<a id="try-your-mcp-connection"></a>

## 3\. Try one email

Ask your agent:

```text
Use InboxSpec to create an inbox
for a new, unique test run.
Show me its email address, then
wait up to 60 seconds for an email
with a verification code.
```

Send a test email to that address while the wait is pending. A match returns the message and code candidates; a timeout means no matching email arrived. Read `structuredContent.status` before using a result.

After the test, ask the agent to clean up only that run once all senders and waits have finished. See [wait outcomes and retries](https://www.inboxspec.com/docs/markdown/waits.md) and [cleanup](https://www.inboxspec.com/docs/markdown/cleanup.md) for details.

For client configuration details, see the [Claude Code](https://code.claude.com/docs/en/mcp) and [Codex](https://developers.openai.com/codex/mcp) references.