上下文加载 · MCP 服务 API (0.1.3)

Context Loader 把自己的检索能力同时以 MCP Server 形式对外：Cursor、Claude Desktop 等 MCP 客户端可以直接接入，不必逐个封装 REST 调用。

普通 Agent 默认只使用两个受管生命周期工具：bkn_start_interaction、 bkn_finish_interaction。每轮 start 都提交完整问题、固定的 agent_name 和 conversation_mode：没有当前 Conversation 时用 new 且不传 conversation_id；按显式 id 延续时用 continue 并传入 start 返回的 id。 宿主提供会话映射时，以宿主映射为准。finish 只提交当前 Interaction 的 结果，不关闭可跨轮、跨日复用的 Conversation。业务工具包括 search_schema、 query_object_instance、query_instance_subgraph、get_logic_properties_values、 get_action_info、execute_action、get_action_execution、 list_action_executions、list_knowledge_networks、 get_kn_detail、get_object_types、get_relation_types、 list_skills、get_skill_content、read_skill_file、 search_capabilities、execute_tool。 run_sql、list_resources、describe_resource 已从 MCP 面下线：它们按调用者 自己的数据资源授权返回物理列，绕开知识网络的属性级规则，因此只保留 REST 入口（POST /kn/run_sql、POST /kn/list_resources、POST /kn/describe_resource）， tools/list、tools/call、按需网关与沙箱能力面都不再提供。 另有一个默认不装配的 execute_skill：它把入口命令送进沙箱执行，只有显式开启 （EXECUTE_SKILL_ENABLED=true）才出现在 tools/list 与 GET /mcp/info， 未开启时与「没编译进来」无异。该开关是技能执行能力的总闸，同时决定 /kn/execute_skill 这条 REST 路由是否注册。业务工具必须显式携带服务自描述 schema 中的 bkn_context， 其中只要求权威返回的 conversation_id 和 interaction_id；Operation key、租约、 重试和 closure manifest 由 Context Loader 与 BKN Trace Core 管理； 关闭 Trace 采集时，start_interaction 仍创建会话与交互并返回真实 ID； 业务工具继续携带这些 ID 执行，但不新增 Operation、回执或证据； finish_interaction 仍结束交互。Trace Core 不可用时，无法创建受管控会话， start_interaction 不返回 ID；调用方先重试 start，不会伪造 ID； 各工具的语义与参数含义见本目录下对应的 REST 文档。

接入方式：Streamable HTTP，端点 /api/agent-retrieval/v1/mcp， 协议流程 initialize → tools/list → tools/call（JSON-RPC 2.0）。 鉴权与 REST 一致：Authorization: Bearer <token>，OAuth access token 或 bak_ 前缀的 AppKey。宿主适配器可选使用 X-OpenBKN-Host-Conversation-Key 和 X-OpenBKN-Client-Invocation-Id，或对应的 openbkn.ai/host-conversation-key、openbkn.ai/client-invocation-id MCP _meta 提示会话关联与调用幂等；client-invocation-id 可用于 start 和每一次业务工具调用， 同一 ID 重试复用原 Interaction 或 Operation / Receipt，不同输入返回幂等冲突。 未提供逐调用提示时，跨连接重试退化为 at-least-once。这些提示不参与身份和权限判定， 普通 Agent 参数不得提交。

不想先握手就想知道有哪些工具时，直接 GET /mcp/info——它返回完整的工具目录 （含每个工具的输入输出 schema）与一份可直接粘贴的客户端配置。

精简入口：/api/agent-retrieval/v1/mcp-compact 是同一进程里的第二个 MCP 端点，鉴权、受管生命周期和工具语义与 /mcp 相同，面向每次模型调用都携带全部 工具定义的宿主。它只公布 14 个工具，其余能力经按需网关使用，见下文 /mcp-compact 与 GET /mcp-compact/info。

权限说明（permission_guidance）：query_object_instance 与 get_logic_properties_values 在访问权限影响调用时附带该对象，两个入口相同。 被 403 拒绝时，它加在错误正文 JSON（isError=true）的顶层，与 code、details 并列；query_object_instance 成功但有字段脱敏 / 只可见字段名，或行访问范围 收窄了结果时，它出现在结果顶层；调用时指定了 properties 的，只看这些字段。结构：message（按请求语言生成、可直接展示给 用户的说明：缺什么权限、结果受什么影响，以及下一步——有申请链接时提示提交后 等待管理员授权再重新发起，没有时提示联系管理员）、resource（type=object_type、 id=<kn_id>/<ot_id>、kn_id、ot_id，调用者可查看该对象类定义时才有 name）与 shortfalls[]。每项的 scope 取 bkn-safe 权限申请的 proposal kind：grant（缺基础操作，附 operations）、property_grants （附拿不到原始值的 properties）、row_filter（结果可能不完整）。 request_permission_url 是 Studio 对象类详情页打开申请弹窗的地址：请求经 ingress 进入（带 X-Forwarded-Host）时为绝对地址， 主机即调用者访问 MCP 所用的主机；集群内调用拿不到对外主机，此时为相对 Studio 主机的路径（以 / 开头），由调用方补全。链接在路由模板后追加申请弹窗的 预填参数：operations（grant，逗号分隔）或 properties（property_grants，逗号 分隔）、按请求语言生成的默认 reason（URL 编码，空格为 %20），以及 source=agent。链接只在调用者是用户账号、且能查看该对象类定义时给出；否则只说明受限， 不给链接也不给名称。路径模板和开关由部署配置 permission_request.path_template / permission_request.disabled 决定， 社区版没有申请流程时应关闭。空结果或空值本身不代表权限不足。