formbase

Formstep MCP 服务

适用于 Formstep 的托管 MCP 服务。只需一个请求，即可收集经过验证的客户信息。

你的 Agent 向一位客户（即接收者）发送一个请求：表单采用你的品牌样式和对方的语言，并预填你已知的信息，因此对方只需确认或更正。他们无需账户，就能在同一页面上传文件、签名、预约或付款。答案会以你的字段键返回，并附上你的外部 ID；如果表单包含决策问题，还会返回批准、拒绝或需修改的结果。你的 Agent 可以通过 request_get 读取答案；或者，接收者提交后，Formstep 会立即调用你的回调 URL。

服务地址为：

https://api.formstep.io/api/mcp

此仓库包含文档、示例配置和 Grok Build 插件清单。无需安装或运行任何内容。

• Agent 可以做什么
• 连接 AI 工具
• 试用
• 工具
• 限制
• 协议详情
• 文档
• 报告问题

Agent 可以做什么

• 发送请求。 向一位指定人员索取信息，并预填或锁定答案，然后读取对方的回答。使用你发布的表单，也可以让 Agent 在同一次调用中创建表单。
• 构建表单。 创建表单，并添加、编辑或移除其中的问题、页面和逻辑。
• 发布和分享。 发布表单、创建分享链接、翻译表单，并设置主题和选项。
• 读取结果。 列出表单的提交记录并读取其分析数据。

大多数 AI 工具通过 OAuth 登录 Formstep：粘贴 URL，在浏览器中登录 Formstep，然后选择一个工作区。脚本和无头 Agent 则发送 API 令牌。

连接 AI 工具

将所有客户端 ID、密钥或令牌字段留空。AI 工具会从服务中找到 Formstep 登录页面并完成注册。

Claude Code

claude mcp add --transport http formstep https://api.formstep.io/api/mcp

然后在 Claude Code 中输入 /mcp 登录。

若要与项目的所有协作者共享此服务，请改为将 .mcp.json 提交到项目中：

{
  "mcpServers": {
    "formstep": {
      "type": "http",
      "url": "https://api.formstep.io/api/mcp"
    }
  }
}

Claude desktop 和 claude.ai

打开 Customize › Connectors › + › Add custom connector，然后粘贴 URL。在 claude.ai 上添加的连接器也可在桌面和移动应用中使用。

在 Team 和 Enterprise 版本中，所有者需先在 Organization settings › Connectors 下添加连接器。成员随后点击该连接器上的 Connect。Free 版本只能添加一个自定义连接器。Claude 官方指南：开始使用自定义连接器。

ChatGPT

在 Settings › Apps › Advanced settings 下开启开发者模式。然后打开 Settings › Apps › Create，粘贴 URL，选择 OAuth，点击 Scan Tools，登录 Formstep，再点击 Create。

开发者模式仅适用于网页版。Pro 版本中的 ChatGPT 只能读取数据：发送请求或编辑表单等会更改内容的工具需要 Business、Enterprise 或 Edu 版本。在 Business 版本中，只有管理员和所有者可以使用开发者模式。OpenAI 官方指南：ChatGPT 中的开发者模式和 MCP 应用。

Cursor

将以下内容添加到项目中的 .cursor/mcp.json，或添加到 ~/.cursor/mcp.json 以供所有项目使用：

{
  "mcpServers": {
    "formstep": {
      "url": "https://api.formstep.io/api/mcp"
    }
  }
}

Cline

Cline 使用 API 令牌连接（令牌创建方法请参见下文）。将以下内容添加到 Cline 的 cline_mcp_settings.json 中：

{
  "mcpServers": {
    "formstep": {
      "type": "streamableHttp",
      "url": "https://api.formstep.io/api/mcp",
      "headers": {
        "Authorization": "Bearer fs_YOUR_TOKEN"
      }
    }
  }
}

也可以让 Cline 为你安装：llms-install.md 介绍了它会执行的步骤。

Grok Build

此仓库也是一个 Grok Build 插件： .grok-plugin/plugin.json、.mcp.json 服务配置和一个技能 formstep-requests。该插件不会在你的机器上运行任何内容。它只会调用一个网络端点 https://api.formstep.io/api/mcp，并通过 Formstep OAuth 登录，或使用你添加为请求头的 API 令牌。

