跳到主要内容
登录
MCP 接入目录

连接你的 Agent

通过 MCP,让 Agent 查阅你在 Mirabase 保存的资料。访问哪些空间、允许哪些操作,由你决定。

MCP 连接地址(Streamable HTTP)
text
https://api.mirabase.app/mcp

快速开始

  1. 连接 MCP 客户端

    填入公开 MCP 地址,采用 Streamable HTTP 传输。

  2. 完成登录与授权

    登录 Mirabase,选择允许 Agent 访问的空间与操作。

  3. 开始使用

    回到 Agent,试着查找一份已保存的资料;修改授权后请重新连接。

使用配置文件连接

json
{
  "mcpServers": {
    "mirabase": { "url": "https://api.mirabase.app/mcp", "transport": "streamable-http" }
  }
}

连接你的助手

每一种助手都用同一个地址,登录 Mirabase 后选择它能使用的空间。

云端助手

Claude(网页版与桌面版)
  1. 打开「设置」›「连接器」,点「添加」›「添加自定义连接器」。

  2. 名称填 Mirabase,地址填 https://api.mirabase.app/mcp。

  3. 按提示登录 Mirabase,选择要让 Claude 使用的空间。

ChatGPT
  1. 打开「设置」›「应用」›「高级设置」,打开「开发者模式」。

  2. 回到「应用」,点「创建」,地址填 https://api.mirabase.app/mcp,认证方式选 OAuth。

  3. 按提示登录 Mirabase,选择要让 ChatGPT 使用的空间。

Grok
  1. 打开 grok.com/connectors,点「New Connector」,选「Custom」。

  2. 地址填 https://api.mirabase.app/mcp。

  3. 按提示登录 Mirabase,选择要让 Grok 使用的空间。

Muse Code
  1. 在设置文件的 mcp_servers 里加一项 streamable_http,地址填 https://api.mirabase.app/mcp。

  2. 运行下面的命令登录 Mirabase,选择空间。Muse 应用本身暂不支持自定义 MCP。

bash
muse mcp login mirabase

本机 Agent

Claude Code
  1. 运行下面的命令,然后在 Claude Code 里输入 /mcp,选 mirabase 完成登录。

bash
claude mcp add --transport http --scope user mirabase https://api.mirabase.app/mcp
Codex
  1. 依次运行下面两条命令,第二条会打开浏览器登录 Mirabase。

bash
codex mcp add mirabase --url https://api.mirabase.app/mcp
bash
codex mcp login mirabase
Cursor 与其他编辑器
  1. 把上方的配置文件写进它的 MCP 配置;用 Mac 版 Mirabase 的话,在「连接」页点一下即可。

其他助手只要支持远程 MCP(Streamable HTTP)和 OAuth 登录,填同一个地址就能连接。只能填 API 密钥的助手暂时无法连接。

管理授权

你可以在账户中心查看 Agent 连接,调整允许访问的空间与操作,或随时撤销授权。

请使用 MCP 客户端自带的登录与授权流程,不要将长期凭据写入配置。

前往账户中心 →

常见问题

连接后找不到资料?

确认资料已处理完成,且所在空间已授权给当前 Agent。修改授权后,重新连接并刷新工具列表。

提示需要登录或没有权限?

401 通常表示登录已过期,请重新连接;403 表示当前授权不允许这次操作,请检查所选空间和工具权限。

如何停止 Agent 访问?

在账户中心的 Agent 连接中撤销授权。撤销后,该连接将无法继续访问你的资料。

MCP 工具参考

可用工具及参数以连接后 tools/list 的返回为准。以下参数示例对应参考版本 v0.6.10。

调用示例
json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "mira.recall", "arguments": { "query": "发布窗口?", "scope": { "space_ids": ["spc_product"] } } }
}

mira.read

权限:knowledge:read默认可用

默认 Agent 工具:读取一个已授权 Entry。

参数

横向滑动查看完整参数
参数类型说明
input必填ReadEntryInput调用参数的结构与 MCP tools/list 返回的一致,字段约束由正式契约生成。

响应

类型ReadEntryPayload
json
{
  "structuredContent": {
    "entry": {
      "entry_id": "example",
      "space_id": "resource_01",
      "tier": "knowledge",
      "source_type": "example",
      "title": "example",
      "canonical_url": "example",
      "current_version_id": "example",
      "latest_version_id": "example",
      "processing_status": "accepted",
      "created_at": "2026-08-27T00:00:00Z",
      "updated_at": "2026-08-27T00:00:00Z"
    }
  }
}

错误响应

