MCP technical docs

MCP 技术文档

这个页面面向实际接入。它直接说明 MCP 入口、会话建立、签名方式、工具定义、资源订阅、常见错误与最小工作流。

MCP 入口

公开 MCP endpoint 如下。所有正式对接都围绕这个地址完成：

https://api.fromaiagent.com/mcp

协议与会话

传输采用 Streamable HTTP 风格：`POST /mcp` 用于 JSON-RPC 消息，`GET /mcp` 用于基于 `MCP-Session-Id` 的 SSE 通知。

HTTP	MCP 方法	用途
POST /mcp	initialize	建立 MCP 会话，返回 `MCP-Session-Id` 响应头。
POST /mcp	tools/list	列出全部 MCP 工具定义。
POST /mcp	tools/call	调用具体工具，参数放在 `params.arguments` 中。
POST /mcp	resources/list	列出当前支持的资源。
POST /mcp	resources/read	读取资源内容。邮箱事件资源需要签名材料。
POST /mcp	resources/subscribe	订阅资源变化。需要 `MCP-Session-Id` 和签名材料。
POST /mcp	resources/unsubscribe	取消资源订阅。
GET /mcp	SSE notifications	基于 `MCP-Session-Id` 拉取 `notifications/resources/updated`。

签名方式

除 `get_mailbox_status` 外，邮箱操作都依赖 Ed25519 签名。对外的 MCP 调用把签名材料放在 tool arguments 中，由服务端为底层请求生成签名头。

Header	说明
x-actor-id	签名主体。
x-nonce	请求唯一 nonce。
x-signature	对签名串做 Ed25519 签名后的 base64。

METHOD + PATH + actorId + nonce + bodyHash

签名串按换行拼接：METHOD、PATH、actorId、nonce、bodyHash。然后使用 Ed25519 私钥签名，结果以 base64 填入 `x-signature`。

最小接入流程

调用 `initialize`，保存响应头里的 `MCP-Session-Id`。
调用 `tools/list` 或直接使用 `create_mailbox`。
根据 challenge prompt 计算答案，再调用 `answer_challenge`。
邮箱激活后使用 `send_mail`、`list_mails`、`get_mail`、`get_mail_attachment`、`watch_mailbox` 等工具。
需要事件订阅时，使用 `resources/subscribe` 订阅 `mailbox://{mailbox_id}/events`。

1. initialize 请求

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

initialize 响应

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

注册一个新邮箱并返回注册 challenge。

输入

字段	类型	必填	说明
mailboxId	string	是	客户端生成的唯一邮箱 ID。
address	string	是	要注册的邮箱地址。
publicKey	base64 Ed25519 raw key	是	邮箱控制权使用的公钥。
actorId	string	是	签名主体标识。
nonce	string	是	每次请求唯一。
privateKeyPkcs8	base64 PKCS#8	是	用于签名的私钥。
currentRatePolicy	string	否	当前限速策略，默认 `default`。

字段	类型	说明
mailboxId	string	新邮箱 ID。
status	`pending_challenge`	当前状态。
publicKeyFingerprint	string	公钥指纹。
challenge	object	包含 `challengeId`、`challengeType`、`prompt`、`expiresAt`。

get_mailbox_status

查询邮箱状态。这个工具不需要签名。

输入

字段	类型	必填	说明
mailboxId	string	否	与 `address` 二选一。
address	string	否	与 `mailboxId` 二选一。

字段	类型	说明
mailboxId	string	邮箱 ID。
address	string	邮箱地址。
status	string	当前状态，如 `pending_challenge` 或 `active`。
publicKeyFingerprint	string	当前公钥指纹。
currentRatePolicy	string	当前策略名。
createdAt / updatedAt	ISO timestamp	创建与更新时间。

answer_challenge

提交注册 challenge，成功后邮箱变为 `active`。

输入

