MCP reference
AgenticMailCenter is an email inbox for external agents. Agents run in a client you choose and use the supported MCP or REST interface; the dashboard is a companion for mailbox owners. This reference describes the single Streamable HTTP MCP endpoint at /mcp. GET /mcp returns compact metadata. Protected POST /mcp requests require the same tenant-bound API key used by the Agent API, supplied as a Bearer token or x-api-key header. Every MCP credential requires gateway:read plus any route-specific scope: gateway:write for draft and label mutations, or gateway:send for approved sends.
The tools and JSON Schemas shown here are generated from the runtime tools/list definitions. The runtime list is the source of truth; this page intentionally does not maintain a second hand-written tool catalog.
Connection lifecycle
- Send
initializewith protocol version2025-11-25. - Send
notifications/initialized. - Call
tools/listto discover the current safe tool set and schemas. - Call only tools allowed by the key scope. Every MCP credential requires
gateway:read; draft and label writes additionally requiregateway:write, andsend_approved_draftadditionally requiresgateway:send. In thesend_with_policymode, sending requires human approval and passing policy checks. The separatesend_directmode can send a policy-allowed draft before review only whenAMG_DIRECT_SEND_ENABLED=true. Rejected drafts remain blocked.
MCP compacts message bodies and event payloads by default. Request body or attachment content only through the explicit tool options that document that choice. Direct send, mailbox connection, API-key administration, and policy administration are not MCP tools. Hosted deployments do not store message bodies, so include_body returns no text there. To read the text, call GET /v1/messages/{message_id}/content with the same key.
Runtime tool catalog
The live route advertises this catalog directly from its runtime definitions:
list_accounts— List connected Gateway email accounts.Input schema
{ "type": "object", "properties": { "limit": { "type": "integer", "description": "Maximum records to return (1-100).", "minimum": 1, "maximum": 100 }, "cursor": { "type": "string", "description": "Opaque cursor returned by a prior call to this same list tool with the same filters.", "maxLength": 4096, "minLength": 1 } }, "additionalProperties": false }list_identities— List agent identities and safety modes.Input schema
{ "type": "object", "properties": { "limit": { "type": "integer", "description": "Maximum records to return (1-100).", "minimum": 1, "maximum": 100 }, "cursor": { "type": "string", "description": "Opaque cursor returned by a prior call to this same list tool with the same filters.", "maxLength": 4096, "minLength": 1 } }, "additionalProperties": false }list_events— Poll durable compact events. Use after/checkpoint for forward resume; cursor/next_cursor remains backward pagination.Input schema
{ "type": "object", "properties": { "type": { "type": "string", "description": "Event type filter.", "maxLength": 65536 }, "source": { "type": "string", "description": "Event source filter.", "maxLength": 65536 }, "account_id": { "type": "string", "description": "Gateway account id filter.", "maxLength": 65536 }, "message_id": { "type": "string", "description": "Gateway message id filter.", "maxLength": 65536 }, "thread_id": { "type": "string", "description": "Gateway thread id filter.", "maxLength": 65536 }, "draft_id": { "type": "string", "description": "Gateway draft id filter.", "maxLength": 65536 }, "limit": { "type": "integer", "description": "Maximum events to return (1-200).", "minimum": 1, "maximum": 200 }, "cursor": { "type": "string", "description": "Opaque cursor returned by a prior list_events call.", "maxLength": 4096, "minLength": 1 }, "after": { "type": "string", "description": "Opaque forward checkpoint returned as checkpoint by a prior list_events call.", "maxLength": 4096, "minLength": 1 } }, "additionalProperties": false }list_threads— List normalized email threads with safe filters.Input schema
{ "type": "object", "properties": { "account_id": { "type": "string", "description": "Gateway account id.", "maxLength": 65536 }, "query": { "type": "string", "description": "Full-text search query.", "maxLength": 65536 }, "semantic": { "type": "string", "description": "Deterministic enrichment-backed semantic filter.", "maxLength": 65536 }, "label": { "type": "string", "description": "Internal label name.", "maxLength": 65536 }, "provider_mailbox_path": { "type": "string", "description": "Provider mailbox path metadata filter.", "maxLength": 65536 }, "provider_message_id": { "type": "string", "description": "Provider message id metadata filter.", "maxLength": 65536 }, "provider_label": { "type": "string", "description": "Provider label metadata filter.", "maxLength": 65536 }, "provider_flag": { "type": "string", "description": "Provider flag metadata filter.", "maxLength": 65536 }, "from": { "type": "string", "description": "Sender address or domain filter.", "maxLength": 65536 }, "recipient": { "type": "string", "description": "Recipient address or domain filter.", "maxLength": 65536 }, "date_from": { "type": "string", "description": "Inclusive lower date bound.", "maxLength": 65536 }, "date_to": { "type": "string", "description": "Inclusive upper date bound.", "maxLength": 65536 }, "has_attachment": { "type": "boolean", "description": "Filter by whether a message has attachments." }, "attachment": { "type": "string", "description": "Attachment filename, content type, or provider id filter.", "maxLength": 65536 }, "limit": { "type": "integer", "description": "Maximum records to return (1-100).", "minimum": 1, "maximum": 100 }, "cursor": { "type": "string", "description": "Opaque cursor returned by a prior call to this same list tool with the same filters.", "maxLength": 4096, "minLength": 1 } }, "additionalProperties": false }get_thread— Get a normalized email thread.Input schema
{ "type": "object", "properties": { "thread_id": { "type": "string", "description": "Gateway thread id.", "pattern": "^(?!\\.\\.?$)[^\\s/?#\\\\\\u0000-\\u001F\\u007F]+$", "maxLength": 65536, "minLength": 1 }, "include_body": { "type": "boolean", "description": "Include raw message body text and HTML." } }, "additionalProperties": false, "required": [ "thread_id" ] }list_messages— List normalized email messages with safe filters.Input schema
{ "type": "object", "properties": { "account_id": { "type": "string", "description": "Gateway account id.", "maxLength": 65536 }, "query": { "type": "string", "description": "Full-text search query.", "maxLength": 65536 }, "semantic": { "type": "string", "description": "Deterministic enrichment-backed semantic filter.", "maxLength": 65536 }, "label": { "type": "string", "description": "Internal label name.", "maxLength": 65536 }, "provider_mailbox_path": { "type": "string", "description": "Provider mailbox path metadata filter.", "maxLength": 65536 }, "provider_message_id": { "type": "string", "description": "Provider message id metadata filter.", "maxLength": 65536 }, "provider_label": { "type": "string", "description": "Provider label metadata filter.", "maxLength": 65536 }, "provider_flag": { "type": "string", "description": "Provider flag metadata filter.", "maxLength": 65536 }, "from": { "type": "string", "description": "Sender address or domain filter.", "maxLength": 65536 }, "recipient": { "type": "string", "description": "Recipient address or domain filter.", "maxLength": 65536 }, "date_from": { "type": "string", "description": "Inclusive lower date bound.", "maxLength": 65536 }, "date_to": { "type": "string", "description": "Inclusive upper date bound.", "maxLength": 65536 }, "has_attachment": { "type": "boolean", "description": "Filter by whether a message has attachments." }, "attachment": { "type": "string", "description": "Attachment filename, content type, or provider id filter.", "maxLength": 65536 }, "limit": { "type": "integer", "description": "Maximum records to return (1-100).", "minimum": 1, "maximum": 100 }, "cursor": { "type": "string", "description": "Opaque cursor returned by a prior call to this same list tool with the same filters.", "maxLength": 4096, "minLength": 1 } }, "additionalProperties": false }get_message— Get a normalized email message.Input schema
{ "type": "object", "properties": { "message_id": { "type": "string", "description": "Gateway message id.", "pattern": "^(?!\\.\\.?$)[^\\s/?#\\\\\\u0000-\\u001F\\u007F]+$", "maxLength": 65536, "minLength": 1 }, "include_body": { "type": "boolean", "description": "Include raw message body text and HTML." }, "include_enrichment": { "type": "boolean", "description": "Include compact AI enrichment evidence." } }, "additionalProperties": false, "required": [ "message_id" ] }search_messages— Search normalized email messages.Input schema
{ "type": "object", "properties": { "account_id": { "type": "string", "description": "Gateway account id.", "maxLength": 65536 }, "query": { "type": "string", "description": "Full-text search query.", "maxLength": 65536 }, "semantic": { "type": "string", "description": "Deterministic enrichment-backed semantic filter.", "maxLength": 65536 }, "label": { "type": "string", "description": "Internal label name.", "maxLength": 65536 }, "provider_mailbox_path": { "type": "string", "description": "Provider mailbox path metadata filter.", "maxLength": 65536 }, "provider_message_id": { "type": "string", "description": "Provider message id metadata filter.", "maxLength": 65536 }, "provider_label": { "type": "string", "description": "Provider label metadata filter.", "maxLength": 65536 }, "provider_flag": { "type": "string", "description": "Provider flag metadata filter.", "maxLength": 65536 }, "from": { "type": "string", "description": "Sender address or domain filter.", "maxLength": 65536 }, "recipient": { "type": "string", "description": "Recipient address or domain filter.", "maxLength": 65536 }, "date_from": { "type": "string", "description": "Inclusive lower date bound.", "maxLength": 65536 }, "date_to": { "type": "string", "description": "Inclusive upper date bound.", "maxLength": 65536 }, "has_attachment": { "type": "boolean", "description": "Filter by whether a message has attachments." }, "attachment": { "type": "string", "description": "Attachment filename, content type, or provider id filter.", "maxLength": 65536 }, "limit": { "type": "integer", "description": "Maximum records to return (1-100).", "minimum": 1, "maximum": 100 }, "cursor": { "type": "string", "description": "Opaque cursor returned by a prior call to this same list tool with the same filters.", "maxLength": 4096, "minLength": 1 } }, "additionalProperties": false }create_draft— Create a draft without sending.Input schema
{ "type": "object", "properties": { "account_id": { "type": "string", "description": "Gateway account id.", "maxLength": 65536, "minLength": 1 }, "thread_id": { "type": "string", "description": "Gateway thread id.", "maxLength": 65536 }, "agent_identity_id": { "type": "string", "description": "Gateway agent identity id.", "maxLength": 65536, "minLength": 1 }, "reply_to_message_id": { "type": "string", "description": "Gateway source message id for replies.", "maxLength": 65536 }, "idempotency_key": { "type": "string", "description": "Agent-provided idempotency key.", "maxLength": 65536, "minLength": 1 }, "subject": { "type": "string", "description": "Draft subject.", "maxLength": 65536 }, "to_addresses": { "type": "array", "description": "Primary recipients.", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Email address.", "maxLength": 65536, "minLength": 1 }, "name": { "type": "string", "description": "Optional display name.", "maxLength": 65536 } }, "additionalProperties": false, "required": [ "address" ] }, "maxItems": 256, "minItems": 1 }, "cc_addresses": { "type": "array", "description": "Carbon-copy recipients.", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Email address.", "maxLength": 65536, "minLength": 1 }, "name": { "type": "string", "description": "Optional display name.", "maxLength": 65536 } }, "additionalProperties": false, "required": [ "address" ] }, "maxItems": 256 }, "bcc_addresses": { "type": "array", "description": "Blind-carbon-copy recipients.", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Email address.", "maxLength": 65536, "minLength": 1 }, "name": { "type": "string", "description": "Optional display name.", "maxLength": 65536 } }, "additionalProperties": false, "required": [ "address" ] }, "maxItems": 256 }, "body_text": { "type": "string", "description": "Plain text draft body.", "maxLength": 65536, "minLength": 1 }, "body_html": { "type": "string", "description": "HTML draft body.", "maxLength": 65536 }, "attachments": { "type": "array", "description": "Outbound attachment descriptors.", "items": { "type": "object", "properties": { "filename": { "type": "string", "description": "Attachment filename.", "maxLength": 65536 }, "contentType": { "type": "string", "description": "Attachment content type.", "maxLength": 65536 }, "content_type": { "type": "string", "description": "Attachment content type.", "maxLength": 65536 }, "content": { "type": "string", "description": "Base64 attachment content.", "maxLength": 699052 }, "cid": { "type": "string", "description": "Optional content id.", "maxLength": 65536 } }, "additionalProperties": false }, "maxItems": 64 } }, "additionalProperties": false, "required": [ "account_id", "agent_identity_id", "idempotency_key", "to_addresses", "body_text" ] }update_draft— Update a draft without sending.Input schema
{ "type": "object", "properties": { "draft_id": { "type": "string", "description": "Gateway draft id.", "pattern": "^(?!\\.\\.?$)[^\\s/?#\\\\\\u0000-\\u001F\\u007F]+$", "maxLength": 65536 }, "subject": { "type": "string", "description": "Draft subject.", "maxLength": 65536 }, "to_addresses": { "type": "array", "description": "Primary recipients.", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Email address.", "maxLength": 65536, "minLength": 1 }, "name": { "type": "string", "description": "Optional display name.", "maxLength": 65536 } }, "additionalProperties": false, "required": [ "address" ] }, "maxItems": 256, "minItems": 1 }, "cc_addresses": { "type": "array", "description": "Carbon-copy recipients.", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Email address.", "maxLength": 65536, "minLength": 1 }, "name": { "type": "string", "description": "Optional display name.", "maxLength": 65536 } }, "additionalProperties": false, "required": [ "address" ] }, "maxItems": 256 }, "bcc_addresses": { "type": "array", "description": "Blind-carbon-copy recipients.", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Email address.", "maxLength": 65536, "minLength": 1 }, "name": { "type": "string", "description": "Optional display name.", "maxLength": 65536 } }, "additionalProperties": false, "required": [ "address" ] }, "maxItems": 256 }, "body_text": { "type": "string", "description": "Plain text draft body.", "maxLength": 65536, "minLength": 1 }, "body_html": { "type": "string", "description": "HTML draft body.", "maxLength": 65536 }, "attachments": { "type": "array", "description": "Outbound attachment descriptors.", "items": { "type": "object", "properties": { "filename": { "type": "string", "description": "Attachment filename.", "maxLength": 65536 }, "contentType": { "type": "string", "description": "Attachment content type.", "maxLength": 65536 }, "content_type": { "type": "string", "description": "Attachment content type.", "maxLength": 65536 }, "content": { "type": "string", "description": "Base64 attachment content.", "maxLength": 699052 }, "cid": { "type": "string", "description": "Optional content id.", "maxLength": 65536 } }, "additionalProperties": false }, "maxItems": 64 } }, "additionalProperties": false, "required": [ "draft_id" ] }submit_draft_for_approval— Submit a draft for human approval.Input schema
{ "type": "object", "properties": { "draft_id": { "type": "string", "description": "Gateway draft id.", "pattern": "^(?!\\.\\.?$)[^\\s/?#\\\\\\u0000-\\u001F\\u007F]+$", "maxLength": 65536, "minLength": 1 }, "submitted_by": { "type": "string", "description": "Actor submitting the draft.", "maxLength": 65536, "minLength": 1 } }, "additionalProperties": false, "required": [ "draft_id", "submitted_by" ] }send_approved_draft— Send a previously approved draft.Input schema
{ "type": "object", "properties": { "draft_id": { "type": "string", "description": "Gateway draft id.", "pattern": "^(?!\\.\\.?$)[^\\s/?#\\\\\\u0000-\\u001F\\u007F]+$", "maxLength": 65536, "minLength": 1 } }, "additionalProperties": false, "required": [ "draft_id" ] }reply_with_draft— Create a reply draft for an explicit thread and source message.Input schema
{ "type": "object", "properties": { "account_id": { "type": "string", "description": "Gateway account id.", "maxLength": 65536, "minLength": 1 }, "thread_id": { "type": "string", "description": "Gateway thread id.", "maxLength": 65536, "minLength": 1 }, "agent_identity_id": { "type": "string", "description": "Gateway agent identity id.", "maxLength": 65536, "minLength": 1 }, "reply_to_message_id": { "type": "string", "description": "Gateway source message id for replies.", "maxLength": 65536, "minLength": 1 }, "idempotency_key": { "type": "string", "description": "Agent-provided idempotency key.", "maxLength": 65536, "minLength": 1 }, "subject": { "type": "string", "description": "Draft subject.", "maxLength": 65536 }, "to_addresses": { "type": "array", "description": "Primary recipients.", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Email address.", "maxLength": 65536, "minLength": 1 }, "name": { "type": "string", "description": "Optional display name.", "maxLength": 65536 } }, "additionalProperties": false, "required": [ "address" ] }, "maxItems": 256, "minItems": 1 }, "cc_addresses": { "type": "array", "description": "Carbon-copy recipients.", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Email address.", "maxLength": 65536, "minLength": 1 }, "name": { "type": "string", "description": "Optional display name.", "maxLength": 65536 } }, "additionalProperties": false, "required": [ "address" ] }, "maxItems": 256 }, "bcc_addresses": { "type": "array", "description": "Blind-carbon-copy recipients.", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Email address.", "maxLength": 65536, "minLength": 1 }, "name": { "type": "string", "description": "Optional display name.", "maxLength": 65536 } }, "additionalProperties": false, "required": [ "address" ] }, "maxItems": 256 }, "body_text": { "type": "string", "description": "Plain text draft body.", "maxLength": 65536, "minLength": 1 }, "body_html": { "type": "string", "description": "HTML draft body.", "maxLength": 65536 }, "attachments": { "type": "array", "description": "Outbound attachment descriptors.", "items": { "type": "object", "properties": { "filename": { "type": "string", "description": "Attachment filename.", "maxLength": 65536 }, "contentType": { "type": "string", "description": "Attachment content type.", "maxLength": 65536 }, "content_type": { "type": "string", "description": "Attachment content type.", "maxLength": 65536 }, "content": { "type": "string", "description": "Base64 attachment content.", "maxLength": 699052 }, "cid": { "type": "string", "description": "Optional content id.", "maxLength": 65536 } }, "additionalProperties": false }, "maxItems": 64 } }, "additionalProperties": false, "required": [ "account_id", "thread_id", "agent_identity_id", "reply_to_message_id", "idempotency_key", "to_addresses", "body_text" ] }add_label— Add an internal Gateway label to a message.Input schema
{ "type": "object", "properties": { "message_id": { "type": "string", "description": "Gateway message id.", "pattern": "^(?!\\.\\.?$)[^\\s/?#\\\\\\u0000-\\u001F\\u007F]+$", "maxLength": 65536, "minLength": 1 }, "label_id": { "type": "string", "description": "Existing Gateway label id.", "maxLength": 65536 }, "name": { "type": "string", "description": "Internal label name.", "maxLength": 65536 }, "color": { "type": "string", "description": "Label color for newly-created labels.", "maxLength": 65536 }, "description": { "type": "string", "description": "Label description for newly-created labels.", "maxLength": 65536 } }, "additionalProperties": false, "required": [ "message_id" ] }remove_label— Remove an internal Gateway label from a message.Input schema
{ "type": "object", "properties": { "message_id": { "type": "string", "description": "Gateway message id.", "pattern": "^(?!\\.\\.?$)[^\\s/?#\\\\\\u0000-\\u001F\\u007F]+$", "maxLength": 65536, "minLength": 1 }, "label_id": { "type": "string", "description": "Existing Gateway label id.", "maxLength": 65536 }, "name": { "type": "string", "description": "Internal label name.", "maxLength": 65536 }, "color": { "type": "string", "description": "Label color for newly-created labels.", "maxLength": 65536 }, "description": { "type": "string", "description": "Label description for newly-created labels.", "maxLength": 65536 } }, "additionalProperties": false, "required": [ "message_id" ] }get_attachment— Get normalized attachment metadata.Input schema
{ "type": "object", "properties": { "attachment_id": { "type": "string", "description": "Gateway attachment id.", "pattern": "^(?!\\.\\.?$)[^\\s/?#\\\\\\u0000-\\u001F\\u007F]+$", "maxLength": 65536, "minLength": 1 }, "include_content": { "type": "boolean", "description": "Fetch base64 attachment content through MailConnector." } }, "additionalProperties": false, "required": [ "attachment_id" ] }
Use tools/list rather than copying this list into a client. Schemas are closed at the top level and reject unknown fields.
Safe local probe
This probe only discovers metadata and tools; it does not create a draft or send mail:
curl --fail-with-body --silent --show-error \
-H "Authorization: Bearer ${AGENT_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
"${AGENTICMAILCENTER_ORIGIN}/mcp"
For a client-specific connection shape, use the Claude Code, Codex, Hermes Agent, or OpenClaw guide and keep the key in the client secret/environment store.