跳到主要内容
开发者文档
文档目录

连接 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 Code
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 废纸篓里的 EntryGET /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把一段文本保存为一个没有路径的 EntryPOST /v2/spaces/{space_id}/ingest
mira.url.ingest抓取一个公开网页,把可读正文保存为一个 EntryPOST /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。
json
{
  "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 仅将你的输入作为指令。

下一步

  • 权限:配置 Agent 的写入模式、读取根路径和写入根路径。
  • 分支:让 Agent 在分支上工作,合并前可以审查。
  • 记忆:审核 Agent 记录的记忆。