Quaflo

    MCP 使用指南

    在 Claude、ChatGPT、WorkBuddy 等 AI 助手,以及 Cursor、Claude Code 等编辑器中连接 Quaflo MCP 服务

    什么是 MCP?

    MCP (Model Context Protocol) 是一种开放协议，允许 AI 助手通过标准化的接口访问外部服务和数据源。通过 Quaflo MCP 服务，您可以在 Cursor、Claude Code 等 AI 编辑器中直接管理问卷数据，无需切换到网页界面。

    前置要求
    • 已注册 Quaflo 账号
    • 一个支持 MCP 的 AI 宿主或编辑器（如 Claude、ChatGPT、WorkBuddy,或 Cursor、Claude Code 等）
    • （仅固定令牌方式需要）已在 账户设置 → API 访问令牌 中创建令牌；OAuth 方式无需预先创建
    两种连接方式
    Quaflo 支持两种 MCP 授权方式。若你的 AI 宿主支持「添加连接器」,推荐使用 OAuth——更安全、可随时撤销、无需复制任何密钥。
    对比项OAuth 连接器推荐个人访问令牌
    授权方式浏览器登录授权,无需复制密钥手动把令牌填进配置文件
    令牌寿命短时有效 + 自动刷新长期有效(需手动轮换)
    权限控制同意页按需勾选 scope创建令牌时设定 scope
    撤销账户设置一键撤销该连接删除或停用该令牌
    适用客户端Claude、ChatGPT、WorkBuddy 等支持连接器的宿主Cursor、Trae、Windsurf 等用配置文件的客户端
    方式一:OAuth 连接器(推荐)
    在宿主里添加 Quaflo 连接器,用浏览器完成授权即可,无需创建或复制任何密钥。
    • 浏览器授权,不用手动管理密钥
    • 访问令牌短时有效并自动刷新
    • 授权时按需勾选权限,随时在账户设置撤销

    步骤 1: 在宿主中添加连接器

    打开宿主的连接器设置,选择「添加自定义 / 远程连接器」。

    步骤 2: 填入 MCP 地址

    粘贴下面的 MCP 服务地址并保存:

    https://api.quaflo.cn/api/v1/mcp

    步骤 3: 浏览器授权

    宿主会自动拉起授权页:登录 Quaflo → 勾选要授予的权限 → 点击同意,随后自动返回。

    步骤 4: 管理已授权应用

    随时在 账户设置 → 已授权应用 查看每个连接的权限与最后使用时间,并一键撤销。

    各宿主的添加入口(以你的 App 实际界面为准)

    • ·Claude(桌面 / 网页):设置 → Connectors → Add custom connector
    • ·ChatGPT:开启开发者模式 → Connectors → 添加自定义连接器
    • ·WorkBuddy:MCP 服务管理 → 添加自定义连接器(auth 选 oauth)→ 信任
    • ·Codex CLI:运行 codex mcp login <连接器名>,浏览器完成授权
    方式二:个人访问令牌(固定令牌)
    适用于用配置文件 / 请求头鉴权的客户端。若你的宿主支持连接器,建议改用上面的方式一。

    步骤 1: 打开 Cursor 设置

    点击左下角的齿轮图标，选择 "Settings" → "Features" → "MCP Servers"

    步骤 2: 添加 MCP 服务器

    在 MCP Servers 配置中，添加以下配置：

    {
  "mcpServers": {
    "quaflo": {
      "url": "https://api.quaflo.cn/api/v1/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}
    将 YOUR_PERSONAL_ACCESS_TOKEN 替换为您在个人设置中创建的实际 API 令牌。

    步骤 3: 重启 Cursor

    保存配置后，重启 Cursor 使配置生效。

    步骤 4: 验证连接

    重启后，您可以在 AI 对话中询问："列出我的问卷"，如果配置成功，AI 将能够访问您的问卷数据。

    可用功能
    配置完成后，AI 助手可以帮您执行以下操作：

    问卷管理

    • 列出所有问卷
    • 查看问卷详细信息
    • 获取问卷结构
    • 查看问卷设置

    问卷校验

    • 验证问卷质量
    • 检查逻辑问题
    • 模拟答题流程

    数据查看

    • 查看回复列表
    • 获取统计摘要
    • 导出数据

    元数据管理

    • 更新问卷标题和描述
    • 查看问卷元信息

    内容与设置写入

    • 增量修改问卷结构（survey_patch）
    • 更新问卷运行时设置（survey_update_settings：结束语、跳转、透传参数、可重复答题等）
    • 配额管理（survey_quota_patch）
    • 发布 / 停止收集（需显式确认）

    答卷提交

    • survey_test_submit_response：提交测试答卷（自动标记 testData，不污染真实数据）
    • survey_submit_response：真实提交（影响配额、报表与导出，请谨慎使用）
    使用示例
    列出我的所有问卷
    显示问卷 'customer-feedback' 的结构
    验证问卷 'survey-123' 的逻辑
    获取问卷 'nps-survey' 的回复统计
    帮我检查问卷 'abc' 是否有不可达的题目
    常见问题

    Q1AI 提示无法连接到 MCP 服务

    检查 API 令牌是否正确填写，确保令牌有效且未过期。在个人设置中查看令牌状态。

    Q2配置文件格式错误

    确保 JSON 格式正确，注意逗号、引号和大括号的匹配。可以使用 JSON 验证工具检查。

    Q3权限不足

    确保创建令牌时选择了必要的权限（scopes）。如需完整功能，建议选择所有相关权限。

    Q4服务器地址错误

    确认服务器地址正确，当前环境的 MCP 地址为： https://api.quaflo.cn/api/v1/mcp

    Q5请求返回 403（Origin 被拒绝）

    服务端通过 MCP_ALLOWED_ORIGINS 允许列表校验浏览器型客户端的 Origin 头：未配置该列表时，任何带 Origin 的请求都会被 403 拒绝。桌面编辑器（Cursor/Claude Code 等）通常不带 Origin 不受影响；浏览器型客户端需联系管理员配置允许列表。

    Q6请求返回 429（触发限流）

    MCP 按已认证用户限流（默认可由 MCP_RATE_LIMIT / MCP_RATE_WINDOW 调整），写入与发布另有更严格的按 scope 上限。收到 429 时请按响应头 Retry-After 等待后重试。

    安全提示
    • 不要将 API 令牌提交到版本控制系统（Git）中
    • 不要在公共场所分享您的配置文件截图
    • 定期更换 API 令牌，建议每 90 天更换一次
    • 如果令牌泄露，立即在个人设置中撤销它
    • 只授予必要的权限，遵循最小权限原则
    下一步
    1. 1在个人设置中创建您的第一个 API 令牌
    2. 2按照上述步骤配置您的 AI 编辑器
    3. 3尝试基本的问卷查询命令
    4. 4探索更多高级功能

    需要帮助？

    返回设置联系支持团队查看 API 文档