其他工具

任何支持带登录功能的远程 MCP 服务的工具都能以相同方式工作：找到它通过 URL 添加服务的位置。连接指南链接了各个工具自己的说明。

登录并选择工作区

Agent 首次使用 Formstep 时，你的 AI 工具会在浏览器中打开 Formstep 页面。登录、选择工作区，然后点击 Authorize。

一个连接只能访问对应的一个工作区。要使用其他工作区，请再添加一次 Formstep，并选择另一个工作区。

要检查是否正常工作，请询问：

List my Formstep forms and whether each one is published.

要移除连接，请在 Formstep 工作区侧边栏中打开 OAuth and API Keys。在 Connected apps 下，点击该连接旁边的垃圾桶图标，然后点击 Disconnect 确认。

脚本和无头 Agent：使用 API 令牌

无法打开浏览器的程序，例如脚本、CI 任务或无头 Agent，需要改为在请求头中发送 API 令牌。

1. 在工作区侧边栏中打开 OAuth and API Keys，然后点击 Create token（API 令牌）。
2. 复制令牌。令牌以 fs_ 开头。
3. 将其作为 Authorization: Bearer 请求头发送。

和 OAuth 连接一样，一个令牌只能访问一个工作区。令牌会在创建后 30 天过期，且无法延期，因此请做好更换计划。不要将其提交到 git。

通过命令行使用 Claude Code：

claude mcp add --transport http formstep https://api.formstep.io/api/mcp \
  --header "Authorization: Bearer fs_YOUR_TOKEN"

或者在配置文件中使用。这是 Claude Code 的 .mcp.json；Cursor 在其 mcp.json 中使用相同的 headers 对象：

{
  "mcpServers": {
    "formstep": {
      "type": "http",
      "url": "https://api.formstep.io/api/mcp",
      "headers": {
        "Authorization": "Bearer fs_YOUR_TOKEN"
      }
    }
  }
}

其他工具使用相同的 URL 和请求头。请查看其文档，了解配置位置。

试试看

向一位联系人发送请求。使用已发布表单的名称：

Send a Formstep request with the "Supplier onboarding" form to Ada Lovelace ([email protected]). Fill in the company name "Analytical Engines Ltd" and lock it so it cannot be changed. Use supplier-2041 as the external ID. Don't send the invitation email; give me the link and I will send it myself.

Agent 会通过 fields_list 读取表单的字段键，通过 request_create 创建请求，并提供请求链接。

还没有表单？Agent 可以在同一次调用中创建一个：

Ask Ada Lovelace ([email protected]) for her last three payslips and a 40 EUR processing fee, and let her book a 15 minute call. Use our logo at https://acme.example/logo.png and a dark blue cover. Give me the link.

Agent 会通过 workspaceConnection_list 检查工作区的 Stripe 和 Cal.com 连接，然后调用 request_create，并传入 form 对象而不是 formId：其中包含名称、区块，以及你提供的徽标和封面。Formstep 会一步完成表单构建、发布和请求创建，并返回答案对应的字段键。再次使用相同的定义会复用该表单，因此发送一百个请求也只会创建一个表单。

如果表单启用了 Send reminders，Formstep 仍会按计划向收件人发送提醒邮件。若要阻止提醒，也请注明 no reminders。

收件人提交时，Agent 不会收到通知，因此之后再询问：

Has the Formstep request supplier-2041 been answered? Show me the answers.

Agent 会通过外部 ID 使用 request_list 查找请求，然后使用 request_get 读取请求。请求完成后，答案会以字段键为键返回。

分步指南：使用 AI Agent 发送请求、一次调用中创建表单和请求以及使用 AI Agent 构建表单。

工具

AI 工具一旦连接，所有工具都会连同完整的输入架构出现在 tools/list 中。MCP 服务参考详细介绍了这些工具。

请求

向一位指定的人询问信息并读取结果。

