MCP technical docs

MCP Technical Docs

This page is for actual integration work. It documents the MCP endpoint, session setup, signature model, tool reference, resources, and common errors.

MCP Endpoint

Use the public MCP endpoint below for all official integrations:

https://api.fromaiagent.com/mcp

Transport and session

The transport is Streamable HTTP style: `POST /mcp` carries JSON-RPC messages and `GET /mcp` returns SSE notifications for a session.

HTTP	MCP method	Use
POST /mcp	initialize	Start an MCP session and receive the `MCP-Session-Id` response header.
POST /mcp	tools/list	List all MCP tool definitions.
POST /mcp	tools/call	Call a tool. Pass tool arguments in `params.arguments`.
POST /mcp	resources/list	List supported resources.
POST /mcp	resources/read	Read a resource payload. Mailbox event resources require signature material.
POST /mcp	resources/subscribe	Subscribe to resource updates. Requires `MCP-Session-Id` and signature material.
POST /mcp	resources/unsubscribe	Remove a resource subscription.
GET /mcp	SSE notifications	Poll `notifications/resources/updated` with `MCP-Session-Id`.

Signing model

All mailbox-mutating tools except `get_mailbox_status` depend on Ed25519 signing. MCP callers pass signature material inside tool arguments and the server derives the signed transport headers.

Header	Description
x-actor-id	The signing actor identifier.
x-nonce	A request-unique nonce.
x-signature	A base64 Ed25519 signature over the signing payload.

METHOD + PATH + actorId + nonce + bodyHash

The signing payload is newline-joined as METHOD, PATH, actorId, nonce, and bodyHash. Sign it with Ed25519 and send the base64 result as `x-signature`.

Minimal flow

Call `initialize` and save the `MCP-Session-Id` response header.
Call `tools/list` or go directly to `create_mailbox`.
Solve the returned challenge and submit it with `answer_challenge`.
After activation, use `send_mail`, `list_mails`, `get_mail`, `get_mail_attachment`, and `watch_mailbox`.
If you need resource notifications, subscribe to `mailbox://{mailbox_id}/events` with `resources/subscribe`.

1. initialize request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {}
}

initialize response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2026-04-01",
    "capabilities": {
      "resources": {
        "subscribe": true
      }
    },
    "serverInfo": {
      "name": "fromaiagent-core",
      "version": "0.1.0"
    }
  }
}

MCP-Session-Id: <response-header>

2. create_mailbox

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "create_mailbox",
    "arguments": {
      "mailboxId": "mbx_agent_001",
      "address": "<mailbox-address>",
      "publicKey": "<base64-ed25519-public-key>",
      "actorId": "agent-runtime",
      "nonce": "nonce-register-001",
      "privateKeyPkcs8": "<base64-pkcs8-private-key>"
    }
  }
}

3. send_mail

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "send_mail",
    "arguments": {
      "mailboxId": "mbx_agent_001",
      "publicKey": "<base64-ed25519-public-key>",
      "actorId": "agent-runtime",
      "nonce": "nonce-send-001",
      "privateKeyPkcs8": "<base64-pkcs8-private-key>",
      "to": "<recipient-address>",
      "subject": "Project update",
      "bodyText": "Here is the latest status."
    }
  }
}

4. get_mail_attachment

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "get_mail_attachment",
    "arguments": {
      "mailboxId": "mbx_agent_001",
      "publicKey": "<base64-ed25519-public-key>",
      "actorId": "agent-runtime",
      "nonce": "nonce-attachment-001",
      "privateKeyPkcs8": "<base64-pkcs8-private-key>",
      "mailId": "<mail-id>",
      "attachmentId": "0"
    }
  }
}

Tool Reference

create_mailbox

Inputs

Field	Type	Required	Description
mailboxId	string	yes	A client-generated unique mailbox ID.
address	string	yes	The mailbox address to register.
publicKey	base64 Ed25519 raw key	yes	The public key used to control the mailbox.
actorId	string	yes	The signing actor identifier.
nonce	string	yes	Unique per request.
privateKeyPkcs8	base64 PKCS#8	yes	The private key used to sign the request.
currentRatePolicy	string	no	Optional rate policy. Defaults to `default`.

Returns

Field	Type	Description
mailboxId	string	The mailbox ID.
status	`pending_challenge`	The current state.
publicKeyFingerprint	string	The public key fingerprint.
challenge	object	Includes `challengeId`, `challengeType`, `prompt`, and `expiresAt`.

get_mailbox_status

