# Troubleshooting

## The server does not connect

- Confirm the URL is exactly `https://betterstood.com/api/mcp` and the transport is Streamable HTTP, not SSE.
- Confirm `BETTERSTOOD_MCP_TOKEN` exists in the environment of the agent process.
- Restart the client after changing user-level MCP configuration.
- Do not test the endpoint with browser navigation: GET is intentionally unsupported.

## I receive 401

The token is absent, malformed, expired, revoked, or no longer belongs to a current owner/admin membership. Create a replacement PAT and update the client secret store.

## A write tool is missing

Tool discovery is scope-filtered. A read-only PAT lists only read tools. A Scale-to-Growth/PAYG downgrade keeps the five oldest active PATs and suspends excess credentials; a downgrade from PAYG, Growth, or Scale to Free or Pro suspends every PAT. A Developer Access kill switch can also suspend the whole surface.

## An update conflicts or is locked

For `REVISION_CONFLICT`, get the scenario or campaign again and reconcile against the new revision. For `RESOURCE_LOCKED`, another editor holds the temporary exclusive lease: wait for release or expiry, then read the latest revision before explicitly retrying; do not attempt an early takeover. For `SCENARIO_LOCKED`, an active campaign prevents public MCP scenario edits; use the returned Studio URL. For `CAMPAIGN_LOCKED`, the campaign is not DRAFT or a scenario/channel routing change conflicts with an open non-test interaction; use the returned editor URL.

## Product knowledge search is unavailable or empty

`SERVICE_UNAVAILABLE` means Betterstood could not verify the requested product-reference bundle. Retry with bounded backoff; the server deliberately avoids stale, partial, or cross-language results. An empty result is different: the verified documents contain no match in the requested locale and topics, so simplify the query or broaden `topics`.

`elicitra_knowledge_search` does not search a scenario's Knowledge Base. Continue in Studio for organization document upload, publication, attachment, or retrieval testing.

## Webhook verification does not complete

Return 2xx quickly, verify the signature over the raw `application/json` body, read its sole `challenge` field, then enter that exact value in Betterstood. The control body is not a CloudEvent, and a 2xx response alone does not prove endpoint possession.

## Deliveries repeat

At-least-once delivery permits duplicates. Persist CloudEvent `id` before processing and return 2xx for ids already accepted. Do not use request timestamp or delivery attempt as the business id.

## Signature checks fail

Verify against the raw body bytes, not re-serialized JSON. Parse every `v1` value during the 24-hour rotation overlap, keep clocks synchronized, and use constant-time comparison.