Troubleshooting

Every MCP tool returns structured errors. Each error has a stable code field -- match against the codes below to find the resolution.

authentication_required

The MCP server has no valid access token for this session.

What it means. Either you've never signed in, your refresh token has been revoked, or local token storage was cleared (e.g. you reinstalled the server).

How to fix it.

1. Call the sign_in tool. The agent surfaces an authorization_url.
2. Open the URL in your browser and complete the Firebase sign-in.
3. The browser redirects back with code + state. Pass them to complete_sign_in (the agent usually handles this automatically if it's an interactive client).
4. Retry the original tool call.

scope_required

Your token does not carry the scope this tool needs.

What it means. Scopes are derived from your role at token issuance. A viewer's token can never call flows:write tools -- the scope is absent from the JWT, not just blocked at the API.

How to fix it.

1. Call whoami to see your current role and the scopes your token actually carries.
2. If your role is too low, ask your org owner to bump it via Settings → Team in the dashboard.
3. After the role change, sign out and sign in again to mint a fresh token -- role changes take effect on the next refresh (within 5 minutes), but signing back in is the deterministic path.

Your dashboard role is authoritative for what your token can do. Admins and owners can manage segments, experiments, integrations, and team; members can edit flows, themes, and locales; viewers are read-only. See the MCP Server overview for the short summary.

confirmation_required

The agent called a destructive operation without confirm: true.

What it means. Destructive tools (delete_flow, unpublish_flow, complete_experiment, delete_experiment, delete_segment, delete_conversion_goal, remove_member, regenerate_share_token) refuse to execute unless the agent explicitly passes confirm: true. The MCP layer rejects the call before it hits the API.

How to fix it. The agent should surface the operation summary to you and ask permission. Once you confirm, it should retry with confirm: true.

If the agent never asks (e.g. an autonomous workflow), you need to either grant blanket permission in your client's tool-use policy or have the workflow whitelist the confirmation explicitly. Setgreet will not bypass this server-side -- it's a hard requirement.

plan_required

Your organization's plan does not include MCP access.

What it means. MCP is a paid Growth / Scale feature. Starter (free) accounts are blocked at three layers:

1. At sign-in (POST /authorize/complete).
2. At every token refresh.
3. At every API request via the plan-gate middleware (60-second cache).

How to fix it. Upgrade to Growth or Scale from Settings → Billing in the dashboard. The error payload includes an upgrade_url:

{
  "error": "plan_required",
  "required_plan": ["pro", "enterprise"],
  "upgrade_url": "https://app.setgreet.com/settings/billing"
}

After upgrading, the next MCP request succeeds -- plan-mutation paths invalidate the cache synchronously, so you don't need to wait for the 60-second TTL.

If you've just downgraded, in-flight access tokens stay valid until expiry (max 5 minutes), then refresh fails with plan_downgraded.

org_mismatch

Your token is bound to a different organization than the resource you're touching.

What it means. MCP tokens are pinned to a single (user, org) pair. The backend enforces this at the URL layer via enforceMCPOrgInPath -- a token issued for org A cannot hit /organizations/B/... paths, even if you happen to be a member of both.

How to fix it. You need to switch orgs deliberately:

1. Call list_organizations to see every org you belong to.
2. Call switch_organization with the target org_id. This does not silently re-issue a token. It returns a reauth_required envelope with a fresh authorization_url.
3. Open the URL in your browser and sign in again. The new token is bound to the new org.

The PKCE round-trip is intentional -- a quiet org switch would let a compromised token escalate from a small org to a large one.

Tool not found

The agent says "I don't have a tool called X".

What it means. Almost always: your role doesn't carry the scope that gates the tool, and the client filtered it out of the tool list. Some clients display the tool but fail the call; others omit it entirely.

How to fix it.

1. Run whoami and check the scopes array.
2. Cross-reference against the tool catalog -- find the row for the tool you wanted and see what scope it needs.
3. If your role is too low, see scope_required.

A related case: if you've recently upgraded your plan or role, sign out and sign in again to refresh the tool list -- some clients cache the catalog per session.

forbidden

The endpoint requires a role you don't have, even though your scope checks out.

What it means. A few backend routes have role gates on top of scopes -- most commonly update_organization (rename, transfer ownership, change size), which is owner-only even for admins with org:write.

How to fix it. Ask the org owner to perform the action. There is no MCP-side workaround for owner-only paths.

Token refresh / 401 loops

Tools fail intermittently with authentication_required even though you signed in recently.

What it means. The MCP server tried to refresh the access token and the refresh failed. Common causes:

• The refresh token was revoked from Settings → MCP Connections in the dashboard.
• Your role was demoted to a level that no longer has plan access (rare).
• Your org was downgraded to Starter since the last successful refresh.
• The MCP server's clock is significantly skewed from the backend's.

How to fix it.

1. Call sign_out to clear the broken session.
2. Call sign_in to start fresh.
3. If the new sign-in returns plan_required, see plan_required.

Sign-out doesn't clear other clients

This is by design. sign_out revokes only the refresh token associated with the current session. If you used the same OAuth client from two terminals, signing out of one does not sign out the other -- each terminal has its own refresh token family.

To sign out everywhere, use the dashboard:

• Settings → MCP Connections → Revoke all sessions -- this hits DELETE /api/v1/me/mcp-sessions?confirm=true, which revokes every active refresh token across every client and every org.

My access token expired in the middle of a long operation

Access tokens live for 5 minutes. The OAuth-aware HTTP client in the MCP server automatically refreshes on 401, so this should be invisible. If you see explicit token_expired errors:

1. The refresh token may have been revoked -- see Token refresh / 401 loops.
2. The system clock on the MCP server host may be wrong -- check with date -u and compare against time.is.

Still stuck?

• Run whoami and capture its full output -- the resolved scopes are the fastest way to diagnose authorization errors.
• Reach out via the support channels listed at setgreet.com.