Read mailbox status. This tool does not require a signature.

Inputs

Field	Type	Required	Description
mailboxId	string	no	Use either `mailboxId` or `address`.
address	string	no	Use either `address` or `mailboxId`.

Returns

Field	Type	Description
mailboxId	string	The mailbox ID.
address	string	The mailbox address.
status	string	The current status, such as `pending_challenge` or `active`.
publicKeyFingerprint	string	The current key fingerprint.
currentRatePolicy	string	The current policy name.
createdAt / updatedAt	ISO timestamp	Creation and update timestamps.

answer_challenge

Submit the registration challenge. A successful answer activates the mailbox.

Inputs

Field	Type	Required	Description
mailboxId	string	yes	The mailbox ID.
challengeId	string	yes	Returned by `create_mailbox`.
answer	string	yes	The challenge answer. The default challenge expects a lowercase SHA-256 hex digest.
publicKey	base64 Ed25519 raw key	yes	The current mailbox public key.
actorId / nonce / privateKeyPkcs8	string	yes	Signature material.

Returns

Field	Type	Description
mailboxId	string	The mailbox ID.
status	`active`	The active status after a successful answer.

send_mail

Queue an outbound email. The initial delivery state is `queued`.

Inputs

Field	Type	Required	Description
mailboxId	string	yes	The mailbox ID.
publicKey	base64 Ed25519 raw key	yes	The current mailbox public key.
to	string	yes	The destination email address.
subject	string	no	The mail subject.
bodyText	string	no	Plain-text body content.
attachmentText	string	no	Searchable text extracted from attachments.
actorId / nonce / privateKeyPkcs8	string	yes	Signature material.

Returns

Field	Type	Description
mailId	string	The mail ID.
threadId	string	The thread ID.
folder	`sent`	The current folder.
deliveryStatus	`queued`	The current delivery state.
createdAt	ISO timestamp	Creation time.

list_mails

List mails with cursor-based pagination. Trash is excluded by default.

Inputs

Field	Type	Required	Description
mailboxId	string	yes	The mailbox ID.
publicKey	base64 Ed25519 raw key	yes	The current mailbox public key.
folder	`inbox \| sent \| trash`	no	Filter by folder.
includeTrash	boolean	no	Include trash when `true`.
limit	number	no	Defaults to 20. Maximum 100.
cursor	number	no	Pagination offset.
actorId / nonce / privateKeyPkcs8	string	yes	Signature material.

Returns

Field	Type	Description
mails	MailSummary[]	An array of mail summaries.
nextCursor	number \| null	The next pagination offset.

search_mails

Run full-text search across subject, snippet, body text, and text attachments.

Inputs

Field	Type	Required	Description
mailboxId	string	yes	The mailbox ID.
publicKey	base64 Ed25519 raw key	yes	The current mailbox public key.
query	string	yes	The full-text query.
includeTrash	boolean	no	Include trash when `true`.
limit	number	no	Defaults to 10. Maximum 100.
actorId / nonce / privateKeyPkcs8	string	yes	Signature material.

Returns

Field	Type	Description
mails	MailSummary[]	The matched mail summaries.

get_mail

Fetch the full stored record for a single mail.

Inputs

Field	Type	Required	Description
mailboxId	string	yes	The mailbox ID.
publicKey	base64 Ed25519 raw key	yes	The current mailbox public key.
mailId	string	yes	The mail ID.
actorId / nonce / privateKeyPkcs8	string	yes	Signature material.

Returns

Field	Type	Description
mailId / threadId / mailboxId	string	Identity fields.
direction / folder / deliveryStatus	string	Mail direction, folder, and delivery state.
fromAddress / toAddress / subject / snippet	string	Primary addressing and summary fields.
bodyText / attachmentText	string	Text content ready for model use.
attachments	MailAttachmentSummary[]	Attachment metadata including `attachmentId`, `filename`, and `contentType`.
retentionUntil	ISO timestamp \| null	Trash retention deadline.

get_mail_attachment

Fetch one attachment. The binary stays in private R2 and `core` returns controlled base64 content.

Inputs

Field	Type	Required	Description
mailboxId	string	yes	The mailbox ID.
publicKey	base64 Ed25519 raw key	yes	The current mailbox public key.
mailId	string	yes	The mail ID.
attachmentId	string	yes	The attachment identifier returned by `get_mail`.
actorId / nonce / privateKeyPkcs8	string	yes	Signature material.

Returns

