Skip to main content
Most problems are one of five things. Work down the list in order — authentication and identity account for the large majority.

​
🔑 Authentication

The MCP Inspector (and several MCP clients) won’t send Authorization unless you add it explicitly. If every tool call returns “Invalid or missing API key”, the header isn’t reaching the server — check the client’s request-headers config before suspecting the key.
Prove the key works outside your agent, with plain HTTP:
A 200 means the key and product id are fine and the problem is in how your agent sends them.

​
Can’t connect at all

  • Transport — the server speaks Streamable HTTP. A client configured for stdio or plain SSE won’t connect.
  • Trailing slash — the canonical endpoint is https://mcp.autoplay.ai/mcp, with no trailing slash. Requesting /mcp/ can produce a 307 redirect that some streaming clients won’t follow mid-stream.
  • Sessions — the server is stateless, so a client that insists on an mcp-session-id handshake isn’t required to carry one.

​
🪪 Identity mismatches

This is the single most common cause of “Autoplay isn’t working”. The store is keyed by user_id, so an agent that asks for a different value reads an empty bucket — and a busy user looks idle. Confirm the same value appears in all three places:
Use a stable user id — your internal user primary key, the one your activity source identifies with. Do not key on email: emails change, and activity is stored under the stable id, so an email lookup reads the wrong bucket.
Full rule and the per-agent mechanisms for passing a verified id: Identity.

​
📭 Empty activity

actions: [] with authentication and identity both correct means there’s genuinely nothing stored. In order of likelihood:
  1. The user hasn’t browsed yet. Identifying a user stores nothing on its own. With PostHog, activity is built from $pageview and $autocapture events — the user has to actually navigate or click.
  2. Autocapture is off. If your provider’s autocapture is disabled, clicks and form submits never arrive.
  3. The activity expired. Live activity has a 4-hour TTL. A user who was active yesterday reads as empty — that’s by design; it’s live memory, not an archive.
  4. Ingestion isn’t wired up. Work back through Quickstart Steps 1–3: the snippet, posthog.identify(...), product registration, and the ingest webhook.
Only the last 50 actions per user are kept. If you expected a step from much earlier in a long session, it may have been trimmed. Onboarding progress is not affected — it’s durable state, read through get_onboarding_context.

​
🧭 Onboarding state unavailable

role_unknown and degraded both exist so the agent can fail closed. Reporting “onboarding complete” to a user whose state simply couldn’t be read is the failure mode these flags prevent — don’t collapse them into done.

​
🛠️ Failed and missing tool calls

​
The tool isn’t in the list

get_live_user_activity is always advertised. The other seven tools appear only once your product’s onboarding is configured with Autoplay — the server doesn’t advertise a tool it can’t serve. If your client only sees get_live_user_activity, onboarding isn’t wired up for that product yet.

​
The tool call comes back wrong

​
The agent burns turns before answering

Chaining get_live_user_activity + get_onboarding_context + list_user_tours costs several blocking reads, and some platforms (Intercom Fin among them) run at most one blocking tool per turn and silently drop the rest. Use get_recommendation_context instead — one call returns activity, onboarding progress, the next step, and the matching tour, with a smaller payload than get_onboarding_context alone.

​
The agent claims a walkthrough opened when it didn’t

A tour opens only through guide_next_step or trigger_user_tour. Describing a tour in text does nothing. Instruct your agent to claim a walkthrough is opening only after launched: true comes back.

​
Still stuck?

Ask in Discord with your product_id, the tool you called, the user_id you sent, and the exact response.