---
title: Troubleshooting
description: Common issues with the Brand Stack MCP connector, from OAuth flow failures to scope errors and tool errors, and how to recover.
---

## "No eligible workspaces" on the consent screen

You're signed in but you aren't an admin of any Brand Stack workspace. Ask a workspace admin to either:

- Promote you to admin, or
- Authorize the MCP connection on their own account (the token is workspace-scoped, not user-scoped: once authorized, anyone using the same client gets the same workspace's data).

Members can still use the MCP connector on shared infrastructure once an admin has connected; what they can't do is initiate a new connection from scratch.

## "redirect_uri is not registered for this client"

Your AI client tried to use a redirect URI that wasn't included when it registered with Brand Stack. This usually means the client re-registered against a different `redirect_uri` than the one it's now passing.

Fix: remove the connection in your client (`claude mcp remove brandstack`, delete the entry in `mcp.json`, etc.), then add it again. Dynamic Client Registration creates a fresh `client_id` with the right URIs.

## "PKCE verifier mismatch"

The authorization code was redeemed with the wrong PKCE verifier. This is usually a client-side bug or a stale tab. Close any extra browser tabs running the OAuth flow and try again from the AI client.

## "Insufficient credits"

Your workspace doesn't have enough credits for the action. Check the balance:

> "Get the credits for this workspace."

Or top up at **Settings → Subscription → Plans**. The generation tools (`create_mockup`, `create_scene`) consume credits at the same rate as the in-app studio; capture and uploads are always free, and a newly connected workspace starts with 10 free mockups.

## "This token does not have the mcp:write scope"

Your client requested only `mcp:read` during the consent flow. Reconnect to grant write scope as well, or skip the write tools.

## "That URL cannot be captured"

`capture_screenshot` runs on Brand Stack's servers, so it can only reach
public addresses. A local dev server (`localhost`, `127.0.0.1`, private
network ranges) is only visible from your own machine. Capture those
where they live:

```bash
npx playwright screenshot http://localhost:3000/dashboard ./shot.png
npx @brandstack/cli upload ./shot.png
```

No API key handy? The agent can move the file without one: call
`create_upload_link` and POST the bytes to the `uploadEndpoint` it
returns. The CLI command above is the one-step version for shells that
do have a key ([API keys](/mcp/api-keys)).

If a public page times out instead, it loaded too slowly or renders only
after interaction; the same client-side capture is the fallback there
too.

## "This upload link is invalid or has expired"

Upload links from `create_upload_link` live for 30 minutes. Ask the
agent for a fresh one; it takes a second and costs nothing.

## Mockup or scene generation hangs / times out

Generation has a 120-second hard cap. If a single call hits the cap:

- Drop `image_size` to `1K` (cheaper, faster).
- Remove reference images (`character_reference_url`, `style_reference_url`); they each add a fetch step.
- Try again; model latency varies with load.

If the call returns an error after generation started, the workspace is **not** charged: credits are refunded on every failure path, and the mockup/scene row is marked `failed` in the studio.

## Revoking a connection

To revoke server-side (kills every active access + refresh token immediately):

1. Open **Settings → Developer** in Brand Stack.
2. Find the client under **Authorized clients**.
3. Click **Revoke**.

The next request from that client gets a 401 and the user has to reconnect to restore access.

To remove the connection client-side (without revoking the tokens):

- Claude Code: `claude mcp remove brandstack`
- Claude.ai web: Settings → Connectors → click the connector → **Disconnect**
- Cursor / Codex: delete the entry from `mcp.json` / `config.toml`

## Refresh token reuse

If a client tries to use a refresh token that has already been rotated, Brand Stack revokes the entire grant immediately. This is by design: refresh-token reuse usually indicates token theft. The legitimate client will get `invalid_grant` on its next refresh and trigger a fresh OAuth flow.

If you see this happen unexpectedly, check whether two copies of the same client (e.g. two Claude Code installs sharing the same config) are competing for the same grant.

## Still stuck?

Open an issue with the request id (returned in error response headers) and we'll look into it. Don't paste tokens; Brand Stack support can find the grant from the request id alone.