• fields_list：列出已发布表单中请求可操作的字段键。在调用带 formId 的 request_create 之前调用。
• request_create：将表单分配给一位接收者，并设置预填内容、锁定字段、上下文、交付方式、有效期和可选回调。对于已发布的表单，传入 formId；也可以传入 form，在同一次调用中构建表单（见下文）。
• request_get：按 ID 读取一条请求。返回状态、时间线，以及在请求完成后按字段键组织的答案。
• request_list：列出某个表单或工作区的请求，并按状态、结果或你自己的外部 ID 筛选。
• request_cancel：撤回待处理的请求。
• request_remind：立即向接收者发送提醒邮件。
• request_replayCallback：当回调从未到达你的端点时，再次发送回调。
• document_create：为请求交给接收者的文件预留上传位置。一个上传位置可供任意数量的请求使用。
• workspaceConnection_list：列出工作区已连接的 Stripe 和 Cal.com 账户，并提供用于连接缺失账户的 connectUrl。在构建带有付款或预约功能的表单之前读取。
• scheduler_listEventTypes：列出预约区块可指定的 Cal.com 活动类型，以及每种类型能否通过表单预约。
• paymentConnection_setDefault：选择默认用于收取付款的 Stripe 账户。仅限工作区所有者。

在请求中构建的表单

request_create 可用 form 代替 formId。Formstep 会根据它构建普通表单、发布表单并创建请求，一步完成：要么两者都创建，要么都不创建。Agent 不需要编辑器工具，也不需要调用 fields_list。

{
  "form": {
    "name": "Documents and fee for your mortgage application",
    "logo": { "type": "image", "url": "https://acme.example/logo.png" },
    "cover": { "type": "color", "color": "#0f4c81" },
    "blocks": [
      { "type": "paragraph", "content": "Hi {{first_name}}, upload the documents and pay the fee." },
      { "type": "hiddenField", "key": "first_name" },
      { "type": "file", "key": "payslips", "title": "Your last three payslips", "maxFiles": 3 },
      { "type": "payment", "key": "fee", "title": "Processing fee", "amount": 40, "currency": "EUR" },
      { "type": "scheduleAppointment", "key": "call", "title": "Pick a time", "eventType": "15 min call" }
    ]
  },
  "recipient": { "email": "[email protected]", "name": "Ada" },
  "context": { "first_name": "Ada" }
}

• form 接受 name 和 blocks（1 到 200 个，按表单顺序排列），还可选传入 language、品牌元素（logo、cover、emoji）、theme（每种颜色模式对应一个预设 ID）、settings 和 translations（表单中每个字符串的额外语言翻译）。Formstep 会获取每个图片 URL 一次，并保存副本；图片必须是公开的 JPEG、PNG 或 WebP。
• 区块 接受对应 editor_insert* 工具的参数，但不含 formId 和 after，并需附带一个 key。所有区块类型均可使用：问题、文档、付款、预约、决策、内容区块、行、分页分隔符、重复组、隐藏字段和计算字段，以及通过键引用其他区块的逻辑规则。
• 响应会添加 form: { id, name, reused, fields }，其中包含答案返回时使用的字段键。
• 一个定义，一个表单。 重复使用同一个 form 会复用已发布的表单（reused: true）。将客户姓名、发票编号或金额放入 prefill 和 context，不要放入名称、区块或品牌中，否则每次调用都会创建一个新表单。Agent 会保留品牌设置，并在每次请求中原样发送。每个问题都要设置 key。
• 付款和预约需要工作区已连接 Stripe 或 Cal.com。workspaceConnection_list 会说明已连接的账户，并返回供用户打开一次的 connectUrl；Agent 无法自行连接账户。

完整参考见 load_skill("requests") 的第 2c 节，以及在一次调用中创建表单和请求。

表单

• form_list、form_get、form_create、form_update：查找、读取、创建和重命名表单，并设置文件夹、表情符号、封面和徽标。
• form_publish、form_unpublish：开始和停止接收提交。重复调用 form_publish 是安全的。
• form_delete、form_restore：将表单移至回收站（同时撤销其分享链接），并将其恢复。

form_get 返回最近一次已发布版本中的问题。对于草稿，使用 editor_getDocument 读取内容。

编辑器

