接入地址与鉴权规则
- 端点地址:
https://apemind.ai/mcp/(私有化部署替换为 https://<APEMIND_HOST>/mcp/,注意保留末尾斜杠)。
- 传输协议:MCP Streamable HTTP(JSON-RPC 2.0 over HTTP POST / SSE)。
- API Key 鉴权(最简单):携带
Authorization: Bearer <API_KEY>。组织 API Key 自动固定在所属组织,不能通过请求头跨组织访问。
- OAuth 鉴权:携带
Authorization: Bearer <OAUTH_TOKEN> 与 X-ApeMind-Workspace-Id: <ORG_ID>(组织 ID 必须来自 GET /api/v2/me/workspaces)。
- 严禁混用凭据:浏览器 Cookie 和
Mcp-Session-Id 不能代替 Bearer 凭据。无效/过期凭据返回 HTTP 401;业务权限、配额或工作空间缺失在 JSON-RPC 成功外壳中以 isError: true 和结构化 error_code(如 workspace_required)返回。
客户端接入示例
Claude Code
claude mcp add --transport http apemind https://apemind.ai/mcp/ \
--header "Authorization: Bearer ${APEMIND_API_KEY}"
Cursor(.cursor/mcp.json)
{
"mcpServers": {
"apemind": {
"url": "https://apemind.ai/mcp/",
"headers": {
"Authorization": "Bearer ${env:APEMIND_API_KEY}"
}
}
}
}
curl(Streamable HTTP JSON-RPC 最小闭环)
# 1. 初始化会话并提取 Mcp-Session-Id(如服务端返回)
curl -i -sS -X POST "${APEMIND_BASE_URL}/mcp/" \
-H "Authorization: Bearer ${APEMIND_API_KEY}" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-03-26",
"capabilities": {},
"clientInfo": {"name": "curl-probe", "version": "1.0.0"}
}
}'
# 2. 列出当前身份可用的全部工具(以当次 tools/list 的 JSON Schema 为准)
curl -sS -X POST "${APEMIND_BASE_URL}/mcp/" \
-H "Authorization: Bearer ${APEMIND_API_KEY}" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}'
# 3. 调用 search_knowledge 检索指定知识库
curl -sS -X POST "${APEMIND_BASE_URL}/mcp/" \
-H "Authorization: Bearer ${APEMIND_API_KEY}" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "search_knowledge",
"arguments": {
"collection_id": "'"${KB_ID}"'",
"query": "合同解除条件",
"top_k": 5
}
}
}'
前置门槛(requires)与公共数据结构
tools/list 响应的注解里通过 requires 声明三档前置条件:workspace_access(已选定有效组织)、collection_access(对目标知识库有读权限,隐含 workspace_access)与 web_access(部署与身份允许公网出口)。超出数值上限的参数除标注「超出直接报错」外会自动收敛并在 *_applied 中返回实际值。
证据引用(EvidenceRef)与 search_knowledge 返回结构
items[]:向量、全文与图谱经加权 RRF 融合后的文本证据,每项包含 ref(collection_id、document_id、chunk_id、parse_version、match_quality)、excerpt、source_modes 与 rank_by_mode。
image_items[]:向量模式自动并行召回的知识库图片命中(与文字共用一次 query embedding,独立保留 top-k)。
qa_items[]:当目标知识库绑定了就绪的问答源(QA Source)时,返回人工审核的标准答案命中;match_quality: "strong" 可直接采用(仍须引用其 ref),answer_truncated: true 时用 read_evidence_refs 读取完整答案。
- 核对原文规范:将检索返回的
ref 原样传入 read_evidence_refs 展开完整片段,不要单独保存裸 chunk_id(跨文档不保证全局唯一,且重新解析后 parse_version 会变化)。
全部 20 个内置工具清单
以下清单与后端注册表(aperag/mcp/registration.py)保持同步;实际可用工具受调用方 API Key 作用域或 Agent builtin_tools 白名单约束。完整字段 Schema 可直接读取 tools/list 或内置资源 apemind://usage-guide / apemind://usage-guide/en。
1. 目录与元数据探索
| 工具名 |
主要入参 |
用途与返回要点 |
list_collections |
query?, limit?, cursor? |
列出当前组织内可读知识库(含只读市场订阅库)的 ID、标题与文档计数 |
list_documents |
collection_id, query?, limit?, cursor? |
列出指定知识库内的文档清单、状态与解析版本 |
get_collection_metadata |
collection_id |
查看知识库索引配置、语言、文档概览及图谱实体类型分布 |
get_document_metadata |
collection_id, document_id |
查看单篇文档的章节目录(TOC)、页数/分块数、索引进度与解析版本 |
2. 检索、精确匹配与多模态分析
| 工具名 |
主要入参 |
用途与返回要点 |
search_knowledge |
collection_id, query, modes?, top_k?, excerpt_chars? |
默认首选检索工具:默认融合 vector(含文字与图片)+ fulltext,传入 modes: ["vector","fulltext","graph"] 叠加图谱;同时返回 items、image_items、qa_items 与 modes_skipped |
grep_documents |
collection_id, pattern, document_ids?, case_sensitive?, context_chars? |
在解析后的 Markdown 正文中做字面/正则精确查找,适合编号、条款号、函数名与型号检索 |
diff_documents |
old, new, max_hunks? |
对两篇文档(或同一文档的不同版本)生成结构化差异 Hunk,适合制度修订对比 |
analyze_knowledge_image |
collection_id, document_id, image_id, question |
调用视觉模型针对知识库内提取出的图表、截图或公式做细粒度问答分析 |
3. 原文阅读与证据核对
| 工具名 |
主要入参 |
用途与返回要点 |
read_evidence_refs |
refs[], max_chars_per_ref? |
批量把检索返回的 ref(含文本片段与 qa_items)展开为完整原文与上下文 |
read_document_chunks |
collection_id, document_id, chunk_ids[] / 窗口参数 |
按分块 ID 或前后邻接窗口顺序展开阅读,适合沿着 recommended_read 补全上下文 |
read_document |
collection_id, document_id, section_path? / 范围参数 |
按章节路径或字节/字符范围顺序通读单篇文档 |
4. 知识图谱探索
| 工具名 |
主要入参 |
用途与返回要点 |
lookup_entity |
collection_id, name |
查询单个实体的定义、关系邻居及带 target_chunk_id 的 recommended_read |
list_entities |
collection_id, entity_type?, query?, limit? |
按实体类型或关键词浏览知识图谱节点 |
find_entity_paths |
collection_id, source_entity, target_entity, max_hops? |
发现两个实体之间的跨文档多跳关联路径与支撑证据 |
5. 公网检索、受管函数与外部连接
| 工具名 |
主要入参 |
用途与返回要点 |
web_search |
query, limit? |
公网搜索引擎查询(需 workspace_access + web_access) |
web_read |
urls[], max_chars? |
抓取并正文提取指定网页 URL(受 URL 数量与总字符预算上限约束) |
list_functions |
query?, limit? |
列出当前身份获授权调用的组织受管函数及其入参 Schema(默认关闭,需授权开启) |
call_function |
function, input? |
执行指定受管函数并返回结构化输出 |
list_connections |
connection?, limit? |
省略 connection 时列出可用外部连接;传入连接 ID 或 slug 时返回该连接可调用的操作及 input_schema |
invoke_connection |
connection, operation, arguments? |
调用已授权的外部连接操作(数据库、HTTP、飞书等);遵守连接策略与写操作确认,失败不自动重试 |
内置提示与使用说明资源
MCP Server 同时暴露两个只读资源 apemind://usage-guide(中文)与 apemind://usage-guide/en(英文)以及提示模板 search_assistant,客户端可在初始化后读取它们作为系统提示补充,无需在代码里硬编码检索策略。
下一步