use-twenty-mcp

何时使用

当用户希望读取或查看正在运行的 Twenty 工作区时——而非更改应用代码——请选择此技能。典型触发场景：

• “列出我在 Twenty 中的所有公司 / 人员 / 商机”
• “显示我本周创建的记录”
• “我的 Twenty 工作区里有什么”
• “将我的 Agent 连接到我的 Twenty 工作区”
• “为 myworkspace.twenty.com 设置 Twenty MCP”
• “查询 CRM 中的 X”
• “总结我在 Twenty 中的销售管道”
• “显示公司对象上的字段”

请勿使用此技能来搭建应用（使用 create-app）、添加或修改应用实体（使用 develop-app）、操作应用（使用 manage-app）或准备应用市场资源（使用 publish-app）。

它是什么

Twenty MCP 将 Agent 连接到现有的 Twenty 工作区，使其能够查看工作区数据和元数据：记录、对象、字段、schema、配置以及相关 CRM 上下文。

这与 Twenty 应用不同。当用户希望搭建新的应用代码库时使用 $create-app，当用户希望添加应用定义的功能（如对象、字段、逻辑、布局或组件）时使用 $develop-app。

当用户希望将 Agent 连接到已运行的工作区、检索或查看工作区数据、查看元数据或排查 MCP 访问问题时，使用 $use-twenty-mcp。

请勿将 MCP 作为自定义工作区的默认方式。例如，优先通过 Twenty 应用创建新对象，而不是直接通过 MCP 创建。仅当用户明确要求通过 MCP 进行工作区自定义时，才使用 MCP。

设置

使用 ../../references/use-twenty-mcp/setup.md 进行工作区 URL 规范化、MCP 服务配置、OAuth 防护措施以及设置问题排查。

检索

在检索、列出、搜索、总结或呈现工作区记录之前，请阅读 ../../references/use-twenty-mcp/result-formatting.md。

在选择正确的 Twenty MCP 工作区、查询记录、构建记录链接、格式化日期和值，以及呈现可读的 Markdown 而非原始 API 输出时，请应用该参考文档。

输出约定

在针对检索到的工作区记录给出最终答案之前：

• 如果工具输出包含 recordReferences，则第一个记录名称列或记录标题必须将每个显示名称链接回 Twenty。
• 使用所选工作区源和返回的 recordReferences，按 {workspaceOrigin}/object/{objectNameSingular}/{recordId} 构建链接。
• 如果工作区源未知，请尽可能从所选 MCP 服务 URL 解析它。如果仍无法解析，请说明直接记录链接需要工作区 URL，而不是编造一个主机名。
• 当 recordReferences 和工作区源可用时，切勿在记录表中显示未链接的记录名称。