Flow Forms

Troubleshooting

Common issues and solutions when using the Flow Forms MCP integration.

Connection Issues

"Authentication failed" or "No account context"

  • Verify your subdomain is correct in the MCP server URL
  • Try removing and re-adding the MCP server in your AI client
  • Make sure your Flow Forms user account is active
  • If using multiple accounts, confirm you're connecting to the right tenant

OAuth prompt not appearing

  • Make sure your browser allows popups from flowforms.app
  • For CLI-based clients, check the terminal output for a device code URL and authorization code to enter in your browser
  • Try restarting your AI client and initiating a new connection

Connection drops or timeouts

  • Check your internet connection
  • Restart your AI client
  • If the issue persists, remove and re-add the MCP server

Permission Errors

"Permission denied" or limited results

The AI operates with your user permissions. This means:

  • Admin users can access all forms and submissions
  • Non-admin users only see forms available to their groups
  • Creating forms requires form creation permission
  • Editing or deleting form fields requires edit permission on the form
  • Private forms are never accessible through MCP
  • Submission visibility depends on your involvement (you submitted it, you're an approver, or you're an admin)

If you're seeing fewer forms or submissions than expected, check your group memberships and role with your account administrator.

Tool-Specific Issues

"Form not found"

  • The form ID (sqid) may be incorrect - use list-forms to find the correct ID
  • The form may be private (private forms are excluded from MCP)
  • You may not have group access to the form

"Missing required elements" when creating a submission

  • Use get-form first to see which fields are required
  • All required fields must have values when creating a submission
  • If a field name appears more than once in the form, use form_element_id (numeric) instead of name

"No active notification for this submission" when approving/denying

  • You can only approve or deny submissions that are currently pending on you
  • Use get-submission with include_workflow to check the submission's current workflow status
  • The submission may already have been approved or denied by another approver

"Graduated form required" when approving

Some workflow steps require you to fill out an additional form before approving. When this happens:

  1. Use get-submission with include_workflow: true to see the graduated form details
  2. Use create-submission with parent_submission_id to submit the graduated form
  3. Then retry the approval

Element creation errors

  • "Invalid field type" - Check the supported types list in the tool reference
  • Options required - checkbox, radio, select, and autocomplete fields must include an options array
  • Composite requires props - Set props.template and props.fields when creating composite elements
  • Calculated requires operator - Set props.operator (sum, multiply, subtract, or divide) when creating calculated elements

Audit Logging

All MCP tool invocations are logged with your user ID, the tool name, input parameters, and outcome (success or error). If you need to review MCP activity for your account, contact your administrator.