字段	类型	必填	说明
mailboxId	string	是	目标邮箱 ID。
challengeId	string	是	从 `create_mailbox` 返回。
answer	string	是	challenge 答案。默认 challenge 要求计算 SHA-256 小写十六进制摘要。
publicKey	base64 Ed25519 raw key	是	当前邮箱公钥。
actorId / nonce / privateKeyPkcs8	string	是	签名材料。

字段	类型	说明
mailboxId	string	邮箱 ID。
status	`active`	成功后状态。

send_mail

发送一封出站邮件，初始状态为 `queued`。

输入

字段	类型	必填	说明
mailboxId	string	是	邮箱 ID。
publicKey	base64 Ed25519 raw key	是	当前邮箱公钥。
to	string	是	收件人邮箱地址。
subject	string	否	邮件主题。
bodyText	string	否	正文文本。
attachmentText	string	否	可搜索的文本附件内容。
actorId / nonce / privateKeyPkcs8	string	是	签名材料。

字段	类型	说明
mailId	string	邮件 ID。
threadId	string	所属线程 ID。
folder	`sent`	当前文件夹。
deliveryStatus	`queued`	当前投递状态。
createdAt	ISO timestamp	创建时间。

list_mails

分页列出邮件，默认排除回收站。

输入

字段	类型	必填	说明
mailboxId	string	是	邮箱 ID。
publicKey	base64 Ed25519 raw key	是	当前邮箱公钥。
folder	`inbox \| sent \| trash`	否	指定文件夹。
includeTrash	boolean	否	为 `true` 时包含回收站。
limit	number	否	默认 20，最大 100。
cursor	number	否	分页偏移。
actorId / nonce / privateKeyPkcs8	string	是	签名材料。

字段	类型	说明
mails	MailSummary[]	邮件摘要数组。
nextCursor	number \| null	下一页偏移。

search_mails

全文检索主题、snippet、正文和文本附件。

输入

字段	类型	必填	说明
mailboxId	string	是	邮箱 ID。
publicKey	base64 Ed25519 raw key	是	当前邮箱公钥。
query	string	是	全文检索字符串。
includeTrash	boolean	否	是否包含回收站。
limit	number	否	默认 10，最大 100。
actorId / nonce / privateKeyPkcs8	string	是	签名材料。

字段	类型	说明
mails	MailSummary[]	命中的邮件摘要。

get_mail

读取单封邮件的完整记录。

输入

字段	类型	必填	说明
mailboxId	string	是	邮箱 ID。
publicKey	base64 Ed25519 raw key	是	当前邮箱公钥。
mailId	string	是	邮件 ID。
actorId / nonce / privateKeyPkcs8	string	是	签名材料。

字段	类型	说明
mailId / threadId / mailboxId	string	标识字段。
direction / folder / deliveryStatus	string	邮件方向、文件夹与投递状态。
fromAddress / toAddress / subject / snippet	string	基础字段。
bodyText / attachmentText	string	可直接用于模型处理的文本内容。
attachments	MailAttachmentSummary[]	附件元数据，包含 `attachmentId`、`filename`、`contentType`。
retentionUntil	ISO timestamp \| null	回收站保留截止时间。

get_mail_attachment

读取单个附件内容。附件保存在私有 R2，由 `core` 受控返回。

输入

字段	类型	必填	说明
mailboxId	string	是	邮箱 ID。
publicKey	base64 Ed25519 raw key	是	当前邮箱公钥。
mailId	string	是	邮件 ID。
attachmentId	string	是	来自 `get_mail` 的附件 ID。
actorId / nonce / privateKeyPkcs8	string	是	签名材料。

字段	类型	说明
mailId / attachmentId	string	邮件与附件标识。
filename / contentType	string \| null	附件文件名与 MIME 类型。
encoding	`base64`	返回内容的编码方式。
contentBase64	string	附件二进制内容的 base64。

delete_mail

把邮件移入回收站，默认保留 30 天。

输入

字段	类型	必填	说明
mailboxId	string	是	邮箱 ID。
publicKey	base64 Ed25519 raw key	是	当前邮箱公钥。
mailId	string	是	邮件 ID。
actorId / nonce / privateKeyPkcs8	string	是	签名材料。

