Troubleshooting

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

#Connection Issues

#"Unauthenticated." or "No account context available."

• 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

#Requests failing with HTTP 429

The MCP endpoint allows 60 requests per minute per user. An AI assistant working through a long task can hit that ceiling; it should pause and retry. If you see repeated 429s, ask the assistant to batch its work (for example, batch-create-form-elements instead of one call per field).

#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 hidden from listings and submission tools; only the form's editors and admins can open them with get-form
• 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 listings unless you can edit them)
• 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

#"You do not have an active notification for this submission."

• 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

#"This workflow step requires a graduated form to be completed before approval."

Some workflow steps require you to fill out an additional form before approving. The error itself names the form to submit. 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 a template - Set props.template when creating composite elements; props.fields is derived from it automatically
• Calculated requires operator - Set props.operator (sum, multiply, subtract, divide, min, max, age, time_difference, or date_offset) when creating calculated elements. date_offset also needs props.days and props.direction (forward or back).

#Audit Logging

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.