Field	Type	Description
mailId / attachmentId	string	Mail and attachment identifiers.
filename / contentType	string \| null	The attachment filename and MIME type.
encoding	`base64`	The encoding used for the returned payload.
contentBase64	string	The attachment bytes encoded as base64.

delete_mail

Move a mail into trash with a fixed 30-day retention window.

Inputs

Field	Type	Required	Description
mailboxId	string	yes	The mailbox ID.
publicKey	base64 Ed25519 raw key	yes	The current mailbox public key.
mailId	string	yes	The mail ID.
actorId / nonce / privateKeyPkcs8	string	yes	Signature material.

Returns

Field	Type	Description
mailId	string	The mail ID.
folder	`trash`	The target folder.
retentionUntil	ISO timestamp	The cleanup deadline.
retentionDays	`30`	The fixed retention window.

restore_mail

Restore a trashed mail to its prior folder.

Inputs

Field	Type	Required	Description
mailboxId	string	yes	The mailbox ID.
publicKey	base64 Ed25519 raw key	yes	The current mailbox public key.
mailId	string	yes	The mail ID.
actorId / nonce / privateKeyPkcs8	string	yes	Signature material.

Returns

Field	Type	Description
mailId	string	The mail ID.
folder	string	The restored folder.
retentionUntil	ISO timestamp \| null	Usually `null` after restore.

list_threads

List conversation threads with cursor-based pagination.

Inputs

Field	Type	Required	Description
mailboxId	string	yes	The mailbox ID.
publicKey	base64 Ed25519 raw key	yes	The current mailbox public key.
limit	number	no	Defaults to 20. Maximum 100.
cursor	number	no	Pagination offset.
actorId / nonce / privateKeyPkcs8	string	yes	Signature material.

Returns

Field	Type	Description
threads	ThreadSummary[]	The thread summaries.
nextCursor	number \| null	The next pagination offset.

rotate_key

Rotate the mailbox control key.

Inputs

Field	Type	Required	Description
mailboxId	string	yes	The mailbox ID.
currentPublicKey	base64 Ed25519 raw key	yes	The current mailbox key.
nextPublicKey	base64 Ed25519 raw key	yes	The next mailbox key.
actorId / nonce / privateKeyPkcs8	string	yes	The private key must correspond to `currentPublicKey`.

Returns

Field	Type	Description
mailboxId	string	The mailbox ID.
status	string	The mailbox status.
publicKeyFingerprint	string	The fingerprint of the next key.

watch_mailbox

Long-poll the mailbox event stream.

Inputs

Field	Type	Required	Description
mailboxId	string	yes	The mailbox ID.
publicKey	base64 Ed25519 raw key	yes	The current mailbox public key.
cursor	number	no	The starting event cursor.
limit	number	no	Defaults to 50. Maximum 100.
timeoutMs	number	no	Defaults to 1000. Maximum 10000.
actorId / nonce / privateKeyPkcs8	string	yes	Signature material.

Returns

Field	Type	Description
events	DeliveryEventRecord[]	An array of events including `cursor`, `eventId`, `eventType`, and `payload`.
nextCursor	number	The cursor to use for the next poll.
timedOut	boolean	Returns `true` when no new events arrive before the timeout.

Resource subscription

The public resource is `mailbox://{mailbox_id}/events`. It returns JSON with `mailboxId`, `cursor`, `nextCursor`, and `events`. After subscribing, `GET /mcp` yields `notifications/resources/updated` over SSE.

mailbox://{mailbox_id}/events

When subscribing to a resource, send `uri`, `publicKey`, `actorId`, `nonce`, and `privateKeyPkcs8` in `params`.

Common errors

Error	When it happens
missing_mcp_session_id	The request is missing the MCP session header.
missing_mcp_signature_material	A resource request is missing `actorId`, `nonce`, `privateKeyPkcs8`, or `publicKey`.
missing_signature_headers	The signed transport headers are missing.
invalid_signature	Signature verification failed, usually because the key or payload does not match.
invalid_request_signature	The key material or signature payload could not be parsed.
nonce_reuse_with_different_request	The same `actorId + nonce` was reused for a different request body.
challenge_answer_incorrect	The challenge answer is wrong.
challenge_expired	The challenge has expired.
challenge_already_answered	The challenge was already submitted.
mailbox_not_found	The mailbox does not exist or the mailboxId is wrong.
mail_not_found	The requested mail does not exist.
stale_current_public_key	The current key used for rotation is no longer valid.
invalid_public_key	The next public key is malformed.
method_not_supported	The MCP method is not implemented.