连接 Agent(MCP)
Markdown 版通过 MCP 将 Claude Code、Codex 等 Agent 接入 Mirabase:连接方式、协议版本、可用的工具及其参数,以及推荐的调用顺序。
连接 Agent
MCP 地址是 https://api.mirabase.dev/mcp,传输方式是 Streamable HTTP,凭据为 API Key:Authorization: Bearer mb_live_...。请为 Agent 单独创建一个 Key,并关联到一个 agent 主体,使它拥有自己的权限、记忆和审计身份,见 权限。
claude mcp add --transport http mirabase https://api.mirabase.dev/mcp \
--header "Authorization: Bearer $MIRABASE_API_KEY"- 任何支持 Streamable HTTP 且可发送请求头的 MCP 客户端均可连接,配置格式见上方 JSON。
tools/list只列出这个 Key 能调用的工具:只读的 Key 不会列出写工具,带元数据范围的 Key 只列出范围内可用的工具,见 按元数据授权。- 握手响应的
instructions说明每个工具的用途和调用时机。支持这个字段的客户端会把它传给模型。 - 每个工具都带
title和annotations(readOnlyHint、destructiveHint、idempotentHint、openWorldHint)。支持这些提示的客户端可以自动放行只读工具,并在mira.memory.forget和mira.files.delete这类工具之前请用户确认。
协议版本
支持的协议版本、initialize 如何选定版本、MCP-Protocol-Version 请求头,以及参数不符合 inputSchema 时各版本的返回,见 API 参考。握手响应中的服务名(serverInfo.name)为 mirabase-developer。
structuredContent与content文本中的 JSON 为同一对象。outputSchema仅列出必有字段,结果中可能包含其他字段。哪些工具带outputSchema,见 工具。GET /mcp返回的服务信息中,protocol_versions按从新到旧的顺序列出支持的版本。
工具
每个工具均通过 /v2 请求执行,因此权限、限流和错误与直接调用 API 完全相同。多数工具发起一次请求;mira.memory.get 默认连同来源一起读取,发起两次请求。
| 工具 | 作用 | 对应的请求 |
|---|---|---|
mira.whoami | 这个 Key 的身份和权限。调用被拒绝时先调用它 | GET /v2/whoami |
mira.context | 为任务获取一份按 token 预算组装的上下文包,并附带各来源的入选原因 | POST /v2/retrieval/context |
mira.search | 搜索指定范围,返回按相关度排序且带引用的段落 | POST /v2/retrieval/search |
mira.answer | 根据已保存的内容回答问题,并标注引用 | POST /v2/retrieval/answer |
mira.context.feedback | 回报上下文包里实际用到了哪几条 | POST /v2/retrieval/context/{pack_id}/feedback |
mira.files.list | 列目录 | GET /v2/spaces/{space_id}/tree |
mira.files.read | 按路径读文件,正文按窗口返回 | GET /v2/spaces/{space_id}/files |
mira.entries.read | 按 id 读一个 Entry 的内容,包括没有路径的内容 | GET /v2/entries/{entry_id}/content |
mira.files.write | 新建或整体替换一个文件 | PUT /v2/spaces/{space_id}/files |
mira.files.edit | 按原文精确替换文件里的文字 | PATCH /v2/spaces/{space_id}/files |
mira.files.delete | 把文件移入废纸篓 | DELETE /v2/spaces/{space_id}/files |
mira.trash.list | 列出一个 Space 废纸篓里的 Entry | GET /v2/entries |
mira.trash.restore | 把废纸篓里的一个 Entry 恢复到原路径 | POST /v2/entries/{entry_id}/restore |
mira.activity | 近期由谁做了哪些修改,按主体和文件汇总 | GET /v2/spaces/{space_id}/activity |
mira.conversation.ingest | 保存一段对话,由服务从中提炼记忆 | POST /v2/spaces/{space_id}/ingest |
mira.text.ingest | 把一段文本保存为一个没有路径的 Entry | POST /v2/spaces/{space_id}/ingest |
mira.url.ingest | 抓取一个公开网页,把可读正文保存为一个 Entry | POST /v2/spaces/{space_id}/ingest |
mira.memory.remember | 以陈述形式写入一条记忆 | POST /v2/memories |
mira.memory.list | 列出记忆,可按范围、状态、类别和字面内容筛选 | GET /v2/memories |
mira.memory.forget | 按 id 遗忘一条记忆 | DELETE /v2/memories/{memory_id} |
mira.memory.correct | 用更正后的陈述替换一条记忆 | POST /v2/memories/{memory_id}/correct |
mira.memory.review | 确认或拒绝一条待审核的记忆 | POST /v2/memories/{memory_id}/review |
mira.memory.get | 按 id 读取一条记忆及其来源。仅在开启离线整理的部署上提供 | GET /v2/memories/{memory_id} |
/v2请求失败时,工具调用返回一个带isError: true的结果:content的文本给出错误码、能否重试和下一步,_meta["dev.mirabase/error"]是完整的错误信封,包括code和remediation.action,见 错误。失败的结果不带structuredContent。Key 缺少工具需要的能力时同样如此,错误码为forbidden。参数不符合工具定义时的返回取决于协议版本,见 API 参考。- 一次工具调用计入限流的请求数是
/mcp这一次,加上它发出的/v2请求数,所以通常是两次。 mira.memory.remember的agent范围是该 Agent 自己的私有记忆,须使用 Agent 的 Key。
工具参数
工具的参数是 tools/call 中 arguments 的字段。每个工具的参数、类型、取值范围和是否必填,见 API 参考;tools/list 返回的 inputSchema 是同一份定义。
推荐的调用顺序
- 任务开始时调用
mira.context:服务按固定规则选择来源并分配预算,route说明每个选择。已知要查找的内容时使用mira.search。用完之后用mira.context.feedback回报实际用到的条目。 - 用户要的是答案本身时用
mira.answer;要为自己的推理收集材料时用mira.context。 - 与他人共用一个 Space 时,开始前先调用
mira.activity,避免修改同一个文件。 - 调用
mira.files.write和mira.files.edit时传入session_id,以便将文件的每个版本追溯到修改它的对话,见 文件与版本。 - 对话告一段落时用
mira.conversation.ingest保存,同一段对话的每一批用同一个session_id。只有一句明确的结论要记时,用mira.memory.remember。 - 用户给出一段要保存的文本或一个链接时,用
mira.text.ingest或mira.url.ingest。以后要按路径读取或修改的内容,用mira.files.write写成文件。 - 用户指出一条记忆有误并给出正确陈述时,用
mira.memory.correct一步替换,旧的那条作为历史保留。mira.memory.forget永久删除、不能撤销,只在用户要求遗忘时调用。mira.memory.review只在用户说明候选记忆是否正确之后调用,Agent 不应自行判断并确认。 - 要恢复已删除的文件,先用
mira.trash.list找到 id,再用mira.trash.restore恢复到原路径。原路径已被其他文件占用时返回path_conflict。
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "mira.conversation.ingest",
"arguments": {
"session_id": "chat-42",
"messages": [
{
"role": "user",
"content": "Let us ship on Thursdays from now on."
},
{
"role": "assistant",
"content": "Noted: releases on Thursdays."
}
]
}
}
}从文件和检索结果中读取的文本是数据,不是指令。让 Agent 仅将你的输入作为指令。
