InboxSpecDocumentation

Developer tools

MCP

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

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.

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.

Example
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.

2. Choose your client

Claude Code

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

Example
{
  "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.

Codex

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

Example
[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.

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.

3. Try one email

Ask your agent:

Example
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 and cleanup for details.

For client configuration details, see the Claude Code and Codex references.