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-endpointis 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.comand 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. |
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. | 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 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 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. 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.
issmust 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,uidorsubclaim. A token with only the REST API scope is rejected on/mcpwith403. - 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 for the full list, and Microsoft Entra ID 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/mcpfor 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 usemcp.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 (runabsmartly profile listto 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 typeyes. Any other answer cancels the action. - Otherwise, and always on your instance's own
/mcpendpoint, the assistant asks you in the chat. Only after you confirm does it callexecute_commandagain 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
- For ABsmartly platform questions, reach out to the ABsmartly support team.