# 连接 Agent（MCP）

通过 MCP 将 Claude Code、Codex 等 Agent 接入 Mirabase：连接方式、协议版本、可用的工具及其参数，以及推荐的调用顺序。

## 连接 Agent

MCP 地址是 `https://api.mirabase.dev/mcp`，传输方式是 Streamable HTTP，凭据为 API Key：`Authorization: Bearer mb_live_...`。请为 Agent 单独创建一个 Key，并关联到一个 `agent` 主体，使它拥有自己的权限、记忆和审计身份，见 [权限](https://mirabase.io/zh/developers/permissions.md#principals)。

Claude Code:

```bash
claude mcp add --transport http mirabase https://api.mirabase.dev/mcp \
  --header "Authorization: Bearer $MIRABASE_API_KEY"
```

Codex:

```bash
codex mcp add mirabase --url https://api.mirabase.dev/mcp \
  --bearer-token-env-var MIRABASE_API_KEY
```

JSON:

```json
{
  "mcpServers": {
    "mirabase": {
      "type": "http",
      "url": "https://api.mirabase.dev/mcp",
      "headers": {
        "Authorization": "Bearer mb_live_..."
      }
    }
  }
}
```

- 任何支持 Streamable HTTP 且可发送请求头的 MCP 客户端均可连接，配置格式见上方 JSON。
- `tools/list` 只列出这个 Key 能调用的工具：只读的 Key 不会列出写工具，带元数据范围的 Key 只列出范围内可用的工具，见 [按元数据授权](https://mirabase.io/zh/developers/authentication.md#metadata-scope)。
- 握手响应的 `instructions` 说明每个工具的用途和调用时机。支持这个字段的客户端会把它传给模型。
- 每个工具都带 `title` 和 `annotations`（`readOnlyHint`、`destructiveHint`、`idempotentHint`、`openWorldHint`）。支持这些提示的客户端可以自动放行只读工具，并在 `mira.memory.forget` 和 `mira.files.delete` 这类工具之前请用户确认。

## 协议版本

支持的协议版本、`initialize` 如何选定版本、`MCP-Protocol-Version` 请求头，以及参数不符合 `inputSchema` 时各版本的返回，见 [API 参考](https://mirabase.io/zh/developers/api/mcp.md#mcp-rpc)。握手响应中的服务名（`serverInfo.name`）为 `mirabase-developer`。

- `structuredContent` 与 `content` 文本中的 JSON 为同一对象。`outputSchema` 仅列出必有字段，结果中可能包含其他字段。哪些工具带 `outputSchema`，见 [工具](https://mirabase.io/zh/developers/api/mcp.md#tools)。
- [`GET /mcp`](https://mirabase.io/zh/developers/api/mcp.md#mcp-handshake) 返回的服务信息中，`protocol_versions` 按从新到旧的顺序列出支持的版本。

## 工具

每个工具均通过 `/v2` 请求执行，因此权限、限流和错误与直接调用 API 完全相同。多数工具发起一次请求；`mira.memory.get` 默认连同来源一起读取，发起两次请求。

| 工具 | 作用 | 对应的请求 |
| --- | --- | --- |
| `mira.whoami` | 这个 Key 的身份和权限。调用被拒绝时先调用它 | [`GET /v2/whoami`](https://mirabase.io/zh/developers/api/identity.md#identity-whoami) |
| `mira.context` | 为任务获取一份按 token 预算组装的上下文包，并附带各来源的入选原因 | [`POST /v2/retrieval/context`](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-buildcontext) |
| `mira.search` | 搜索指定范围，返回按相关度排序且带引用的段落 | [`POST /v2/retrieval/search`](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-search) |
| `mira.answer` | 根据已保存的内容回答问题，并标注引用 | [`POST /v2/retrieval/answer`](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-answer) |
| `mira.context.feedback` | 回报上下文包里实际用到了哪几条 | [`POST /v2/retrieval/context/{pack_id}/feedback`](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-contextfeedback) |
| `mira.files.list` | 列目录 | [`GET /v2/spaces/{space_id}/tree`](https://mirabase.io/zh/developers/api/tree.md#tree-list) |
| `mira.files.read` | 按路径读文件，正文按窗口返回 | [`GET /v2/spaces/{space_id}/files`](https://mirabase.io/zh/developers/api/files.md#files-read) |
| `mira.entries.read` | 按 id 读一个 Entry 的内容，包括没有路径的内容 | [`GET /v2/entries/{entry_id}/content`](https://mirabase.io/zh/developers/api/entries.md#entries-content) |
| `mira.files.write` | 新建或整体替换一个文件 | [`PUT /v2/spaces/{space_id}/files`](https://mirabase.io/zh/developers/api/files.md#files-write) |
| `mira.files.edit` | 按原文精确替换文件里的文字 | [`PATCH /v2/spaces/{space_id}/files`](https://mirabase.io/zh/developers/api/files.md#files-patch) |
| `mira.files.delete` | 把文件移入废纸篓 | [`DELETE /v2/spaces/{space_id}/files`](https://mirabase.io/zh/developers/api/files.md#files-delete) |
| `mira.trash.list` | 列出一个 Space 废纸篓里的 Entry | [`GET /v2/entries`](https://mirabase.io/zh/developers/api/entries.md#entries-list) |
| `mira.trash.restore` | 把废纸篓里的一个 Entry 恢复到原路径 | [`POST /v2/entries/{entry_id}/restore`](https://mirabase.io/zh/developers/api/entries.md#entries-restore) |
| `mira.activity` | 近期由谁做了哪些修改，按主体和文件汇总 | [`GET /v2/spaces/{space_id}/activity`](https://mirabase.io/zh/developers/api/changes.md#changes-activity) |
| `mira.conversation.ingest` | 保存一段对话，由服务从中提炼记忆 | [`POST /v2/spaces/{space_id}/ingest`](https://mirabase.io/zh/developers/api/ingest.md#ingest-ingest) |
| `mira.text.ingest` | 把一段文本保存为一个没有路径的 Entry | [`POST /v2/spaces/{space_id}/ingest`](https://mirabase.io/zh/developers/api/ingest.md#ingest-ingest) |
| `mira.url.ingest` | 抓取一个公开网页，把可读正文保存为一个 Entry | [`POST /v2/spaces/{space_id}/ingest`](https://mirabase.io/zh/developers/api/ingest.md#ingest-ingest) |
| `mira.memory.remember` | 以陈述形式写入一条记忆 | [`POST /v2/memories`](https://mirabase.io/zh/developers/api/memories.md#memories-create) |
| `mira.memory.list` | 列出记忆，可按范围、状态、类别和字面内容筛选 | [`GET /v2/memories`](https://mirabase.io/zh/developers/api/memories.md#memories-list) |
| `mira.memory.forget` | 按 id 遗忘一条记忆 | [`DELETE /v2/memories/{memory_id}`](https://mirabase.io/zh/developers/api/memories.md#memories-forget) |
| `mira.memory.correct` | 用更正后的陈述替换一条记忆 | [`POST /v2/memories/{memory_id}/correct`](https://mirabase.io/zh/developers/api/memories.md#memories-correct) |
| `mira.memory.review` | 确认或拒绝一条待审核的记忆 | [`POST /v2/memories/{memory_id}/review`](https://mirabase.io/zh/developers/api/memories.md#memories-review) |
| `mira.memory.get` | 按 id 读取一条记忆及其来源。仅在开启离线整理的部署上提供 | [`GET /v2/memories/{memory_id}`](https://mirabase.io/zh/developers/api/memories.md#memories-read) |

- `/v2` 请求失败时，工具调用返回一个带 `isError: true` 的结果：`content` 的文本给出错误码、能否重试和下一步，`_meta["dev.mirabase/error"]` 是完整的错误信封，包括 `code` 和 `remediation.action`，见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)。失败的结果不带 `structuredContent`。Key 缺少工具需要的能力时同样如此，错误码为 `forbidden`。参数不符合工具定义时的返回取决于协议版本，见 [API 参考](https://mirabase.io/zh/developers/api/mcp.md#mcp-rpc)。
- 一次工具调用计入限流的请求数是 `/mcp` 这一次，加上它发出的 `/v2` 请求数，所以通常是两次。
- `mira.memory.remember` 的 `agent` 范围是该 Agent 自己的私有记忆，须使用 Agent 的 Key。

## 工具参数

工具的参数是 `tools/call` 中 `arguments` 的字段。每个工具的参数、类型、取值范围和是否必填，见 [API 参考](https://mirabase.io/zh/developers/api/mcp.md#tools)；`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`，以便将文件的每个版本追溯到修改它的对话，见 [文件与版本](https://mirabase.io/zh/developers/files.md#versions)。
- 对话告一段落时用 `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 仅将你的输入作为指令。

## 下一步

- [权限](https://mirabase.io/zh/developers/permissions.md)：配置 Agent 的写入模式、读取根路径和写入根路径。
- [分支](https://mirabase.io/zh/developers/branches.md)：让 Agent 在分支上工作，合并前可以审查。
- [记忆](https://mirabase.io/zh/developers/memory.md)：审核 Agent 记录的记忆。
