Troubleshooting

Quick fixes for the most common issues with the Claude Connector.

If something isn't working, start here. Most issues are easy to resolve — and if not, we're an email away.

The connector isn't showing up in Claude

Claude.ai (OAuth flow):

The easiest path: connect from the Claude directory listing. If you added it manually instead, confirm the URL is https://mcp.productised.ai/mcp (no ?apiKey=... suffix).
Allow popups for claude.ai — the Productised sign-in opens in a popup.
Start a new conversation after connecting — existing conversations don't pick up new connectors automatically.

Claude Desktop (OAuth via connector picker):

Search the directory for "Productised" in Settings → Connectors (or add it manually with the URL https://mcp.productised.ai/mcp). A browser window opens for sign-in.
After authorising, return to Claude Desktop — the 🔌 icon in the chat input bar confirms the connection.

Claude Desktop (manual JSON / API key):

Confirm the JSON in Settings → Developer → Edit Config is valid (no trailing commas, properly closed braces). Paste into a JSON linter if unsure.
Restart Claude Desktop completely (⌘+Q, not just close) — the config is only read at startup.
The Authorization: Bearer YOUR_API_KEY header must be inside the headers block — not in the URL.

Almost always a popup blocker.

Click the address bar icon (or browser settings) and allow popups for claude.ai.
Click Connect on the Productised connector again.
The sign-in popup should appear.

If the popup opens but the sign-in fails:

You may be signed in to a different Productised account than the one you want. Sign out of app.productised.ai, sign back in as the right account, then retry.
Your organisation may block third-party OAuth grants. Check with your admin, or use the API-key route in Claude Desktop as a fallback.

Claude returns "Session expired" or "Tool execution failed"

The MCP server keeps sessions in memory. When the server restarts (during a deploy, for example), older sessions become invalid.

Fix: Start a new Claude conversation. The next message creates a fresh session and the connector re-initialises. Your OAuth token (or API key) is still valid — the session is just a per-conversation construct.

Follow-up requests are routed back to the same server, so mid-conversation drops are rare outside a deploy.

"Unauthorized" / 401 errors

If you connected via OAuth:

Your access token may have expired and refresh failed. Remove the Productised connector from Settings → Connectors, then add it again to re-run the OAuth flow.
If it still fails, remove Productised in Claude's Settings → Connectors and connect it again.

If you connected via API key:

Double-check the key in your Claude config matches a key listed in Productised → Settings → Advanced → API (Admins only).
The key may have been revoked. Generate a new one and update your config.
Key in the wrong place: Claude Desktop's manual config expects it in the Authorization: Bearer ... header. Claude.ai doesn't use an API key at all — it connects by signing in.

A tool call returns a warning instead of doing what I asked

The connector is self-correcting. Many tools return a structured warning + a fix payload rather than silently doing the wrong thing.

The most common one is the token coverage warning from create_page / update_page:

⚠️ This page uses 3 object tokens the AI Agent does NOT output yet — they will render blank: {{ object:sleepScore }}, {{ object:topStrength }}, {{ object:nextStep1 }}. Call set_agent_fields with the suggested_agent_fields below …

Claude reads the warning, calls set_agent_fields with the suggested fields, then the next submission populates the page.

If you ever see a warning without Claude acting on it, just say: "do what the warning suggests" — Claude will pick it up.

A result page renders literal `{{ object:* }}` tokens

This means the tokens in the page don't match the fields the AI agent produces. The page was likely created without the coverage check, or the agent fields were changed afterwards.

Fix: Ask Claude to align them:

"My result page is rendering literal {{ object:foo }} tokens. Pull the current page, check it against the agent fields, and call set_agent_fields with anything missing."

Claude calls get_page → reads tokens → set_agent_fields with the missing ones. The next submission renders correctly.

For existing responses created before the fix, the new fields won't backfill — you'll need a fresh submission to see a fully-populated render.

The result page renders but the score gauge / bars are blank

Two common causes:

The page relies on <script> tags. Designed page sections are placed straight into the result page, where scripts don't run. Build score visuals as pure CSS/SVG. The built-in result designs already work this way. If you wrote custom HTML, ask Claude: "my gauge is blank — rebuild it as a CSS/SVG ring instead of JS."
You used {{ object:* }} inside an SVG/HTML attribute. Object tokens get wrapped in <p> by the markdown renderer, corrupting attributes. Use {{ chart:fieldName }} instead for any value inside an attribute. See the tokens reference.

The result page renders but is off-centre or sprawls full-width

The result page renders inside a centred card up to 1200px wide. If your design isn't self-centring, ask Claude:

"My result page is rendering flush-left. Update the page so the content is centred — wrap in a max-width container with margin auto."

Claude calls get_page → wraps the content → update_page.

Claude says the tool returned an error

Claude shows you the error the tool sent back. The most common ones:

Product not found — Claude is probably working in a different workspace. The error names the workspace it's in; switch workspace in the app, then ask again. Or ask Claude to call list_products to confirm what it can see.
Missing required parameter — Claude didn't include product_id or similar. Re-prompt with the explicit value.
Rate limited (429) — wait a minute. The connector allows up to 200 requests a minute from one connection.
Internal server error (500) — email support@productised.ai with the time it happened and your workspace name.

The product talks in the wrong language

Ask Claude: "Set the language of [product name] to German" (English, German, French, Spanish, Italian, Dutch or Portuguese), or set it on the canvas under the AI Product node's Conversation → Collection Instructions → Language. It covers the questions, the AI Agents' analysis and the result page, and works better than adding "reply in German" to the prompt. Auto follows the language your instructions are written in.

The result page doesn't appear at the end of a test run

The result page belongs to the live product. Either:

Publish it: "Publish [product name]" (publish_product), then run through the live link again, or
Test with the demo link: open the ?demo=true link Claude shares. A run started there goes all the way through to its result page, even while the product is unpublished.

Demo URLs return 404

Every demo link is a product link ending in ?demo=true, and it works even while the product is unpublished. If one returns "not found":

The product was deleted, or you're signed in to a different account.
The product has no AI Product node — ask Claude to check the product's structure.
It's a Document result — Document results from a demo run only open for the product's creator.

The connector seems slow

Most tool calls should complete in 1–3 seconds. If you're consistently seeing slower responses, factors to check:

Heavy generate_product calls legitimately take 20–30 seconds because of the AI generation pipeline behind them. Expected.
brain_ask with large context can take 5–10 seconds — Brain loads your workspace context, which scales with how much you have.
Image upload through upload_image({ source_url }) depends on the source server's speed and the image size. Up to 10–15 seconds is normal.

If list_products, get_product, or other read tools are slow, that's worth reporting — they should be under 1 second normally.

Help

If you're stuck on something this page doesn't cover, you have three options:

Ask Claude. "How do I do X with the connector?" — Claude knows its full tool list and will point you at the right tool or the right page in these docs.
Check your workspace. If Claude can't find something, make sure the app has the right workspace open — the connector follows it.
Email us. support@productised.ai — include the timestamp of the issue and your workspace name.

Was this page helpful?