• editor_getDocument：读取表单的完整结构。
• editor_updateElement、editor_deleteElement：编辑、移动或移除区块。
• editor_formatText：设置区块内文本的格式。
• editor_setLogic、editor_testLogic：更改逻辑区块的规则并进行测试。使用 editor_insertLogic 创建区块。

每种区块类型都有专属插入工具，并采用精确的架构：

• 问题： editor_insertTextQuestion、editor_insertContactQuestion、editor_insertNumberQuestion、editor_insertDateQuestion、editor_insertTimeQuestion、editor_insertRadioQuestion、editor_insertCheckboxQuestion、editor_insertSelectQuestion、editor_insertPictureChoiceQuestion、editor_insertSwitchQuestion、editor_insertRatingQuestion、editor_insertLinearScaleQuestion、editor_insertRankingQuestion、editor_insertMatrixQuestion、editor_insertFileQuestion、editor_insertSignatureQuestion、editor_insertPaymentQuestion、editor_insertScheduleAppointmentQuestion
• 决策： editor_insertDecisionQuestion 用于插入批准 / 拒绝 / 要求修改的选项，其答案会成为请求结果。手动创建的单选题无法产生此结果。
• 内容： editor_insertHeader、editor_insertParagraph、editor_insertImage、editor_insertList、editor_insertTable、editor_insertRow、editor_insertEmbedded、editor_insertPageDivider、editor_insertDocumentsBlock
• 数据与逻辑： editor_insertHiddenField、editor_insertCalculatedField、editor_insertVariable、editor_insertRepeatingGroup、editor_insertLogic

分享与结果

• formShareLink_list、formShareLink_create、formShareLink_update：管理分享链接，也支持自定义域名。
• formSubmission_list：列出表单已完成的提交，并可按需列出草稿。
• formWebhook_list、formWebhook_create、formWebhook_update、formWebhook_delete、formWebhook_test：将表单的每次提交 POST 到你的端点，并使用 Webhook 自有密钥签名。
• formAnalytics_get：按设备、国家/地区、浏览器和来源查看浏览量、提交数、完成率和独立访客数。

外观、设置与翻译

• formTheme_get、formTheme_set：浅色和深色主题。
• formSettings_get、formSettings_update：通知邮件、完成后重定向、密码、数据保留和语言。
• translationLanguage_list、translationDraft_get、translationDraft_update、translationDraft_publish、translationLanguage_delete：将表单翻译为草稿，然后发布。

工作区

• workspace_list：获取连接所能访问的唯一工作区及其 ID。
• workspaceFolder_list、workspaceFolder_create、workspaceFolder_update、workspaceFolder_delete：管理文件夹。

内置指南

有两个工具会返回文档，而非执行操作：

• load_skill 加载某个主题的指南：requests、question-types、logic-rules、editing-flows、form-best-practices、form-themes、form-settings、analytics 或 toon-format。
• load_tools 加载一组工具的使用说明，该工具组称为目录：request-lifecycle（请求、文档以及 Stripe 和 Cal.com 连接）、editor-inserts、editor-actions、form-lifecycle、form-appearance、form-behavior、form-sharing、form-translations、form-data 或 workspace-management。

每份指南和目录也都是位于 skill://<name> 的 MCP 资源，例如 skill://requests。该服务还提供四个提示词：identity、capabilities、data_tools 和 editor_tools。

需要先确认的工具

有七个工具被标记为具有破坏性，因为撤销它们需要再次调用，或者无法撤销：form_delete、form_unpublish、workspaceFolder_delete、editor_deleteElement、translationLanguage_delete、formWebhook_delete 和 request_cancel。大多数 AI 工具在运行前都会征求你的同意。提示由你的 AI 工具发出；如果需要强制拦截，请检查其审批设置。

有两个操作无法撤销：

• workspaceFolder_delete 会永久删除文件夹、其子文件夹以及其中的所有表单。
• 使用 revoked: true 调用 formShareLink_update 会永久停用分享链接。此工具未标记为具有破坏性，因此你的 AI 工具可能不会事先征求同意。

限制

