跳到主要内容

通过 MCP 接入 AI 智能体

GeniSpace 提供标准的 模型上下文协议（Model Context Protocol，MCP） 服务。任何兼容 MCP 的 AI 客户端或智能体 —— Claude（Desktop / Code）、ChatGPT 连接器、Cursor、VS Code 等 —— 都可以接入它，把你空间内的能力（智能体、数据集、数据源、工作流、知识库、看板等）当作 工具 来调用。这样，外部智能体就能理解需求，并代表你在 GeniSpace 上端到端地构建并运行一套完整方案。

什么是 MCP？

模型上下文协议是连接 AI 智能体与外部工具/数据的开放标准。GeniSpace 的 MCP 服务是其中的桥梁：智能体调用 GeniSpace 工具，而每一次调用都运行在你 API 密钥所属的那个空间内。

接入地址​

服务使用标准的 Streamable HTTP 传输。按所在区域连接 /mcp 端点：

https://api.genispace.ai/mcp      # 国际版
https://api.genispace.cn/mcp      # 中国版

无需鉴权的 GET https://api.genispace.ai/mcp/info 会返回基本的连接信息。

私有化 / 独立部署

私有化部署时请使用你自己的 API 域名（平台运维会在 API 域名上把 /mcp 路径指向 MCP 服务，例如 https://api.你的域名/mcp）。具体地址请向管理员获取。

鉴权​

每个请求都必须携带 GeniSpace API 密钥 作为 Bearer 令牌：

Authorization: Bearer <你的 GeniSpace API 密钥>
  • 一把密钥对应一个空间。 API 密钥永久绑定到单个空间，因此智能体的所有操作都会自动限定在该空间内。你无需传入空间 ID —— 且一把密钥无法访问其它空间。
  • 创建密钥：在控制台 设置 → 集成 的 API 密钥区域创建。请妥善保管（只展示一次）。密钥格式与细节见 API 鉴权。
  • 最小权限：只给密钥分配智能体所需的 space.* 权限（例如 space.dataset.*、space.task.*）。把它当作密码对待；一旦泄露立即轮换或吊销。
注意

持有该密钥的任何人都能在对应空间内执行操作。请为每个集成单独签发密钥、收紧权限，不再需要时及时吊销。

接入客户端​

连接信息始终一致：上面的 URL 加一个 Authorization: Bearer 请求头。大多数客户端通过类似下面的配置接入一个远程 / HTTP MCP 服务：

{
  "mcpServers": {
    "genispace": {
      "type": "http",
      "url": "https://api.genispace.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_GENISPACE_API_KEY" }
    }
  }
}
提示

不同客户端的字段名略有差异（有的叫「远程 MCP 服务」「HTTP 服务」或「连接器」）。无论格式如何，都只需提供两样东西：/mcp 地址，以及 Authorization: Bearer <密钥> 请求头。具体填写位置请参阅你所用客户端的 MCP 文档。

接入后，智能体会自动收到服务的使用说明，并能列出可用的工具。

你能做什么​

服务暴露了一组聚焦、易于导航的工具，外加参考文档与现成模板。

发现类工具（从这里开始）​

工具用途
genispace_list_capabilities列出可操作的资源分组（智能体、数据集、数据源、工作流、任务、算子、知识库、工作台、配置……）。
genispace_search_capabilities在实时 API 中搜索与你意图匹配的操作。
genispace_api_request带护栏的通用执行器，用于调用精选工具未覆盖的任意受支持端点（管理类/内部端点已被拦截）。

精选工具分组​

分组示例
智能体与算子genispace_agent_create（含用于结构化抽取的严格 schema TASK 智能体）、genispace_agent_execute、genispace_operator_run、genispace_email_send
SQL 数据genispace_database_create、genispace_table_create、genispace_datasource_create / _execute（数据源 = 一条已保存的、带参数的 SQL 语句）
向量数据集genispace_dataset_create、genispace_dataset_insert、genispace_dataset_search、genispace_dataset_fulltext_search
工作流与任务genispace_workflow_create、genispace_task_create（手动或带 cron 的 定时）、genispace_task_execute、genispace_task_status
知识与配置genispace_kb_create / _search、genispace_configmap_create、genispace_configvar_set（支持 isSecret）
工作台genispace_workbench_create（创建一个 WORKBENCH 应用 及其工作台并返回 workbenchId —— 工作台不能被直接创建）、genispace_workbench_page_upsert（低代码看板）
空间与存储genispace_whoami、genispace_space_overview、genispace_search、genispace_apikey_create、genispace_storage_list

参考与配方资源​

平台中有两块内容 —— 工作流的节点/边图 和 工作台的页面/组件布局 —— 功能强大但细节较多。服务把它们经过核对的、可直接复制的模板以 MCP 资源 形式发布，供智能体按需读取：

  • genispace://reference/workflow-nodes、genispace://reference/workbench-components
  • genispace://reference/sql-data、genispace://reference/vector-datasets、genispace://reference/agents-and-operators、genispace://reference/knowledge-and-config
  • genispace://docs/recipes/job-intelligence-pipeline —— 一份完整的端到端构建配方
  • genispace://catalog/operators、genispace://catalog/api —— 你空间内的实时清单

构建提示词（Prompts）​

由用户触发、可一键搭建整套方案的模板：build_monitoring_pipeline、build_extraction_agent、build_dashboard、summarize_space。

工作方式​

一个可靠的智能体遵循这样的循环：

  1. 发现 —— 先调 genispace_list_capabilities，再用 genispace_search_capabilities 找到精确的操作；优先使用精选的 genispace_* 工具。
  2. 读参考 —— 凡涉及工作流图或看板，务必先读参考；创建工作流 之前 先读 genispace://reference/workflow-nodes。
  3. 按顺序构建 —— 准备数据（数据库 → 表，和/或数据集）→ 创建数据源（要运行的 SQL）→ 创建智能体/算子 → 组装工作流 → 包成任务（并设定时）→ 可选地建工作台看板 → 用 ConfigMap 存放密钥。
  4. 校验 —— 用 genispace_whoami 确认空间与权限，运行后用 genispace_task_status 查看结果。

示例：一条定时数据流水线​

一个典型的端到端构建（完整模板见 genispace://docs/recipes/job-intelligence-pipeline）：

  1. genispace_database_create → genispace_table_create 建表。
  2. genispace_datasource_create 创建工作流要运行的 SQL（去重查询、插入、更新各一条）。
  3. genispace_agent_create，agentType: "TASK" + 严格的 outputSchema —— 你的结构化抽取器。
  4. genispace_dataset_create 用于语义检索/去重。
  5. 先读 genispace://reference/workflow-nodes，再 genispace_workflow_create 传入节点/边图。
  6. genispace_task_create（type: "SCHEDULED"，cron 如 0 0 6 * * *）让它每天运行。
  7. 可选：genispace_workbench_create 建看板（它会创建一个 WORKBENCH 应用并返回 workbenchId），genispace_configmap_create 存密钥。

限制与说明​

  • MCP 暂不支持文件上传（需要 multipart 上传）。知识库与存储的 读取 和 搜索 可用；请先在控制台导入文件，再在工具中引用。
  • 向量检索需要嵌入向量。 使用 genispace_dataset_search 传入文本（自动嵌入）或用全文检索；或先用 multimodal-embedding 算子计算嵌入。
  • 工作流图在任务运行时才校验，而非创建时 —— 请严格按 genispace://reference/workflow-nodes 构造，避免运行失败。
  • 算子需先在空间内启用 才能运行。

相关文档​