Skip to main content

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:

FormatExample
Simple API keyAuthorization: BxYKd1U2...
Explicit Api-KeyAuthorization: Api-Key BxYKd1U2...
Subdomain shorthandAuthorization: demo-1 BxYKd1U2...
Full domainAuthorization: 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.

ErrorCauseFix
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 workThe 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_deniedYou 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. 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 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 /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?​