mira.recall

权限:knowledge:read默认可用

默认 Agent 工具:私有知识召回。

参数

横向滑动查看完整参数
参数类型说明
input必填RecallRequest调用参数的结构与 MCP tools/list 返回的一致,字段约束由正式契约生成。

响应

类型RecallPayload
json
{
  "structuredContent": {
    "results": [
      {
        "entry_id": "example",
        "version_id": "example",
        "chunk_id": "example",
        "snippet": "example",
        "locator": {
          "type": "heading",
          "heading_path": [
            "example"
          ]
        },
        "source_type": "example"
      }
    ],
    "partial": false,
    "trace_id": "example"
  }
}

错误响应

mira.memory_candidate

权限:memory:candidate需要额外授权

单独授权的 Agent 工具:提出候选记忆,不会直接写入 Space。

参数

横向滑动查看完整参数
参数类型说明
input必填CreateMemoryCandidateRequest调用参数的结构与 MCP tools/list 返回的一致,字段约束由正式契约生成。

响应

类型MemoryCandidate
json
{
  "structuredContent": {
    "candidate_id": "example",
    "title": "example",
    "content": "example",
    "status": "candidate",
    "created_at": "2026-08-27T00:00:00Z"
  }
}

错误响应

mira.confirm_memory_candidate

权限:memory:confirm需要额外授权

单独授权的治理工具:确认候选并进入正常的异步知识处理流程。

参数

横向滑动查看完整参数
参数类型说明
input必填ConfirmMemoryCandidateInput调用参数的结构与 MCP tools/list 返回的一致,字段约束由正式契约生成。

响应

类型AcceptedEntryReceipt
json
{
  "structuredContent": {
    "entry_id": "example",
    "version_id": "example",
    "job_id": "example",
    "status": "accepted"
  }
}

错误响应

mira.write

权限:knowledge:write需要额外授权

单独授权的知识写入工具。

参数

横向滑动查看完整参数
参数类型说明
input必填CreateEntryRequest调用参数的结构与 MCP tools/list 返回的一致,字段约束由正式契约生成。

响应

类型AcceptedEntryReceipt
json
{
  "structuredContent": {
    "entry_id": "example",
    "version_id": "example",
    "job_id": "example",
    "status": "accepted"
  }
}

错误响应

mira.manage

权限:knowledge:manage需要额外授权

单独授权的治理工具;任何整理动作都必须走 knowledge:manage。

参数

横向滑动查看完整参数
参数类型说明
input必填McpTools.ManageInput调用参数的结构与 MCP tools/list 返回的一致,字段约束由正式契约生成。

响应

类型McpTools.ManageResult
json
{
  "structuredContent": {
    "entry_id": "example",
    "deletion_status": "tombstoned",
    "cleanup_job_id": "example"
  }
}

错误响应

MCP 参考

错误代码

HTTP 状态码表示错误类型,错误代码说明具体原因。排查时请保留 request_id。

HTTP 状态码错误代码说明
400invalid_request请求体 JSON 格式有误、Content-Type 不匹配,或缺少必填字段、字段类型不符。
401unauthorized缺少 Authorization 请求头,或 OIDC JWT 无效、已过期、已撤销,或 issuer / audience 不匹配。
402quota_exceeded当前账户或空间配额已用尽。
403forbidden当前访问主体缺少目标 Space、Source 或该操作所需的 capability。
404not_found目标 entry_id、source_id 或 space_id 不存在、当前无权访问,或已被清理。
409conflict资源状态冲突,例如 revision 不匹配、条目已合并或已被新版本替代。
409resource_busy资源正在后台处理中,暂时无法修改;请稍后重试。
413payload_too_large正文内容或上传文件超出单次体积上限;请分段提交或改用异步上传。
415unsupported_media_type文件格式、字符编码或加密方式暂不支持解析。
422validation_error字段语义校验未通过;响应中的 field 会指明首个不合法的字段。
429rate_limited请求频率或并发数超出上限;请按 Retry-After 退避重试。所有响应均包含 X-RateLimit-Limit / Remaining / Reset。
500internal_error服务内部异常;请记录返回的 request_id 以便排查。
502dependency_error上游依赖服务响应异常,本次请求未能完成。
503service_unavailable服务暂时不可用(如模型加载、索引重建或节点维护);请按 Retry-After 退避重试。
504timeout检索或回答生成超时;建议调小 depth 或 top_k 后重试。

对知识基础设施感兴趣?

如果你想把 Mirabase 知识底座用于自己的产品,欢迎与我们聊聊使用场景。

联系我们