# Troubleshooting

Common issues and how to fix them.

## Authentication

### "Failed to authenticate" or 401 errors with an API key

Check the `Authorization` header format. The server accepts several variants:

| Format              | Example                                           |
| ------------------- | ------------------------------------------------- |
| Simple API key      | `Authorization: BxYKd1U2...`                      |
| Explicit `Api-Key`  | `Authorization: Api-Key BxYKd1U2...`              |
| Subdomain shorthand | `Authorization: demo-1 BxYKd1U2...`               |
| Full domain         | `Authorization: demo-1.absmartly.com BxYKd1U2...` |

If you use the **subdomain shorthand** or **full domain** form, you do **not** need to send `x-absmartly-endpoint` — the server constructs the endpoint automatically.

If you use the **simple** or **`Api-Key`** form, you **must** send `x-absmartly-endpoint: https://your-instance.absmartly.com` (or include `?absmartly-endpoint=...` in the URL).

### OAuth login loops or doesn't complete

* **Wrong instance URL.** If `absmartly-endpoint` is missing or points at the wrong subdomain, the OAuth callback can't reach your instance. Re-add the connector with an explicit `?absmartly-endpoint=https://your-instance.absmartly.com`.
* **Browser blocking pop-ups or third-party cookies.** Allow pop-ups for `mcp.absmartly.com` and your ABsmartly subdomain, and ensure third-party cookies aren't fully blocked for the SAML/SSO callback.
* **Stale session.** Sign out of ABsmartly in the browser tab, then restart the OAuth flow from the MCP client.
* **Different browser.** The consent page and your ABsmartly sign-in must happen in the same browser. If your MCP client opens a different browser from the one you use for ABsmartly, sign in there too.

### OAuth errors

Some messages differ between the hosted server (`mcp.absmartly.com`) and your instance's own `/mcp` endpoint. Where they differ, both are listed.

| Error                                                                                                                                                                       | Cause                                                                                                                                                                                                | Fix                                                                                                                                                                                                                                                                                        |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `invalid_client` — *"This MCP client is not supported by this server"* (hosted server) or *"Unknown client"* (your instance)                                                | The client identifies itself with a metadata-document URL that isn't on the trusted list.                                                                                                            | Use an API key, or [ask for the client to be added](https://docs.absmartly.com/docs/APIs-and-SDKs/MCP-Server/oauth-clients.md#your-client-isnt-on-the-list).                                                                                                                               |
| `invalid_redirect_uri` — *"One or more redirect\_uris are not allowed"*                                                                                                     | The client tried to register with a redirect URI that isn't on the [allowlist](https://docs.absmartly.com/docs/APIs-and-SDKs/MCP-Server/oauth-clients.md#allowed-redirect-uris).                     | Use an API key, or ask for the client to be added.                                                                                                                                                                                                                                         |
| `invalid_client` for a client that used to work                                                                                                                             | The client's registration expired. On the hosted server, registrations expire 90 days after they are created. On your instance, they expire after 90 days without use.                               | Remove the connector and add it again so it registers again. If you registered the client manually, [register it again](https://docs.absmartly.com/docs/APIs-and-SDKs/MCP-Server/oauth-clients.md#manual-registration) and enter the new `client_id` and `client_secret` in the connector. |
| *"PKCE with code\_challenge\_method=S256 is required"* (hosted server) or `invalid_request` — *"PKCE is required. Supported code\_challenge\_method: S256"* (your instance) | The client sent no PKCE challenge, or used `plain`.                                                                                                                                                  | Update the client. If it can't use `S256`, use an API key.                                                                                                                                                                                                                                 |
| *"Authorization request expired or invalid, please restart the connection from your MCP client"*                                                                            | The consent page was left open for more than 10 minutes, or was approved in a different browser from the one that started it. On the hosted server, it also appears if the page was submitted twice. | Start the connection again from the MCP client, and complete it in one browser.                                                                                                                                                                                                            |
| *"This login was started in a different browser…"* (hosted server only)                                                                                                     | The sign-in to your instance finished in a different browser from the one that approved the consent page.                                                                                            | Copy the authorization link into the browser where you're signed in to ABsmartly, or restart the connection.                                                                                                                                                                               |
| `invalid_grant` — *"The ABsmartly session has ended, please sign in again"* (hosted server) or *"The session that approved this request has ended"* (your instance)         | You signed out of ABsmartly, or your session expired.                                                                                                                                                | Reconnect the client and sign in again.                                                                                                                                                                                                                                                    |
| `access_denied`                                                                                                                                                             | You clicked **Deny** on the consent page.                                                                                                                                                            | Reconnect and click **Approve**.                                                                                                                                                                                                                                                           |