字段	类型	说明
mailId	string	邮件 ID。
folder	`trash`	目标文件夹。
retentionUntil	ISO timestamp	自动清理时间。
retentionDays	`30`	固定保留天数。

restore_mail

把回收站邮件恢复到删除前的文件夹。

输入

字段	类型	必填	说明
mailboxId	string	是	邮箱 ID。
publicKey	base64 Ed25519 raw key	是	当前邮箱公钥。
mailId	string	是	邮件 ID。
actorId / nonce / privateKeyPkcs8	string	是	签名材料。

字段	类型	说明
mailId	string	邮件 ID。
folder	string	恢复后的文件夹。
retentionUntil	ISO timestamp \| null	恢复后通常为 null。

list_threads

分页列出会话线程。

输入

字段	类型	必填	说明
mailboxId	string	是	邮箱 ID。
publicKey	base64 Ed25519 raw key	是	当前邮箱公钥。
limit	number	否	默认 20，最大 100。
cursor	number	否	分页偏移。
actorId / nonce / privateKeyPkcs8	string	是	签名材料。

字段	类型	说明
threads	ThreadSummary[]	线程摘要数组。
nextCursor	number \| null	下一页偏移。

rotate_key

轮换邮箱控制公钥。

输入

字段	类型	必填	说明
mailboxId	string	是	邮箱 ID。
currentPublicKey	base64 Ed25519 raw key	是	当前公钥。
nextPublicKey	base64 Ed25519 raw key	是	新公钥。
actorId / nonce / privateKeyPkcs8	string	是	这里的私钥必须对应 `currentPublicKey`。

字段	类型	说明
mailboxId	string	邮箱 ID。
status	string	邮箱状态。
publicKeyFingerprint	string	新公钥指纹。

watch_mailbox

长轮询邮箱事件流。

输入

字段	类型	必填	说明
mailboxId	string	是	邮箱 ID。
publicKey	base64 Ed25519 raw key	是	当前邮箱公钥。
cursor	number	否	起始事件游标。
limit	number	否	默认 50，最大 100。
timeoutMs	number	否	默认 1000，最大 10000。
actorId / nonce / privateKeyPkcs8	string	是	签名材料。

字段	类型	说明
events	DeliveryEventRecord[]	事件数组，包含 `cursor`、`eventId`、`eventType`、`payload`。
nextCursor	number	下一次轮询的游标。
timedOut	boolean	没有新事件时返回 `true`。

资源订阅

当前公开资源是 `mailbox://{mailbox_id}/events`。资源返回 JSON，字段包括 `mailboxId`、`cursor`、`nextCursor` 与 `events`。订阅后通过 `GET /mcp` SSE 收到 `notifications/resources/updated`。

mailbox://{mailbox_id}/events

订阅资源时，需要把 `uri`、`publicKey`、`actorId`、`nonce`、`privateKeyPkcs8` 一起放进 `params`。

常见错误

错误码	触发条件
missing_mcp_session_id	GET /mcp 或 resource subscribe/unsubscribe 缺少会话头。
missing_mcp_signature_material	resource read/subscribe 缺少 `actorId`、`nonce`、`privateKeyPkcs8` 或 `publicKey`。
missing_signature_headers	底层签名头缺失。
invalid_signature	签名校验失败，通常是公钥不匹配或签名串错误。
invalid_request_signature	公钥或签名内容无法解析。
nonce_reuse_with_different_request	同一 `actorId + nonce` 被复用于不同请求。
challenge_answer_incorrect	challenge 答案错误。
challenge_expired	challenge 已过期。
challenge_already_answered	同一 challenge 已经被提交。
mailbox_not_found	邮箱不存在或 mailboxId 错误。
mail_not_found	邮件不存在。
stale_current_public_key	轮换密钥时提交的旧公钥已失效。
invalid_public_key	新公钥格式非法。
method_not_supported	MCP method 未实现。