> ## Documentation Index
> Fetch the complete documentation index at: https://developers.autoplay.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting
> The failures that actually come up when connecting an agent to Autoplay — authentication, identity mismatches, empty activity, unavailable onboarding state, and failed tool calls.
Most problems are one of five things. Work down the list in order — authentication and identity account for the large majority.
## 🔑 Authentication
| What you see | What it means | Fix |
| --------------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MCP tool call fails with *"Invalid or missing API key"* | The `Authorization` header never reached the server, or the key is wrong | Send `Authorization: Bearer YOUR_MCP_KEY`. Many MCP clients strip custom headers unless you add them explicitly — see the note below. |
| MCP tool call fails with *"API key does not match product\_id"* | The key is valid, but it's scoped to a different product | The key's `external_id` must equal the `product_id` you pass to the tool. A key for product A can't read product B. Use the `mcp_key` issued for **this** `product_id`. |
| REST endpoint returns **401** | Token missing or invalid | Same as *"Invalid or missing API key"*. |
| REST endpoint returns **403** | Token valid, wrong product | Same as *"API key does not match product\_id"*. |
**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:
```bash theme={null}
curl "https://mcp.autoplay.ai/users/YOUR_PRODUCT_ID/user_12345/live-activity?limit=5" \
-H "Authorization: Bearer YOUR_MCP_KEY"
```
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:
```
1. the id your activity source identifies the user with ← posthog.identify(...) / Amplitude user_id
2. the id Autoplay stored activity under ← follows layer 1 automatically
3. the user_id your agent sends to the tool ← this is the one that's usually wrong
```
| Symptom | Likely cause |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `actions` is empty for a user you know is active | The agent is sending its own contact id, an email, or an anonymous session id instead of your stable user id |
| Activity appears for some users but not others | Only some sessions are identified — anonymous (not-logged-in) users have no trusted identity to pass |
| It worked in a test call but not from the agent | Your `curl` used the right id; the agent's verified identity is bound to a different field |
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](/activity/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](/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`](/mcp/tools#get_onboarding_context).
## 🧭 Onboarding state unavailable
| What you see | What it means | What the agent should do |
| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `degraded: true` on `get_onboarding_context`, or `onboarding.degraded: true` on `get_recommendation_context` | Onboarding state is **temporarily** unavailable | Give generic help. Do **not** assert specifics about the user's progress, and don't tell them they're done. Retry shortly. |
| `guide_next_step` returns `not_configured: true` | The product has no onboarding workflows configured at all | Configure onboarding for the product. Until then there's no next step to guide toward. |
| `guide_next_step` returns `role_unknown: true` | The user has no role on record and the product has role-scoped workflows, so their chain can't be resolved | Assert the role — pass `role` to `guide_next_step`, or call `PUT /users/{product_id}/{user_id}/role`, then retry. Treat this as **unknown**, never as "you're all done". |
| `journey_stage: "new"` and everything at zero for a user who has clearly used the product | Autoplay has never seen this user — almost always the identity mismatch above | Check identity before assuming state is broken. |
`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
| Response | Meaning | Fix |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| *"Unknown tour\_id '…' for this product"* | No such tour — **or** a tour the user's role may not see (the error deliberately doesn't distinguish the two) | Pass a `tour_id` exactly as returned by [`list_user_tours`](/mcp/tools#list_user_tours) **for that user**, so role scoping is applied. |
| `guide_next_step` returns `guide_in_text: true` | Normal, not an error: no in-app tour is configured for the next step | Walk the user through the step **in words**. Never tell them to launch a tour that doesn't exist. |
| `record_workflow_confirmation` returns `status: "unknown_workflow"` | The `workflow_key` doesn't match an active workflow | Use the exact `key` from `get_onboarding_context` / `get_recommendation_context` — don't invent or abbreviate it. |
| `record_workflow_confirmation` returns `already_completed: true` | The workflow was already complete | Nothing to fix; the call is a safe idempotent no-op. |
| A tour returns `status: "queued"` but nothing appears | The user's browser session isn't open, or the app tab was closed | Tours land within a few seconds **if the user has the app open**. Confirm the session is live. |
### 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`](/mcp/tools#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`](/mcp/tools#guide_next_step) or [`trigger_user_tour`](/mcp/tools#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](https://discord.gg/jCbR2tQA5) with your `product_id`, the tool you called, the `user_id` you sent, and the exact response.