See [OAuth & Client Registration](https://docs.absmartly.com/docs/APIs-and-SDKs/MCP-Server/oauth-clients.md) for how clients are accepted.

### Errors with a federated OIDC token (e.g. Microsoft Entra ID)

If your backend calls `/mcp` with a federated token and the request is rejected, decode the token locally and compare its claims with the [token requirements](https://docs.absmartly.com/docs/APIs-and-SDKs/Federated-Authentication/federated-oidc-tokens.md#token-requirements). The most common causes are:

* **Wrong token.** An ID token, the token for your own backend app, or a token for another API (such as Microsoft Graph) is rejected. Send the access token issued for the ABsmartly API, with the MCP scope (for example `mcp.access`).
* **Issuer mismatch.** `iss` must match the issuer ABsmartly has exactly. With Entra ID, version 1 tokens (`https://sts.windows.net/…`) don't match.
* **Missing scope or subject.** The token must carry the MCP scope and a stable `oid`, `uid` or `sub` claim. A token with only the REST API scope is rejected on `/mcp` with `403`.
* **Unlinked user.** The user must sign in through SAML SSO once after federated tokens are enabled to link their identity. Until then, tool calls return a message with the sign-in link. Follow it and sign in.
* **Archived user.** Signing in again doesn't help a linked user who has been archived. Ask an ABsmartly administrator to unarchive them.
* **Calling app not allowed.** The client ID claim isn't one of the client IDs you sent to ABsmartly support.

See [Federated OIDC access tokens](https://docs.absmartly.com/docs/APIs-and-SDKs/Federated-Authentication/federated-oidc-tokens.md#troubleshooting) for the full list, and [Microsoft Entra ID](https://docs.absmartly.com/docs/APIs-and-SDKs/Federated-Authentication/microsoft-entra-id.md#troubleshooting) for Entra-specific problems.

### MCP client loses access after I sign out

When you connect to your instance's own `/mcp` endpoint, the client's access is tied to the browser session you approved it from. Signing out of ABsmartly in that browser ends access for every MCP client approved from it. Reconnect the client to sign in again.

The same happens the other way round. If an MCP client disconnects and revokes its token, that browser is signed out of ABsmartly, and other MCP clients approved from it lose access too. The token also expires after 24 hours without use.

### "API key sessions can't use OAuth"

The server deliberately blocks mixing the two — you can't connect with an API key and then trigger OAuth discovery on the same session. Pick one method per connector. If you want to switch, remove the connector and add it again with the new auth method.

## Connection

### MCP tools don't appear in the assistant

* **VS Code (Copilot):** MCP tools only show up in **Agent mode**, not Ask or Edit mode. Switch modes and reload the window if needed (Command Palette → **Developer: Reload Window**).
* **Gemini Code Assist:** MCP support requires the agent preview channel. Set `"geminicodeassist.updateChannel": "Insiders"` in VS Code settings, then reload.
* **Claude Desktop / Cursor / Windsurf:** restart the app fully (quit, don't just close the window) after editing the config file.

### "Connection refused" or the server doesn't respond

* For **remote**: check that `https://mcp.absmartly.com/sse` (or `/mcp` for Streamable HTTP) is reachable from your machine — corporate proxies and VPNs occasionally block it. If you use your instance's own endpoint (`https://your-instance.absmartly.com/mcp`), remember it supports Streamable HTTP only — SSE clients must use `mcp.absmartly.com/sse`.
* For **local stdio (`npx @absmartly/mcp`)**: make sure Node.js 22+ is on your PATH and that the ABsmartly CLI profile you reference exists (run `absmartly profile list` to check).

### SSE transport works but Streamable HTTP doesn't (or vice versa)

The two endpoints expose the same tools. Older MCP clients sometimes only support `/sse`; newer ones prefer `/mcp` (Streamable HTTP). If one transport fails, switch to the other.

The MCP spec deprecated SSE in March 2025, but `/sse` continues to be supported for compatibility.

## Commands

### "Command requires confirmation"

This is expected behavior for destructive operations — `start`, `stop`, `archive` and `delete` always ask you to confirm before they run.

* On the hosted server (`mcp.absmartly.com`) and the local stdio server, if your client supports MCP **elicitation**, it shows a prompt asking you to type `yes`. Any other answer cancels the action.
* Otherwise, and always on your instance's own `/mcp` endpoint, the assistant asks you in the chat. Only after you confirm does it call `execute_command` again with the same parameters plus `"confirmed": true`.

If the assistant runs a destructive command without asking you, report it — the server instructs it never to set `confirmed` on its own.

### `createExperimentFromTemplate` returned a preview, not a created experiment

Also expected. The first call returns the resolved API payload (with names mapped to IDs) plus any warnings. Review the preview, then call again with `"confirmed": true` to create the experiment.

### "Method not found" or similar from `execute_command`

The command catalog evolves over time. Use `discover_commands` (no parameters) to list current groups, then `discover_commands(group: "...")` to list current commands in a group. If a command from older docs is gone, the catalog will suggest a replacement.

### Validation errors when creating experiments or metrics

The server surfaces the full validation error from the ABsmartly API. Common causes:

* A referenced **application**, **unit type** or **team** doesn't exist (names are resolved to IDs automatically — make sure they match exactly)
* A referenced **metric** or **goal** is archived
* The template YAML frontmatter is missing required fields (`name`, `type`, `unit_type`, `application`)

Use the `absmartly://entities/...` resources to look up valid entity names before retrying.

## Performance

### List operations are truncated

`execute_command` defaults `limit` to **20** for list operations. To get more results, pass `limit: 100` (or higher) in `params`, or use `raw: true` to get the full pagination object back so the assistant can fetch additional pages.

### Responses feel slow

The first request after a cold start fetches all entities (applications, unit types, users, teams, metrics, goals, tags, custom fields) in parallel and caches them. Subsequent requests reuse the cache. If response time is consistently bad, check your network path to `mcp.absmartly.com`.

## Still stuck?

* Check the server source and issues: [github.com/absmartly/mcp/issues](https://github.com/absmartly/mcp/issues)
* For ABsmartly platform questions, reach out to the ABsmartly support team.
