Skip to main content

Authentication

The ABsmartly MCP server supports two authentication methods. Both are configured per client — there are no server-side secrets, so credentials are always provided by your MCP client and isolated per connection. Your instance's /mcp endpoint can also accept federated OIDC tokens, for example from Microsoft Entra ID, sent by your own backend applications.

MethodBest forHow it works
API KeyProgrammatic access, CI/CD, headless agentsPass the key in HTTP headers or via the URL
OAuthInteractive use in Claude Desktop, Cursor, the web, etc.Browser-based login via your ABsmartly SAML/SSO or password
Federated OIDC tokenYour own backend agent acting for users signed in to your identity provider (e.g. Microsoft Entra ID)Your backend sends an access token from your identity provider as a Bearer token (enabled on request)

API key​

API keys are issued from your ABsmartly instance under Settings → API Keys. They authenticate every request and identify which ABsmartly account the MCP session belongs to.

Where to pass the key​

Depending on the client, the API key is supplied as either:

  • An HTTP header (Authorization: … plus x-absmartly-endpoint: …), or
  • A query string parameter on the connection URL (?api_key=YOUR_API_KEY&absmartly-endpoint=https://your-instance.absmartly.com).

See the Setup guide for the exact configuration per client.

Authorization header formats​

When using API key authentication, these header formats are all supported:

FormatExample
Simple API keyAuthorization: BxYKd1U2...
Explicit Api-KeyAuthorization: Api-Key BxYKd1U2...
Subdomain shorthandAuthorization: demo-1 BxYKd1U2...
Full domainAuthorization: demo-1.absmartly.com BxYKd1U2...

The subdomain shorthand auto-constructs the endpoint as https://<subdomain>.absmartly.com/v1, so you don't need to send a separate x-absmartly-endpoint header.

API keys on your instance's /mcp endpoint​

When you connect to https://your-instance.absmartly.com/mcp directly, the instance is already known, so only the key is needed:

Authorization: Api-Key YOUR_API_KEY

OAuth​

OAuth uses your existing ABsmartly login (SAML, SSO or email and password). This is the recommended method for interactive clients like Claude Desktop, Cursor, VS Code or ChatGPT.

The first time the client connects, it opens a browser window. On the hosted server, you first review the Authorize Access consent page for your instance URL and click Approve, then sign in to your ABsmartly instance. On your instance's own /mcp endpoint, you sign in first and then approve the consent page. The client then receives a token and the MCP connection is established. Later connections reuse the token until it expires or your ABsmartly session ends.

There are two OAuth-enabled MCP URLs:

URLHow OAuth works
https://mcp.absmartly.com/mcp (hosted)The hosted server signs you in through your instance and issues its own access token (1 hour) and refresh token (30 days) to the client.
https://your-instance.absmartly.com/mcpYour instance is the OAuth server. The client receives a token tied to your browser session, which expires after 24 hours without use. Signing out of ABsmartly ends its access.

Every OAuth connection uses the authorization code flow with PKCE (S256). For the full sequence, the endpoints involved and the ways an MCP client can be registered, see OAuth & Client Registration.

Specifying the instance URL​

On the hosted server, OAuth needs to know which ABsmartly instance to sign you in to. You can provide this in either of two ways:

  • Add ?absmartly-endpoint=https://your-instance.absmartly.com to the MCP URL, or
  • Omit it — the OAuth flow asks you for the URL in the browser before login.

When you connect to https://your-instance.absmartly.com/mcp directly, the instance is implied by the URL.

Supported clients​

Most MCP clients are accepted automatically, either through a trusted client metadata document or through dynamic client registration with an allowlisted redirect URI. If your client is rejected, use an API key instead, or see Your client isn't on the list?.

Federated OIDC tokens (e.g. Microsoft Entra ID)​

If you run your own backend agent or application for users who are signed in to your OpenID Connect identity provider, it can call your instance's /mcp endpoint with an access token issued by that provider for ABsmartly, obtained for example through the On-Behalf-Of flow or token exchange. Each call acts as the matching ABsmartly user, with that user's permissions. This is enabled per instance by ABsmartly support.

For /mcp, the token must carry the MCP scope, by convention mcp.access. Federated tokens work only on your instance's own /mcp endpoint, not on the hosted server at mcp.absmartly.com. The same kind of token can also be enabled for direct REST API calls, with a separate scope.

Local stdio (CLI credentials)​

When running the server locally with npx @absmartly/mcp, authentication uses your ABsmartly CLI configuration and macOS Keychain credentials. Select a profile with --profile=<name> (for example, --profile=production).

Security model​

  • No server-side secrets — credentials are always provided by the MCP client.
  • Session isolation — each connection has its own credentials.
  • OAuth protection — API key sessions block OAuth discovery to prevent authentication-method confusion.
  • Restricted OAuth clients — only trusted clients and allowlisted redirect URIs can receive OAuth access, and every new client is shown on a consent page first (see OAuth & Client Registration).
  • PKCE required — OAuth requests must use PKCE with S256.
  • Destructive action confirmation — destructive operations such as start, stop, archive and delete ask you to confirm before they run, on every transport (see the Tools Reference).
  • API error surfacing — validation errors from the API are returned with full detail so the assistant can correct them.

Checking who you are​

Once connected, you can confirm authentication and identity at any time with the get_auth_status tool:

Are we authenticated?

The response includes the authenticated email, name, ABsmartly endpoint and the authentication type in use (API Key or OAuth).