> For the complete documentation index, see [llms.txt](https://playbook.nativemsg.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://playbook.nativemsg.com/mcp/troubleshooting.md).

# Troubleshooting

## Connecting

**I can't find where to add the server in my AI tool.**

* Claude: Settings → Connectors → Add custom connector. On Team/Enterprise, an admin may need to allow custom connectors.
* ChatGPT: Settings → **Plugins** (some builds: Connectors or Apps) → Advanced settings → enable **Developer mode**, then Create. Requires a paid plan; workspace admins control availability on Business/Enterprise. Add it on chatgpt.com (web), not the mobile app.
* Cursor and others: add the URL in the tool's MCP settings/config file.

**Sign-in fails or loops.** Update your AI client and retry — the OAuth flow (including the client registering itself) is handled by the client. If it persists, note the client and timestamp and contact support.

**Connected, but no tools appear / "discovery failed."**

* ChatGPT: make sure **Developer mode is on** and the connector is **enabled in the conversation** (+ menu) — custom connectors show no tools outside Developer mode.
* Check the connector's detail page in your AI tool's settings; with everything enabled it should list the tools (73 at time of writing).
* Still empty: disconnect and reconnect the connector, then contact support with the client name — include the time so we can check the discovery request on our side.

**401 / "not authorized" on tool calls.** Reconnect and approve both read and write access. If you intentionally connected read-only, write tools (send, create, delete) will be refused — that's working as designed.

## Sending

**Message not delivered.**

1. Check status: `get_message_status` with the send's `requestId` (per-recipient status: accepted → sent → delivered/failed/read).
2. Check the recipient: subscribed to the channel (`get_human_subscription`)? Opted out contacts don't receive messages — that's correct behavior.
3. Check capability: `check_rcs_capability` — rich content to a non-RCS device falls back to SMS; confirm a fallback exists.
4. RCS channel not launched yet? Unlaunched agents can only message **tester devices**.
5. Widespread failures on one channel suggest carrier/registration issues (missing STOP/HELP or brand elements can get a program disabled) — contact support.

**Tester device gets nothing.** The device must **accept the invitation** sent when it was registered (`add_tester_device`). Check the phone's Messages app for the agent invitation.

**Blast reached fewer people than expected.** A blast reaches contacts that carry any of its tags **and** are subscribed to one of its channels. Check both: `get_blast_tags`, `get_blast_channels`, and remember tag/channel assignment replaces the whole set — a later assignment call may have dropped targeting you set earlier.

## Experiences

**My edit was refused with a subscriber count.** The experience is unpublished with subscribed contacts, so the change would reach them immediately. Either publish the experience and stage changes, or confirm to your agent that you want the change live now (it will pass `force`).

**Experience doesn't respond / wrong workflow fires.** Keywords are checked before NLU intents — an over-broad keyword steals traffic. Verify every `execute`/`goto`/`welcomeMessageExecute`/`executeOnError`/`fallback` target matches an existing workflow name exactly (typos are silent no-ops), and that workflow names are unique. Full checklist: [RCS Experience Schema → Troubleshooting](https://playbook.nativemsg.com/rcs-experience-schema).

**A `{placeholder}` rendered literally in a message.** The attribute was never set before the action that reads it. Trace the `waitFor` / `assignAttributes` / request `response` mapping that should set it, and use plain ASCII `{ }`.

**I broke a live experience.** "Restore the previous revision" — `list_experience_revisions` → `restore_experience_revision`. The replaced revision stays in history too.

## Still stuck

Contact support with: your AI tool and plan, the tool call that failed, the approximate time, and any error text. [support.nativemsg.com](https://support.nativemsg.com)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://playbook.nativemsg.com/mcp/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.