Quaflo

    MCP Usage Guide

    Connect Quaflo MCP in AI assistants like Claude, ChatGPT, WorkBuddy, and editors like Cursor, Claude Code, Trae, Qoder, and CodeBuddy

    What is MCP?

    MCP (Model Context Protocol) is an open protocol that allows AI assistants to access external services and data sources through standardized interfaces. With Quaflo MCP service, you can manage survey data directly in AI editors like Cursor and Claude Code without switching to the web interface.

    Prerequisites
    • Registered Quaflo account
    • An MCP-compatible AI host or editor (e.g. Claude, ChatGPT, WorkBuddy, or Cursor, Claude Code, Trae, Qoder, CodeBuddy)
    • (Fixed-token method only) An API access token created in Account Settings → API Access Tokens; OAuth needs none in advance
    Two ways to connect
    Quaflo supports two MCP authorization methods. If your AI host supports "add a connector", we recommend OAuth — it's more secure, revocable anytime, and requires no secret to copy.
    AspectOAuth ConnectorRecommendedPersonal Access Token
    AuthorizationBrowser sign-in, no secret to copyPaste a token into a config file
    Token lifetimeShort-lived + auto-refreshLong-lived (rotate manually)
    PermissionsPick scopes on the consent screenSet scopes when creating the token
    RevokeOne-click revoke per connector in settingsDelete or disable the token
    Best forHosts with a connector UI (Claude, ChatGPT, WorkBuddy)Config-file clients (Cursor, Trae, Qoder, CodeBuddy, Windsurf)
    Option 1: OAuth Connector (Recommended)
    Add the Quaflo connector in your host and finish authorization in the browser — no secret to create or copy.
    • Browser authorization, no secret to manage
    • Access tokens are short-lived and auto-refresh
    • Grant only the scopes you pick; revoke anytime in settings

    Step 1: Add a connector in your host

    Open your host's connector settings and choose "Add custom / remote connector".

    Step 2: Enter the MCP URL

    Paste the MCP server URL below and save:

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

    Step 3: Authorize in the browser

    The host opens the authorization page: sign in to Quaflo → pick the scopes to grant → approve, then it returns automatically.

    Step 4: Manage authorized apps

    Review each connector's scopes and last-used time — and revoke in one click — under Account Settings → Authorized Apps.

    Where to add it in each host (exact wording may vary)

    • ·Claude (desktop / web): Settings → Connectors → Add custom connector
    • ·ChatGPT: enable Developer Mode → Connectors → add a custom connector
    • ·WorkBuddy: MCP services → add a custom connector (auth: oauth) → Trust
    • ·Codex CLI: run codex mcp login <server-name>, then authorize in the browser
    Option 2: Personal Access Token
    For clients that authenticate via a config file / header. If your host supports connectors, prefer Option 1 above.

    Step 1: Open Cursor Settings

    Click the gear icon in the bottom left, select "Settings" → "Features" → "MCP Servers"

    Step 2: Add MCP Server

    In MCP Servers configuration, add the following configuration:

    {
  "mcpServers": {
    "quaflo": {
      "url": "https://api.quaflo.com/api/v1/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}
    Replace YOUR_PERSONAL_ACCESS_TOKEN with your actual API token created in account settings.

    Step 3: Restart Cursor

    After saving the configuration, restart Cursor to apply the changes.

    Step 4: Verify Connection

    After restart, you can ask in the AI chat: "List my surveys". If configured correctly, the AI will be able to access your survey data.

    Step 1: Open Settings

    In Claude Code, open Settings → MCP Configuration

    Step 2: Add Server

    Add Quaflo MCP server configuration:

    {
  "mcpServers": {
    "quaflo": {
      "url": "https://api.quaflo.com/api/v1/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}
    Replace YOUR_PERSONAL_ACCESS_TOKEN with your actual API token created in account settings.

    Step 3: Reload

    Save configuration and reload MCP servers.

    Step 4: Test Connection

    Try asking the AI: "Show my survey list" to verify the connection is successful.

    Step 1: Open Windsurf Settings

    Open Windsurf Settings (⌘+, on macOS, Ctrl+, on Windows/Linux), search for "MCP" to find the MCP Servers section. You can also browse the MCP Marketplace directly.

    Step 2: Edit MCP Configuration File

    Click "View raw config" to open the configuration file (located at ~/.codeium/windsurf/mcp_config.json), and add the following configuration:

    {
  "mcpServers": {
    "quaflo": {
      "url": "https://api.quaflo.com/api/v1/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}
    Replace YOUR_PERSONAL_ACCESS_TOKEN with your actual API token created in account settings.

    Step 3: Restart Windsurf

    After saving the configuration, fully restart Windsurf, then click "Refresh" in the MCP Servers section to load the new configuration.

    Step 4: Verify Connection

    Ask in Cascade chat: "List my surveys" to verify the connection is successful.

    Step 1: Open MCP Configuration Panel

    Press Ctrl+U (⌘+U on macOS) to open the Agents panel, click the gear icon to enter "AI Management" → "MCP", then select "Configure Manually".

    Step 2: Add MCP Server Configuration

    Paste the following configuration in the MCP settings (you can also create a .trae/mcp.json file in your project root):

    {
  "mcpServers": {
    "quaflo": {
      "url": "https://api.quaflo.com/api/v1/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}
    Replace YOUR_PERSONAL_ACCESS_TOKEN with your actual API token created in account settings.

    Step 3: Restart Trae

    After saving the configuration, restart Trae to apply the changes.

    Step 4: Verify Connection

    Ask in the AI chat: "List my surveys". If configured correctly, the AI will be able to access your survey data.

    Step 1: Open MCP configuration

    In WorkBuddy's MCP service management, choose to add a custom MCP (edit mcp.json).

    Step 2: Add the server config

    Add the mcpServers config below (token-based auth):

    {
  "mcpServers": {
    "quaflo": {
      "url": "https://api.quaflo.com/api/v1/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}
    Replace YOUR_PERSONAL_ACCESS_TOKEN with your actual API token created in account settings.

    Step 3: Trust and restart the session

    Click "Trust" in the MCP service list; after editing mcp.json, exit and re-enter the current session. WorkBuddy also supports the OAuth connector (Option 1), which is preferred.

    Step 4: Verify the connection

    Ask in chat: "List my surveys" — success means the connection works.

    Step 1: Open MCP settings

    In Qoder's MCP panel choose "Manual configuration" / "Add MCP server" (follow your build's UI).

    Step 2: Add the remote server

    Choose Streamable HTTP (SSE on older builds) and enter the endpoint below as the URL. If the panel supports custom headers, add Authorization: Bearer <your token>; if it does not, use the OAuth connector method above or another client. If your build accepts pasted JSON, paste the config below:

    {
  "mcpServers": {
    "quaflo": {
      "url": "https://api.quaflo.com/api/v1/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}
    Replace YOUR_PERSONAL_ACCESS_TOKEN with your actual API token created in account settings.

    Step 3: Save and refresh

    Save, then confirm the server shows as connected in the MCP list; if not, check that the token is still valid.

    Step 4: Verify

    Ask in chat: "List my surveys". A list means the connection works.

    Step 1: Open MCP settings

    In CodeBuddy IDE settings open MCP, choose "Add MCP server" and edit the config.

    Step 2: Add the server config

    Use type streamableHttp and add the mcpServers block below (the token goes in headers):

    {
  "mcpServers": {
    "quaflo": {
      "type": "streamableHttp",
      "url": "https://api.quaflo.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}
    Replace YOUR_PERSONAL_ACCESS_TOKEN with your actual API token created in account settings.

    Step 3: Save and restart the session

    Save, then start a new chat and confirm the MCP server is loaded.

    Step 4: Verify

    Ask in chat: "List my surveys". A list means the connection works.

    Available Capabilities
    Once configured, the AI assistant can help you with:

    Survey Management

    • List all surveys
    • View survey details
    • Get survey structure
    • View survey settings

    Survey Validation

    • Validate survey quality
    • Check logic issues
    • Simulate response flow

    Data Viewing

    • View response list
    • Get statistics summary
    • Export data

    Metadata Management

    • Update survey title and description
    • View survey metadata

    Content & Settings Writes

    • Incrementally modify survey structure (survey_patch)
    • Update runtime settings (survey_update_settings: thank-you message, redirects, pass-through params, repeat-submission policy, etc.)
    • Quota management (survey_quota_patch)
    • Publish / stop collection (explicit confirmation required)

    Response Submission

    • survey_test_submit_response: submit test responses (auto-tagged testData, never pollutes real data)
    • survey_submit_response: real submission (affects quotas, reports and exports — use with care)
    Usage Examples
    List all my surveys
    Show the structure of survey 'customer-feedback'
    Validate the logic of survey 'survey-123'
    Get response statistics for survey 'nps-survey'
    Check if survey 'abc' has any unreachable questions
    Troubleshooting

    Q1AI reports unable to connect to MCP service

    Check if the API token is correctly filled in, ensure the token is valid and not expired. Check token status in account settings.

    Q2Configuration file format error

    Ensure JSON format is correct, pay attention to commas, quotes, and bracket matching. Use a JSON validator tool to check.

    Q3Insufficient permissions

    Ensure necessary scopes were selected when creating the token. For full functionality, select all relevant permissions.

    Q4Incorrect server address

    Confirm the server address is correct. The MCP endpoint for your environment is: https://api.quaflo.com/api/v1/mcp

    Q5Requests return 403 (Origin rejected)

    The server validates the Origin header of browser-based clients against the MCP_ALLOWED_ORIGINS allowlist. When unset, ANY request carrying an Origin header is rejected with 403. Desktop editors (Cursor/Claude Code) normally send no Origin and are unaffected; browser-based clients need the allowlist configured by an administrator.

    Q6Requests return 429 (rate limited)

    MCP rate-limits per authenticated user (tunable via MCP_RATE_LIMIT / MCP_RATE_WINDOW), with tighter per-scope caps on writes and publishes. On 429, wait for the Retry-After response header before retrying.

    Security Tips
    • Do not commit API tokens to version control (Git)
    • Do not share screenshots of your configuration file publicly
    • Rotate API tokens regularly, recommended every 90 days
    • If a token is leaked, immediately revoke it in account settings
    • Only grant necessary permissions, follow the principle of least privilege
    Next Steps
    1. 1Create your first API token in account settings
    2. 2Configure your AI editor following the steps above
    3. 3Try basic survey query commands
    4. 4Explore more advanced features

    Need help?

    Back to SettingsContact SupportView API Docs