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 the rest can be diagnosed from the API logs in your dashboard.

The connector isn't showing up in Claude

Claude.ai (OAuth flow):

Confirm you added the integration at Settings → Connectors → Add custom connector with URL 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):

Use Settings → Connectors → Add custom connector 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.

This was a frequent issue before v1.38 when multi-machine deploys could route follow-up requests to the wrong machine. With session affinity in place, mid-conversation drops are very rare.

"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.
Your account may have been revoked from inside Productised — check Settings → API → Connected apps.

If you connected via API key:

Double-check the key in your Claude config matches a key listed in Productised → Settings → API → Keys.
The key may have been revoked. Generate a new one and update your config.
Key in the wrong place: Claude.ai expects it in the URL query (?apiKey=...), Claude Desktop's manual config expects it in the Authorization: Bearer ... header.

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 / import_design:

⚠️ 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 contains <script> tags. The HTML is injected via innerHTML which never executes scripts. Build score visuals as pure CSS/SVG. If you're using apply_result_template, this is already the case. 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 surface renders inside a centred ~720px card. 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

Open Settings → API → Logs in your Productised workspace. Find the call by timestamp. The log will show:

Exactly what was called
The full error message
The full response

The most common errors:

Missing required parameter — Claude didn't include product_id or similar. Re-prompt with the explicit value.
Product not found — Check the product_id Claude was given (or ask Claude to call list_products to confirm).
Rate limited (429) — Wait a minute. You're hitting the per-key or per-IP cap.
Internal server error (500) — Email support@productised.ai with the timestamp.

Demo URLs return 404

Two causes:

The product was deleted. Demo URLs are tied to live products; deleting the product 404s the URL.
The page was deleted. Result-page demo URLs are tied to a specific Page record. If you re-applied a template or deleted the page, the old URL 404s. Run get_page to find the new page ID.

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 has access to search_documentation and can look up the answer in the live docs.
Check your logs. Settings → API → Logs in your workspace — every call is recorded with full detail.
Email us. support@productised.ai — include the timestamp of the issue and your workspace name.

Was this page helpful?