# 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](/mcp/tools#create-form-element) 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.