Connect an agent

Give an agent access to its inbox over MCP, the CLI or REST, with an API key or OAuth, on your machine or through remote access.

Every agent surface uses the same credential and the same rules. The owner gives the agent two things:

• A base URL. Locally, the service’s loopback URL, such as http://127.0.0.1:8025. For agents in the cloud, the remote access URL, such as https://inbot.example.com.
• A credential. An API key (inbot_<id>_<secret>) created by the owner, or an OAuth grant the owner approves in the browser.

Send the credential as Authorization: Bearer <credential> on API and MCP requests. Signed download capabilities are the exception and need no bearer. Credentials in query strings or custom headers are not accepted. Use 127.0.0.1 rather than localhost: the service accepts only the exact host it serves.

The local examples below assume inbot serve --port 8025. Without --port, serve picks a random free port on each start; use a fixed port for stored agent configurations.

MCP

Inbot serves MCP over streamable HTTP (protocol version 2025-06-18) at /mcp. There is no stdio transport. MCP tools lists all 36 tools.

Claude Code

Follow Connect Claude Code to read the key without recording it in shell history, add the HTTP MCP server with user scope, and install the Inbot skill. OAuth-capable clients can use owner consent instead of an API key.

Codex

In ~/.codex/config.toml:

[mcp_servers.inbot]
url = "http://127.0.0.1:8025/mcp"
bearer_token_env_var = "INBOT_API_KEY"

Other MCP clients

Most clients accept a JSON entry like this:

{
  "mcpServers": {
    "inbot": {
      "type": "http",
      "url": "http://127.0.0.1:8025/mcp",
      "headers": { "Authorization": "Bearer ${INBOT_API_KEY}" }
    }
  }
}

The service checks the credential again on every tool call, so a revoked key stops working immediately, even in an open session.

CLI

The inbot command works for agents too. Set both variables:

export INBOT_URL=http://127.0.0.1:8025
printf "Inbot API key: "
read -rs INBOT_API_KEY
printf "\n"
export INBOT_API_KEY
inbot inboxes list --json
inbot threads list --inbox support@agents.example.com --labels unread --json

Run the prompt in Bash or Zsh; read -s hides the key and keeps it out of shell history. Unset INBOT_API_KEY when finished.

INBOT_URL is the origin without /v0. When both are set, they take precedence over the owner’s connection.json, and setting only one is an error rather than a fallback to owner access. The CLI refuses redirects, times out after 30 seconds and never retries on its own.

• --json prints the exact API response with its snake_case fields. Without it, the CLI prints tables, with No results. for empty lists and the next page token when there is one.
• Errors go to stderr as JSON, { name, code, message, fix }, with a stable exit code.
• Body commands accept flags such as --to and --text, or the full API payload with --data '<json>' or --data-file <path> (- for stdin).
• messages raw, messages attachment, threads attachment and drafts attachment download files through a signed capability URL. -o <path> (or --output) writes a new file with mode 0600 and never overwrites an existing path. Without it the bytes go to redirected stdout; binary output to a terminal is refused with exit code 2. With --json the command prints only the download metadata, which includes the sensitive URL, and cannot be combined with -o.
• Sends print Idempotency-Key: <key> to stderr before the request. If you do not pass --idempotency-key, the CLI generates one.

The CLI reference lists every command and flag.

REST

curl -s http://127.0.0.1:8025/v0/inboxes -H "Authorization: Bearer $INBOT_API_KEY"

Requests and responses are JSON with snake_case fields; unknown body fields are rejected. See the REST API.

Agent skill

The repository’s skills/inbot folder is a ready-made skill: a short SKILL.md with the workflow and rules, plus references for MCP, REST, sending, security, events and the CLI. Copy the folder into your agent’s skills directory. There is no installer for it yet.

What an agent can never do

Agent credentials cannot reach domains, API keys, the mail transport, remote access, owner sessions, approvals, rejected-mail records, quarantine, OAuth management or send_unknown resolution. None of these are MCP tools. The tunnel permits owner browser sign-in, session and password management, draft approval and rejection, and OAuth consent; other owner management stays local. The local owner bearer is rejected on every tunneled path. See the route policy. Nothing in an email can change these boundaries.