• 速率限制。 每个令牌每分钟最多调用 120 次工具，与 REST API 共享此限制。只有 tools/call 计入限制。超过限制后，调用会返回失败的工具结果，其中包含 RATE_LIMITED 和 retryAfterMs。request_create 和 document_create 还共享第二项限制：每个令牌每分钟最多调用 60 次。
• 每日新建表单数量。 工作区每天最多可通过 request_create（设置 form）新建 300 个表单。超过此数量后，任何会新建表单的调用都会因 RATE_LIMITED 失败，而重复使用已有表单的调用仍可正常进行。
• 每月额度。 每次 request_create 都会消耗工作区所有者套餐的 1 个月度额度单位，无论收件人是否最终作答。测试请求（test: true）不消耗额度。额度用尽后，request_create 会因 MONTHLY_ALLOWANCE_REACHED 失败。
• 付费套餐。 向收件人发送邮件（邀请和提醒）以及使用 formAnalytics_get 需要 Pro 或 Business 套餐。请参阅套餐和价格。
• 收件人提交时不会收到通知。 服务端永远不会调用你的 Agent。请稍后再次查询，或在 request_create 中传入 callbackUrl，让 Formstep 调用你的端点（回调）。
• 无法通过工具调用上传文件。 图片通过 URL 设置：http(s):// URL 或 data:image URI。请求所需的文档是例外：document_create 会返回一个上传 URL，你可以在一小时内通过 PUT 将文件上传至该 URL。仅支持 PDF 和图片，每个文件最大 25 MB。
• 没有工作区 AI 技能。 你在 Formstep 中编写的技能仅适用于 Formstep 内置的 AI 聊天。服务端自带的指南（load_skill）可通过 MCP 使用。

协议详情

适用于自行编写 MCP 客户端或排查连接问题的人员。

• 传输方式。 Streamable HTTP，仅支持 POST。每个响应都是 JSON。没有事件流，也没有会话 ID，因此每次调用都是独立的。按照 MCP 规范的要求，请发送 Content-Type: application/json 和 Accept: application/json, text/event-stream。
• 协议版本。 2025-11-25。
• 登录。 每次调用都需要 Authorization: Bearer <token>，包括 initialize。如果未提供，服务端会返回带有 WWW-Authenticate 标头的 401，该标头指向 https://api.formstep.io/.well-known/oauth-protected-resource。客户端可从中找到 OAuth 2.1 服务端，该服务端要求使用 PKCE（S256），并支持动态客户端注册。参考文档列出了各个步骤。
• 令牌。 两种令牌都可访问同一个工作区和相同的工具。
  • API 令牌以 fs_ 开头，自创建之日起有效期为 30 天。
  • OAuth 访问令牌以 fso_ 开头，有效期为 1 小时。你的 AI 工具会使用刷新令牌为其续期；刷新令牌有效期为 30 天，每次使用后都会被替换。
• 结果。 工具结果是一个包含 JSON 的文本项。失败时会返回 success: false 和一条 error 消息。请求工具会在 details 下添加原因代码（例如 UNKNOWN_FIELD_KEY），并提供说明如何修复调用的 suggestion。请求故障排查介绍了常见问题。
• 浏览器。 服务端仅允许来自 Formstep 自有网站的跨源调用，因此其他源上的网页无法直接调用它。

文档

• MCP 服务参考：所有工具、为你自己的客户端配置 OAuth，以及各项限制
• 连接 AI Agent
• 使用 AI Agent 创建表单
• 使用 AI Agent 发送请求
• 请求概览、字段键和回调
• 一次调用中创建表单和请求
• API 令牌和 REST API
• 隐私政策和服务条款

报告问题

• 发送邮件至 [email protected]。
• 或在此仓库中创建问题。请说明你使用的 AI 工具、登录方式、调用的工具以及收到的错误。

问题内容是公开的。请勿在其中粘贴令牌（fs_... 或 fso_...）或收件人的答案；请改为给我们发送邮件。如需报告安全问题，请参阅 SECURITY.md。

欢迎通过拉取请求修正文档。

许可证

此仓库中的文件采用 MIT 许可；请参阅 LICENSE。Formstep 服务的使用受服务条款约束。