MCP 接口 ​

Linker 内置了一个 MCP（Model Context Protocol，模型上下文协议）服务，让支持 MCP 的 AI 客户端与智能体（如 Claude Desktop、Cursor、Cline、各类 AI Agent 框架）能够直接连接 Linker，并通过自然语言读写业务数据。

一、为什么要有这个 ​

过去要让外部系统使用 Linker 的数据，需要对接 开放 API：开发者要先拿到 API Key、阅读接口文档、写代码拼接请求体和条件，再解析返回结果。这条路对程序员很顺，但对「想在对话框里直接问一句『帮我查一下本月新增的客户』」的场景来说，门槛偏高。

MCP 是 AI 应用连接外部系统的开放标准。Linker 实现 MCP 服务端后：

  • AI 客户端即插即用：在客户端里配置一次连接信息，AI 就能自己发现 Linker 有哪些实体、字段和可用操作，无需你写任何对接代码。
  • 用自然语言操作业务数据：你可以直接说「把客户张三的电话改成 139xxxx」「列出状态为成交的订单」，AI 会选择合适的工具并填好参数去执行。
  • 沿用既有权限体系：MCP 与开放 API 共用同一套 API Key 与用户权限，AI 能看能改的范围，和 Key 所绑定用户在系统里完全一致。

简单说，MCP 把 Linker 变成「AI 可读可写」的系统，是开放 API 之上更面向智能体、更低接入成本的通道。

与开放 API 的关系

开放 API 面向「写代码集成」的开发者；MCP 面向「AI 客户端 / 智能体」自动调用。两者底层一致、鉴权同源。如果你要做定时同步或深度定制逻辑，仍可用开放 API；如果只是让 AI 帮你在 Linker 里查数据、改字段，用 MCP 更省事。

二、前置条件：先准备 API Key ​

MCP 接口位于 /open/mcp，属于对外开放接口，必须通过 API Key 鉴权。

API Key 的创建与权限说明，请参考 开放 API 的「获取 API Key」一节：

  • 由系统管理员在「系统设置 → 开放 API」创建；
  • 创建时指定 绑定用户，该 Key 的可见范围、操作权限与该用户完全一致；
  • Key 值仅在创建时完整显示一次，请立即保存。

权限决定一切

MCP 工具执行时的「当前用户」就是 API Key 绑定的用户。绑定用户看不到的数据、没有权限的实体或字段，AI 同样访问不到；写入操作也受该用户权限约束。涉及实体 / 字段结构的「管理类」工具，还要求绑定用户具备管理员权限。

三、连接配置 ​

Linker 的 MCP 服务基于 Streamable HTTP 传输协议，连接参数如下：

项值
传输协议Streamable HTTP
服务地址http(s)://<host>:<port>/open/mcp
鉴权请求头 X-Api-Key: <your-api-key>

默认应用端口为 18000，因此本地部署时的地址通常为：

http://localhost:18000/open/mcp

在各 AI 客户端中接入 ​

不同客户端的配置格式略有差异，但都需要填齐上面三项信息（地址 + 传输方式 + 请求头里的 API Key）。以通用的 MCP 客户端配置为例：

