AI 编码代理入门
最快的连接方式是在 PlaidCloud 内部操作:打开头像(用户)菜单并选择连接您的 AI,选择您使用的客户端,并按其显示的步骤操作,其中包括已为您填好的工作区 MCP 服务器 URL。只要您的工作区启用了 AI 权益,就可以使用该功能。本页其余部分以及随后的各客户端页面仍然是参考资料:如果您不在 Web UI 中,或想全面了解身份验证和服务器提供的内容,请继续阅读。
什么是 MCP 服务器?
Section titled “什么是 MCP 服务器?”模型上下文协议是一项开放标准,用于让 AI 代理与外部工具和数据交互。PlaidCloud 在每个工作区上运行一个 MCP 服务器,它封装了与 REST API 相同的核心辅助函数,并按意图(find、describe、upsert、run、organize)分组,使代理无需加载 1,000 多个底层 RPC 方法名称即可浏览整个接口。
服务器位于:
https://<your-workspace>.plaid.cloud/mcp将 <your-workspace> 替换为您的工作区子域名(即您登录 PlaidCloud UI 时使用的子域名)。
它提供的内容
Section titled “它提供的内容”该目录涵盖了代理所需的大部分日常接口:
- 项目、工作流、步骤 — find/describe/upsert/run/organize,包括步骤级重新运行和版本历史。
- 表、视图、查询 — 架构自省、查询执行、导出、快照、分支。这里的视图与您在 PlaidCloud 中看到的相同,无论是您在表资源管理器中创建的,还是由工作流生成的。
- 维度 — describe、find、upsert、版本管理、管理节点/别名/属性。
- 连接 — 查找、upsert 和测试与外部系统的连接。
- Lakehouse — 分支、快照、optimize/vacuum 操作。
- 身份 — 成员、分组、会话、通讯组。
- 文档、仪表板、UDF、编辑器、代理、发布 — 特定领域的工具。
- 工作流迁移 — 将暂存在 Document 中的 Alteryx(
alteryx_convert)、KNIME(knime_convert)、Prophecy(prophecy_convert)和 Savant(savant_convert)导出文件转换为 PlaidCloud 工作流,并协调组合迁移工作。 - PlaidCloud 文档 —
docs_search按关键字在 PlaidCloud 文档中查找页面,docs_fetch读取页面全文,因此您的代理可以在构建之前先查看某项功能的工作方式。 - 工作流日志和运行跟踪 —
workflow_logs、workflow_run_status、workflow_job_track。
每个工具都返回统一的信封 {ok, data, next_cursor?, total?};失败时使用 {ok: false, error: {code, retryable, message, hint?}}。变更操作接受 dry_run=True,用于只规划而不写入的验证。
保持结果精简
Section titled “保持结果精简”工具结果是代理上下文中最大的单项消耗,因此 find 和 describe 工具默认只返回一小部分,并允许您扩大范围:
- 行。 find 每页返回 25 个匹配项(
step_find返回 50 个)。被截断的页面会设置next_cursor,并且 find 工具还会在truncated中指明被截断的列表;任何一个都表示“还有更多”,而不是“全部就这些”。total始终报告完整数量。请提高limit或使用游标翻页。 - 列。 传入
fields=['id', 'name', 'update_time']即可只返回这些列。任何记录中都不存在的字段名会导致错误并列出可用字段,而不是被悄悄省略,因此拼写错误会明确失败,而不是悄悄返回比您要求更少的内容。提供精选集合的工具还接受field_set='minimal' | 'default' | 'full';调用mcp_introspect可查看某个工具接受哪些参数。 - 计数。
count_only=True可在不获取结果的情况下估算结果集的大小。
未知字段会被拒绝
Section titled “未知字段会被拒绝”工具所接受的 spec(例如 project_upsert 或 workflow_upsert 的那一个)只接受其列出的字段。无法识别的字段会被拒绝,并返回指明该字段的错误,而不是被忽略,以免您日后才发现它没有任何作用。更正名称后重新发送请求即可。workflow_upsert 将工作流的说明作为 memo 接收,并接受 description 作为它的另一个名称。
mcp_batch 将多个工具调用打包成一个请求。它最多接受 100 个调用,同一时间运行有限数量的调用,并且不能嵌套在另一个 mcp_batch 或配方内;请改为将调用列在一个扁平的批次中,这样发送成本不会更高。超过上限的批次会被拒绝并返回指明该上限的消息,而不是被悄悄截断;该上限限制的是单个请求可启动的工作量,而不是您可完成的总量,因此请将较大的作业拆分为多个批次。
无论为 paginate_through_listing 配方传入多大的 max_pages,它在 200 页后都会停止,提前停止时会报告 partial: true。结合其 max_items 限制,单次 paginate 调用总会终止。
配方会拒绝其无法识别的 params 键,并在消息中列出该配方接受的键,因此拼错的可选参数会明确失败,而不是被丢弃,否则调用会悄悄回答与您所问不同的问题。调用 mcp_recipes(name=...) 可查看某个配方接受的键。
按列组织的结果
Section titled “按列组织的结果”如果某个大型结果的所有行都带有相同的字段,它会以按列组织的形式返回,而不是对象列表,这样字段名只发送一次,而不是每行发送一次:
{"_fmt": "cols", "cols": ["id", "name"], "rows": [["a1", "Sales"], ["b2", "Costs"]]}第 i 行是 dict(zip(cols, rows[i]))。小型结果,以及各行字段集不完全相同的任何结果,仍保持为普通的对象数组,因此两种形态都会出现,直接读取这些响应的代码应处理这两种形态。外层信封不变,途中不会转换或舍入任何值。代理在连接时会被告知这种形态,无需您任何提示即可读取;在典型的列表流量中,可节省约 30% 的字符和约 15% 的代理读取预算,这些上下文可留给您真正的问题。(这两个数字不同,是因为重复的字段名对模型来说读取成本很低,因此字符节省量总是较大的那个。)
要查看实时目录,请让您的代理连接服务器并调用 mcp_introspect(不带参数),它会返回当前的工具数量、各领域摘要和参数签名。使用 mcp_recipes 获取常用的多工具剧本(对大型列表分页、先快照再修改、重新运行失败的步骤等)。
每个设置标签的 upsert 工具(适用于表、工作流、步骤、项目、维度、视图、编辑器、UDF、连接和仓库)都接受两个参数:labels 添加标签,remove_labels 移除标签。对象上的其他标签保持不变。移除先于添加执行,因此一次调用即可重命名标签:
{"remove_labels": ["01"], "labels": ["001"]}移除对象上并不存在的标签不会产生任何效果。
视图工具使用您在 PlaidCloud 中看到的视图:
view_find列出视图,view_describe按 ID 或名称返回一个视图。view_upsert创建视图或就地更新视图。更新会保留视图的 ID 和标签,并且无需再次发送查询即可仅更改其标签。view_organize删除、重命名、复制和移动视图。- 将查询参数写为
%(name)s占位符。
视图与表共用文件夹树,因此请使用 table_organize 管理它们的文件夹。
使用原生步骤构建工作流
Section titled “使用原生步骤构建工作流”数据进入 PlaidCloud 后,代理会被引导用原生表步骤来构建每项转换,即 Table Extract、各联接步骤、Table Melt、Table Union All 和 Table Lookup 步骤,而不是提取 SQL步骤。原生步骤会在其筛选器和表达式中填入变量,PlaidCloud 会针对项目的仓库生成其 SQL。提取 SQL 步骤会将查询按所写内容发送到仓库:不填入任何变量,其 SQL 针对某一个仓库编写。
代理可以用 query_run(mode='config') 试用 Table Extract 设置(即它会通过 step_upsert 保存的设置),并在保存步骤之前查看其行。保存提取 SQL 步骤时,step_upsert 会在 config_warnings 中返回一个 prefer_native_steps 条目,指明应改用的原生步骤,describe_step_operation 也带有相同的说明。对于任何原生步骤都无法表达的内容,提取 SQL 仍然可用。
服务器提供了一小组起点,对应人们按名称请求的任务。支持 MCP 提示的客户端会列出这些起点并以菜单形式提供(请查看客户端文档了解其放置位置),因此您只需选择任务,而无需描述它所需的工具调用序列:
| 起点 | 您需要提供的内容 |
|---|---|
| 将 CSV 文件导入表 | 文件,以及可选的项目、存放该文件的文件夹和新表的名称 |
| 解释成本变化 | 结果表,以及可选的项目和两个期间 |
| 调试失败的工作流 | 工作流,以及可选的项目 |
| 探索项目数据 | 您要查找的内容,以及可选的项目 |
每个起点都是一条起始消息,而不是命令:您的代理会读取它,然后自行驱动工具,因此您可以编辑它,或从那里继续对话。
无需了解对象模型即可导入文件
Section titled “无需了解对象模型即可导入文件”导入起点最能节省工作,因为直接的做法需要按正确顺序使用四个工具:查找文档账户、浏览到文件、创建目标表,然后运行导入,而其中任何一步猜错都会让流程在数次调用之后终止。
它读取分隔文本,例如 CSV、TSV 等。Excel 工作簿或 Parquet 文件会被拒绝而不是被误读;请改为在工作流中使用相应的导入步骤导入这些文件。
相反,bulk_import_csv 剧本按名称接收账户,按名称或路径接收文件:
mcp_recipe_run(name='bulk_import_csv', params={ 'project_id': '<project>', 'document_path': 'sales_2026.csv', 'document_account': 'Demo Data',})它会将账户解析为其标识符,定位文件,根据文件本身读取的列和类型创建表,并加载数据,因此您无需提供账户 ID 或列规范。table_name 默认为不含扩展名的文件名,table_path 默认为项目根目录。
知道文件夹时请提供它,例如 'document_path': 'raw/sales_2026.csv',这样搜索就局限于该文件夹。在某个文件夹中指定的文件只会在该文件夹中匹配:更深层中的同名文件会作为选项提供,而不会替它被导入。
当某个参数存在歧义时,结果会询问而不是猜测:
{ "needs_choice": "document_account", "question": "More than one document account is named 'Archive'. Which one?", "candidates": [{"id": "...", "name": "Archive"}, {"id": "...", "name": "Archive"}]}将候选项展示给您所协助的人,然后用其答案再次调用该剧本,并将候选项原样传回。找不到文件时,回复会改为列出最接近的名称,并报告搜索了多少个文件,这样就能区分“不在那里”和“不在我找的地方”。
PlaidCloud 的 MCP 服务器接受两种身份验证路径:
- 通过动态客户端注册(DCR)使用 OAuth 2.1 + PKCE。 这是 Claude.ai 的自定义连接器 UI 所使用的方式,也是 Claude Code 的 MCP 桥接的默认方式。客户端会自行注册,并将您重定向到 PlaidCloud 的 Keycloak 登录页面。登录后,PlaidCloud 会显示 Application Access Request 页面,其中列出应用程序名称以及它将向其发送凭据的重定向 URI;每次授权只需批准一次,即可获取令牌。这是一项安全控制,而不是形式:请检查应用程序名称和重定向 URI 是否与您实际连接的客户端相符,不要批准并非由您发起的请求。
Authorization标头中的静态持有者令牌。 适用于没有可用浏览器重定向的代理运行时,或希望在配置文件中使用长期令牌的运行时。PlaidCloud 提供了一个辅助页面,可为您生成令牌(见下文)。
获取静态持有者令牌
Section titled “获取静态持有者令牌”在您已登录 PlaidCloud 的浏览器标签页中打开此 URL:
https://<your-workspace>.plaid.cloud/mcp/setup/token该页面会返回可直接粘贴到代理 MCP 配置中的 JSON 代码片段。每个工作区都有自己的代码片段。
令牌的有效期由您的 Keycloak 领域的访问令牌有效期策略决定(通常为数小时到一天)。要刷新,请重新加载同一 URL,您的浏览器会话会自动重新生成令牌。
本节其余部分将介绍针对特定 AI 代理客户端的设置:
- Claude Code — Anthropic 的编码代理(CLI、VSCode 扩展、JetBrains 插件)。
- Claude Desktop 和 Claude.ai — 使用“自定义连接器”的 Claude 消费者应用(桌面版)和 Web 版(
claude.ai)。 - Cursor — AI 原生代码编辑器。
- GitHub Copilot — VSCode 中的 Copilot 代理模式。
- Google Gemini CLI —
gemini-cli和 Gemini Code Assist。 - ChatGPT — 当前的支持状态和推荐的变通方法。
- Grok — 连接 Grok 的自定义连接器。
- 故障排除 — 常见错误及其修复方法。