Troubleshooting

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:

curl -I https://florafauna-ai.stlmcp.com/

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 *.stlmcp.com.
• Local proxy stripping HTTPS — bypass it for florafauna-ai.stlmcp.com.
• The URL has a typo — it must be exactly https://florafauna-ai.stlmcp.com/ with the trailing slash and no extra path.

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://florafauna-ai.stlmcp.com/
• Cursor / VS Code / Windsurf: remove the server entry, restart the client, re-add it.
• 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 picks the wrong tool

Sometimes the agent calls start_generation_run when you wanted a Technique run, or vice versa.

• Be explicit: “Use the Thumbnail v3 Technique” skips the generic start_generation_run 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 has run out of credits. 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 call list_workspaces 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 retrieve_technique_run 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: “Run retrieve_technique 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 at creation time.

Performance

Polling feels slow

FLORA MCP polls retrieve_technique_run 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 runCost of >20 credits or a Technique flagged “long-running” in retrieve_technique 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.