Get started
Browse the docs

Agents & MCP

MCP Server

Connect an AI agent to its email inbox with Inboundr's MCP server: setup for Claude Code and other MCP clients, and every tool it provides.

Inboundr has a built-in Model Context Protocol (MCP) server, so an AI agent can manage its own email through a set of tools without any glue code. It serves the same data as the REST API and uses the same inb_ API key.

Endpoint#

MCP endpoint
https://inboundr.net/api/mcp

The server speaks streamable HTTP. Authenticate with a bearer token:

Header
Authorization: Bearer inb_xxxxxxxxxxxxxxxxxxxxxxxx

Connecting#

Claude Desktop / MCP config
{
  "mcpServers": {
    "inboundr": {
      "url": "https://inboundr.net/api/mcp",
      "headers": { "Authorization": "Bearer inb_xxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

The console shows a ready-to-paste connection snippet for your account on the Agents & MCP page.

Tools#

list_domains

List the caller's domains with verification status. Mail can only be received on verified domains.

create_inbox

Create an address on one of the caller's domains, e.g. agent@yourdomain.com. Store-only by default; pass endpointId to also deliver each message to a webhook.

addressstringpathrequired

Full address to create.

endpointIdstringpath

Optional webhook endpoint id (ep_…).

list_inboxes

List the caller's explicit addresses. (Verified domains also accept mail on any address via catch-all.)

list_emails

List emails newest-first (summaries, no bodies). Filter by to, threadId, or direction; paginate with cursor.

tostringpath

Only emails addressed (To/Cc) to this address.

threadIdstringpath

directionstringpath

inbound or outbound.

limitnumberpath

1–100.

cursorstringpath

nextCursor from a previous call.
get_email

Fetch one email in full: text and HTML bodies, attachment metadata, spam/SPF/DKIM verdicts, and threading headers.

idstringpathrequired

Email id (em_…).

get_thread

Fetch all messages in a conversation, oldest first (summaries).

threadIdstringpathrequired

Thread id (thr_…).

get_attachment

Get a presigned download URL (valid 15 minutes) for one attachment. Index is 0-based, matching the attachments array from get_email.

emailIdstringpathrequired

Email id (em_…).

indexnumberpathrequired

0-based attachment index.

list_shield_rules

List the caller's shield rules in evaluation order. The first rule whose conditions all match a message wins and no later rule runs, so the order is the meaning of the list.

create_shield_rule

Create a rule judged against every inbound message before it is stored. All conditions must match (AND); use several rules for OR. New rules are added last in the order.

namestringpathrequired

Short label.

actionstringpathrequired

block drops the message permanently: it's never stored or delivered and the body can't be recovered, though it still counts as received. allow delivers it and skips later rules. route delivers to endpointIds instead of the address's own endpoints; an empty list quarantines it.

conditionsobject[]pathrequired

1–8 { field, operator, value } objects. See Fields and operators.

endpointIdsstring[]path

Route only (ep_…).

domainIdstringpath

Limit to one domain (dom_…).

addressIdstringpath

Limit to one address (addr_…).
delete_shield_rule

Delete a rule. Mail it blocked starts arriving again; mail already blocked stays gone.

idstringpathrequired

Rule id (gr_…).

list_shield_blocks

List messages recently dropped by a rule: sender, recipient, subject, and which rule caught them. This is the only record a blocked message leaves.

limitnumberpath

1–200, default 50.

Rate limits#

MCP and REST share one budget: 5 requests per second per account, counted against the API key's owner. See Rate limits.

A typical agent loop#

  1. Call list_emails with direction: "inbound" to find new mail.
  2. Call get_thread to read the conversation for context.
  3. Call create_shield_rule if future mail like it should be blocked, allowed, routed or quarantined.