# Troubleshooting agents

Fixes for the common connection and permission problems.

## "Needs authentication" in Claude Code

Run `/mcp`, select **guidemark**, choose **Authenticate**, and finish the sign-in in your browser.

## "MCP server guidemark already exists"

You added it before, maybe with an old or empty key. Remove it and add it again:

```bash
claude mcp remove guidemark
claude mcp add --transport http guidemark https://guidemark.co/api/mcp
```

## 401: invalid, revoked or expired

* Signed-in agents renew automatically. If the connection was disconnected in Settings → Agents, sign in again.
* For a key: check it was copied whole (`gm_` plus 64 characters) and hasn't been revoked.
* A sign-in token used against `/api/v1` is refused: those tokens are for the MCP server only. Use an API key for REST.

## 403: "only lets agents save drafts" or "lacks the publish scope"

That's the publishing rule working. Either publish the draft yourself in the dashboard, or allow it: see [Drafts and publishing](/docs/agents/drafts-and-publishing).

## 429: rate limit

60 requests per minute per key or connection. Wait for the `Retry-After` seconds. Create a tour with all its steps in one call instead of one call per step.

## The tour is saved but doesn't show

* It's probably a draft. Preview it with its `?playTour=` link, then switch it on.
* Check `pageUrl` is a path on the project's domain (`/pricing`), and the project's domain is right in Settings.
* Check the selectors exist on the live page. Open the browser console on your site and run `document.querySelector('#plan-studio')`.