json
{
  "mcpServers": {
    "linker": {
      "type": "http",
      "url": "http://localhost:18000/open/mcp",
      "headers": {
        "X-Api-Key": "sk-xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
  • 若你的客户端使用 mcp.json / settings 形式的配置，请按该客户端文档填入相同的 URL 与 headers；
  • 自托管部署请把 localhost:18000 换成实际可访问的域名或 IP；
  • 连接成功后，客户端会自动拉取下方所有工具，AI 即可开始调用。

四、提供的工具能力 ​

Linker MCP 提供的工具分为四类：元数据查询、数据读写、明细记录、结构管理（管理员）。字段一律使用「实体 / 字段内部名称」，调用数据类工具前，建议先用元数据工具确认内部名称。

4.1 元数据查询 ​

用于让 AI 先「认识」你的系统结构，避免猜字段名。

工具作用
list_entities列出所有可操作实体，含显示名、内部名称、主键字段、名称字段
get_entity_metadata获取某实体的完整元数据
list_fields列出实体的字段（内部名、显示名、类型、是否可创建 / 修改、引用实体）
list_field_types列出 Linker 支持的字段类型及其显示名
list_cascade_fields列出可用于查询和引用的级联字段（含引用字段路径）
get_field_options获取下拉 / 多选字段的全部选项值
resolve_entity_name按实体「显示名」反查它的内部名称
resolve_field_name按字段「显示名」反查它在某实体下的内部名称

4.2 数据读写 ​

工具作用
query_records分页查询某实体的业务记录，支持指定返回列、排序、回收站开关，以及可选的过滤条件
get_record按记录 ID 查询单条记录
save_record新增或修改一条记录；请求体不含 ID 为新增，含 ID 为更新（仅更新传入字段）
batch_save_records按同一实体批量新增 / 修改记录

query_records 的过滤条件 condition 为原生 SQL 条件片段（字段使用内部名称），例如 status = 2 AND createdTime > '2025-01-01'。可省略；如提供，必须是合法的条件表达式。

save_record 的字段值使用内部名称；ID 与字典值均以字符串传入。需要同时保存明细时，可在值中附带 DETAILS 数组（每个元素为一条明细记录）。

4.3 明细记录 ​

工具作用
get_detail_records根据主记录 ID，查询指定明细实体的关联记录

4.4 结构管理（仅管理员） ​

这类工具会修改数据库结构（建表、加列、删表、删列），仅当 API Key 绑定用户为管理员时可用，且部分操作不可逆。

工具作用风险
save_entity_metadata保存 / 创建 / 修改实体结构会改动库表
delete_entity_metadata删除自定义实体及其数据表不可逆
save_field_metadata保存 / 新增 / 修改字段会改动库列
delete_field_metadata删除自定义字段及其数据库列不可逆

4.5 删除操作（不可逆） ​

工具作用风险
delete_records按记录 ID 列表删除记录不可逆
delete_records_by_condition按条件批量删除记录不可逆

删除务必二次确认

删除类工具（按 ID、按条件、删字段、删实体）均不可逆。AI 在执行前会向你确认，请务必核对实体、字段与条件范围后再放行；批量按条件删除尤其要确认条件不会误删。

五、典型使用流程 ​

一个完整、安全的对话式操作通常遵循以下步骤：

  1. 确认结构：让 AI 先调用 list_entities / list_fields，弄清实体和字段的内部名称；如只知道显示名，用 resolve_entity_name / resolve_field_name 反查。
  2. 读取验证：用 query_records / get_record 查看数据，确认要操作的对象与字段值。
  3. 执行写入：用 save_record / batch_save_records 新增或修改；需要改结构时由管理员用 4.4 类工具。
  4. 回查确认：写入后再查一次，确认结果符合预期。

示例对话：

你：帮我把客户「张三科技」的负责人改成「李四」，电话改成 13900001234。

AI（内部）:

  1. resolve_entity_name("客户") → 得到内部名 Customer
  2. list_fields("Customer") → 确认有 owner、phone、customerName
  3. query_records("Customer", ["customerId","customerName"], "customerName = '张三科技'") → 拿到记录 ID
  4. save_record("Customer", { "customerId": "...", "owner": "李四", "phone": "13900001234" }) → 返回更新后的 ID
  5. 向你汇报「已更新客户张三科技」。

六、权限与安全建议 ​

  • 最小权限原则：为 AI 集成单独创建一个系统用户，按实际用途分配角色，再绑定到 API Key，避免使用管理员账号（除非确实需要结构管理工具）。
  • Key 等同长期凭证：API Key 一旦泄露，相当于把对应用户的账号权限交给了他人。请妥善保管，不要写入前端代码或提交到公共仓库；不再使用时及时在「开放 API」页面禁用或删除。
  • 删除前确认：不可逆的删除与结构变更，AI 会先征求你确认；你也可以先在测试环境验证工具行为。
  • 数据边界清晰：AI 只能访问绑定用户权限范围内的数据，跨实体引用、回收站、审批等约束与系统行为一致。

七、常见问题 ​

Q：连接失败，客户端报 401？ A：通常是 API Key 缺失、已禁用或已过期。检查连接配置中的 X-Api-Key 请求头，并到「系统设置 → 开放 API」确认该 Key 状态。

Q：AI 说「找不到这个实体 / 字段」？ A：MCP 工具使用内部名称（如 Customer、customerName），不是界面上显示的中文名。让 AI 先调 list_entities / list_fields，或用 resolve_entity_name / resolve_field_name 反查。

Q：为什么有些工具调不了？ A：结构管理与删除类工具受绑定用户权限约束；若非管理员，相关工具会被权限拦截。请确认 API Key 绑定的是具备相应权限的用户。

Q：MCP 和开放 API 选哪个？ A：让 AI 客户端 / 智能体自动操作数据，用 MCP；自行编写代码、做定时任务或深度集成，用 开放 API。

相关阅读 ​

如果你想了解 MCP 在实际业务里能解决什么问题、如何落地，可以继续看下面几篇：

Linker