--- title: Troubleshooting | FLORA API description: Common FLORA MCP problems and how to resolve them. --- Quick fixes for the most common FLORA MCP issues. If none of these apply, send us the request ID from the failing tool result and the name of your client. ## Connection issues ### OAuth browser doesn’t open Your client expected to open a browser tab during the first tool call but nothing happened. - Most clients print the authorization URL when they fail to open a browser. Look for it in the client’s logs or status panel and open it manually. - For Claude Code: check terminal output above the prompt for `Open this URL to authorize: https://...`. - For Cursor / VS Code: check the notifications/toasts panel. - If a corporate browser policy blocks third-party OAuth popups, try a different default browser temporarily. ### ”Failed to connect to MCP server” Network or URL issue. Verify: Terminal window ``` curl -I https://agents.flora.ai/mcp ``` A `200` or `405` is normal (the root only accepts POST). A `connection refused`, `timeout`, or DNS error means your network is blocking the host. Common culprits: - Corporate VPN / firewall — ask IT to allow `agents.flora.ai`. - Local proxy stripping HTTPS — bypass it for `agents.flora.ai`. - The URL has a typo — it must be exactly `https://agents.flora.ai/mcp`. ### Token expired / re-auth loop If your client keeps prompting for OAuth on every call, the refresh token isn’t being persisted. Try: - **Claude Code:** `claude mcp remove flora && claude mcp add --transport http flora https://agents.flora.ai/mcp` - **Cursor / VS Code:** remove the server entry, restart the client, re-add it. - **Hermes Agent / OpenClaw:** clear `~/.mcp-auth/flora` (the `mcp-remote` token cache), then trigger a tool call to re-run OAuth. - **Claude.ai / Desktop:** disconnect the connector in Settings → Connectors, then reconnect. If the loop persists, check FLORA → Settings → Connected apps and revoke any duplicate entries for your client. ## Tool visibility ### Tools not appearing in my client After connecting, `flora` is listed but the agent doesn’t seem to know about its tools. - **Claude Code:** run `/mcp` — `flora` should show `connected` with a tool count. If it shows `pending`, trigger a tool call: *“List my FLORA Techniques.”* - **Cursor:** Settings → MCP — confirm the status dot is green. Toggle off and on if needed. - **VS Code:** make sure you’re in **Agent** mode in Copilot Chat, not Ask mode. - **Claude.ai:** in the chat, click **+** → **Connectors** and toggle FLORA on. Connectors are per-conversation. ### Agent runs the wrong thing Sometimes the agent writes `client.generations.create(...)` (a one-off generation) when you wanted a saved Technique run, or vice versa. - Be explicit: *“Use the Thumbnail v3 Technique”* — naming the Technique steers the agent toward `client.techniques.runs.create(...)` instead of the generic generation path. - If the agent says “I don’t have access to FLORA tools” but the server is connected, force the issue: *“Use FLORA MCP to list my Techniques.”* ## Errors during tool calls ### `401 invalid_token` Your OAuth token was revoked or expired and couldn’t refresh. - Reconnect via your client’s UI (see “Re-auth loop” above). - If you recently revoked access in FLORA → Connected apps, that’s the cause — reconnect from the client. ### `402 insufficient_credits` The workspace balance (USD) is too low to start the run. Top up in FLORA → Settings → Billing, then retry the tool call. ### `403 forbidden` Your FLORA user doesn’t have permission for this operation. Common cases: - Creating Projects when your role is read-only. - Accessing a workspace you’ve been removed from. - Calling a Technique that’s been archived or moved to a different workspace. Ask the agent: *“What workspace am I connected to?”* It will run `client.workspaces.list()` via `execute` and show. If it’s the wrong workspace, disconnect the connector in your client and reconnect — the OAuth flow will let you pick a different workspace. ### `404 not_found` on a run If polling a run (`client.techniques.runs.retrieve(...)`) returns 404, the run ID is wrong or the run was created in a different workspace. - Re-list recent runs: *“Show me the run I just created.”* - Verify you didn’t switch workspaces between the create and the poll. ### `input_validation_error` The tool call inputs didn’t match the Technique’s schema. The agent can self-correct: *“Have it run `client.techniques.retrieve(...)` first, then show me the inputs you’d pass.”* If the Technique recently changed inputs (added a required field), the agent may need a hint about the new field. Try: *“That Technique now requires a `brand_palette` input. Include `"warm minimalism"` for it.”* ## Output rendering ### Images don’t render inline in chat The chat shows URLs but not preview images. - **Claude.ai / Desktop:** image previews require the connector to return outputs as `image_url` content blocks (FLORA does). If they’re still not rendering, the URL may be from a private host the client can’t fetch — see “URL not accessible” below. - **Claude Code / Cursor:** these clients sometimes show URLs as text rather than images. Click the URL to open the asset. ### URL not accessible Output URLs are long-lived but not permanent. If a URL has expired: - Re-run the Technique to get fresh URLs. - For results you need to keep, download them or [attach them to a Project](/mcp/tools/index.md) at creation time. ## Performance ### Polling feels slow FLORA MCP polls the run via `client.techniques.runs.retrieve(...)` every few seconds while a run is in progress. Most Techniques finish in under 30s. If polling drags: - For longer-running Techniques (motion, batches), switch to your client’s background mode (Claude’s Cowork, Cursor’s agent run, etc.). Most clients do this automatically when the run exceeds a chat-friendly threshold. - A high `run_cost` (more than \~$0.50) or a Technique flagged “long-running” in `client.techniques.retrieve(...)` is a hint that you should expect 30s+ runs. ### Rate-limited (`429`) Rare in interactive use, more common in batch jobs. Reduce parallelism: *“Run 2 at a time instead of 8.”* ## Still stuck? Capture the request ID from the failing tool result (most clients show it in the tool’s debug panel) and send us: - Request ID - Your client and version (e.g., “Claude Code 0.x, Cursor 0.x”) - The exact prompt you typed - Approximate time of the failure (UTC) Email support, or hop on an [API onboarding call](https://cal.com/harishv/30min).