MCP Usage Guide

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

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)
(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.

Aspect	OAuth ConnectorRecommended	Personal Access Token
Authorization	Browser sign-in, no secret to copy	Paste a token into a config file
Token lifetime	Short-lived + auto-refresh	Long-lived (rotate manually)
Permissions	Pick scopes on the consent screen	Set scopes when creating the token
Revoke	One-click revoke per connector in settings	Delete or disable the token
Best for	Hosts with a connector UI (Claude, ChatGPT, WorkBuddy)	Config-file clients (Cursor, Trae, 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://www.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://www.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.

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://www.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

1Create your first API token in account settings
2Configure your AI editor following the steps above
3Try basic survey query commands
4Explore more advanced features

Need help?

Back to Settings Contact Support View API Docs