FactVerse AI Agent 快速开始

本指南面向实施工程师、合作伙伴和客户技术团队，用于第一次把 AI 客户端连接到 FactVerse AI Agent。

FactVerse AI Agent 使用受治理的 MCP endpoint。客户端连接到一个 endpoint，发送 API key，列出该 key 可用的工具，然后在平台解析出的租户和 scope 范围内调用读取或计算工具。

AI client -> /mcp/<slice>/ -> API key 解析租户和 scope -> 可用工具

前置条件

连接客户端前，需要准备以下内容：

要求	说明
FactVerse 主机	使用该客户或项目环境提供的主机。示例中使用 `https://your-factverse-host`。
MCP endpoint	使用客户已启用的 slice endpoint，例如 `/mcp/base/` 或 `/mcp/pdm/`。
API key	Key 由管理员签发，仅显示一次，通过 `X-API-Key` 发送。
Scope	Key 必须具备目标工具所需的 scope。
来源数据	Agent 推理前，需要已有资产记录、运营信号、文档、场景或工单记录。
MCP 兼容客户端	Claude Desktop、Cursor、自建 MCP client 或企业 Agent runtime。

选择 endpoint

从匹配工作流的 endpoint 开始。当前工具和 scope 以本网站生成的 scope 参考为准。

Endpoint	典型用途	常见 scope
`/mcp/base/`	通用资产读取、知识、文档、数据质量、仿真、优化和受控写操作	`base.read`, `base.compute.run`, `base.action.write`
`/mcp/pdm/`	预测性维护健康度、摘要、异常和组件智能	`pdm.read`
`/mcp/trafficops/`	人流、车流、检查点和交通运营工具	`trafficops.read`
`/mcp/telcoops/`	网络运营和容量分析工具	`telcoops.read`
`/mcp/semiops/`	洁净室、厂务、utility、SMT 和环境工具	`semiops.read`
`/mcp/aviation/`	航空可靠性分析工具	`aviation.analysis.read`

已退役的 /mcp/physical/ endpoint 仅保留迁移提示。新的 Physical AI 工作流应使用当前 base 和模块 endpoint，并结合 Designer 场景、SimReady asset 和仿真流程。

配置客户端

每个请求都使用 X-API-Key。不要把租户标识作为 header 传入来替代 key 授权。

{
  "mcpServers": {
    "factverse-base": {
      "url": "https://your-factverse-host/mcp/base/",
      "headers": {
        "X-API-Key": "fvk_your_scoped_key"
      }
    }
  }
}

如果集成需要多个 slice，为每个 endpoint 配置独立 server entry。若部署策略允许，同一个 key 可以具备多个 scope。

验证接入

正式设计工作流前，先完成这些检查：

通过 HTTPS 连接 endpoint。
初始化 MCP session。
运行时列出工具。
确认可见工具符合预期。
先调用只读工具。
记录响应、来源引用和缺失数据提示。

Python 客户端示例：

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    async with streamablehttp_client(
        "https://your-factverse-host/mcp/base/",
        headers={"X-API-Key": "fvk_your_scoped_key"},
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            tools = await session.list_tools()
            for tool in tools.tools:
                print(tool.name)

            result = await session.call_tool(
                "get_equipment_status",
                {"equipment_id": "EQ-001"},
            )
            print(result)

如果工具没有出现在列表里，不要硬编码调用。先检查 endpoint、key、scope 和模块启用状态。

第一个工作流检查

工作流	从这里开始	验证内容
设施运营	`/mcp/base/` 与 `base.read`	资产身份、位置、状态、来源系统新鲜度和相关文档。
预测性维护	`/mcp/pdm/` 与 `pdm.read`	设备健康度、异常可见性、维护历史和信号质量。
Physical AI	`/mcp/base/` 与 `base.compute.run`，并结合 Designer 场景上下文	场景版本、资产版本、仿真假设和验证记录。

工单创建等写操作需要明确的写 scope，例如 base.action.write。这类动作应保留人工审批和审计控制。

常见启动失败

现象	可能原因	检查方式
网关返回 `403`	没有发送 API key	确认存在 `X-API-Key` header。
`401`	Key 无效、已撤销或属于其他环境	向管理员申请新的 key。
`missing required scope`	Key 不具备目标工具 scope	对照可见工具和 scope 参考。
工具不在列表中	endpoint 错误、模块未启用或 scope 不足	使用运行时 `tools/list` 并检查 endpoint 路径。
回答为空或质量弱	来源数据缺失、过期或未映射到资产	检查 DFS pipeline、Platform 资产记录、Inspector 记录和文档。
写操作被阻止	缺少写 scope 或审批策略	将动作保留为草稿，并交给具备权限的操作者审批。

下一步

设计工作流前阅读核心概念。
使用 MCP 接入指南查看客户端配置。
使用工具参考和 Scope 参考查看当前生成的工具与权限细节。

前置条件​

选择 endpoint​

配置客户端​

验证接入​

第一个工作流检查​

常见启动失败​

下一步​