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.
| Method | Best for | How it works |
|---|---|---|
| API Key | Programmatic access, CI/CD, headless agents | Pass the key in HTTP headers or via the URL |
| OAuth | Interactive use in Claude Desktop, Cursor, the web, etc. | Browser-based login via your ABsmartly SAML/SSO or password |
| Federated OIDC token | Your 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: …plusx-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:
| 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... |
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:
| URL | How 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/mcp | Your 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.comto 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.
- Federated OIDC access tokens — how it works, the
token requirements, calling
/mcpand/v1, and the errors - Microsoft Entra ID — step-by-step setup for Entra ID
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,archiveanddeleteask 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).