Skip to content

MCP Bearer-token flow for AI agent integrations

The Model Context Protocol (MCP) lets AI agents invoke tools on remote servers. AtmanID acts as the authorization layer — every tool call must present a Bearer token AtmanID issued, with the right scope for the requested tool. This guide walks the token-issuance + introspection loop end-to-end.

If you’re new to MCP itself, the Anthropic spec is the authoritative source. This guide assumes you’ve decided to use AtmanID as the auth layer and want to understand the wire format.

The flow at a glance

Four steps, two RFCs, one audit chain:

  1. The agent mints an OAuth token via POST /api/agents/mcp/oauth/token (RFC 6749 §4.4 client_credentials grant), for one MCP server (audience) and a set of that server’s tools (scope).
  2. The token is presented on every Authorization: Bearer ... call to an MCP tool endpoint.
  3. The MCP server introspects the token via POST /api/agents/mcp/tokens/introspect (RFC 7662), authenticating with its own AtmanID API key, to verify it’s active and scoped for the tool.
  4. Every step writes an audit record keyed by request_id — full forensic trail from agent → token → tool invocation.

1. Mint the OAuth token

Authenticate with the agent’s client credentials: client_id is the agent’s ID, and client_secret is an agent credential (an ifagt_… key) issued from the AI Tool Credentials page → Issue Credential. Send them with HTTP Basic auth, or as client_id / client_secret form fields. The agent must be ACTIVE and must hold an active access grant for the MCP server named in audience.

Terminal window
# Replace ATMANID_BASE_URL with your tenant URL
export ATMANID_BASE_URL="https://your-atmanid-instance.com" # replace with your AtmanID base URL
curl -X POST \
-u "$AGENT_ID:$AGENT_CREDENTIAL" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "audience=$MCP_SERVER_ID" \
--data-urlencode "scope=search_tickets create_ticket" \
"$ATMANID_BASE_URL/api/agents/mcp/oauth/token"
  • audience (required) — the ID of the MCP server the token is for.
  • scope (required) — space-separated tool names on that server.
  • ttl_minutes (optional) — token lifetime, 5 to 1440 minutes; default 1440 (24 hours).

Response (200 OK — RFC 6749 envelope plus AtmanID extensions):

{
"access_token": "ifmcp_3f9c2a...",
"token_type": "Bearer",
"expires_in": 86400,
"scope": "search_tickets create_ticket",
"audience": "mcp-srv-helpdesk",
"issued_at": "2026-10-10T09:00:00.000Z",
"token_id": "tok-7a2c8d9f"
}

Things worth noting on the response:

  • token_type is Bearer, or DPoP when the token request carried a DPoP proof header (RFC 9449) — the token is then bound to that key. A tenant can require DPoP-bound agent tokens, in which case a request without a proof is refused with invalid_dpop_proof.
  • scope is never silently narrowed: if any requested tool is outside the agent’s grant for that server, the whole request fails with invalid_scope.
  • expires_in is seconds, not a timestamp. Mint a new token before expiry by re-running the same call.

2. Use the token on tool calls

The agent SDK or MCP client presents the token on every request to the MCP tool endpoint. If the call goes straight to the MCP server, that server is responsible for verifying the token before fulfilling the request — see step 3. If it goes through the AtmanID MCP Gateway, the gateway validates the token and enforces its scope before forwarding.

POST https://your-mcp-server/tools/some-tool
Authorization: Bearer ifmcp_eyJhbGc...
Content-Type: application/json
{ ...tool-specific payload... }

Tokens are opaque. Don’t try to parse them client-side; just present them on the wire and let the MCP server validate.

3. The MCP server introspects (RFC 7662)

The MCP server validates incoming tokens by calling AtmanID’s introspection endpoint with a JSON body. The MCP server authenticates itself (RFC 7662 §2.1) with an AtmanID API key that holds the read:nhi scope and belongs to the agent’s organisation — mint it at Settings → API Keys → Create new key for the MCP server, not for the agent:

Terminal window
curl -X POST \
-H "Authorization: Bearer atman_MCP_SERVER_KEY" \
-H "Content-Type: application/json" \
-d '{"token": "ifmcp_3f9c2a..."}' \
"$ATMANID_BASE_URL/api/agents/mcp/tokens/introspect"
  • A token from another organisation reads as { "active": false } with your key.
  • Calls without a key are still answered during the transition (and recorded in the audit log); they will then be refused with 401, and a key without read:nhi with 403. Add the key now.
  • A standard-tier key allows 60 introspection calls a minute.

Send JSON, not a form-encoded body — a body that can’t be parsed as JSON is answered with { "active": false }.

Response (200 OK — RFC 7662 envelope, when active):

{
"active": true,
"token_type": "Bearer",
"scope": "search_tickets create_ticket",
"client_id": "agt-mcp-7a2c8d9f",
"sub": "agt-mcp-7a2c8d9f",
"username": "helpdesk-triage-agent",
"aud": "mcp-srv-helpdesk",
"exp": 1760173200,
"iat": 1760086800,
"mcp_server_id": "mcp-srv-helpdesk",
"grant_type": "client_credentials"
}

The response also carries AtmanID extensions such as agent_type and agent_risk_score. For a DPoP-bound token, token_type is DPoP and a cnf.jkt confirmation claim (RFC 7800) is included so the MCP server can verify the proof itself. Check that aud is your own server’s ID and that the requested tool is in scope.

If the token is expired, revoked, or unknown, the response is just:

{ "active": false }

…with no other fields. The MCP server should reject the request with 401 Unauthorized when active: false.

Audit trail

Every token issuance writes an MCP_OAUTH_TOKEN_ISSUED audit record (if that record can’t be written, the token is revoked and not returned), and every introspection of a token AtmanID issued writes an MCP_TOKEN_INTROSPECTED record — including introspections of expired or revoked tokens. Introspecting a string that was never an AtmanID token returns { "active": false } without an audit record. An auditor can trace any tool invocation by joining MCP server logs (which carry request_id) to the corresponding AtmanID audit records.

Example: every token introspection since a given time, from the audit API (needs the read:audit_logs scope):

Terminal window
curl -s "$ATMANID_BASE_URL/api/v1/audit?action_type=MCP_TOKEN_INTROSPECTED&since=2026-10-07T00:00:00Z" \
-H "Authorization: Bearer $ATMANID_API_KEY"

Each record carries its request_id, the token, the MCP server and the time — match the request_id against the MCP server’s own logs. Both endpoints also return the X-Request-Id header.

This isn’t a contrived example — it’s the exact pattern an auditor uses when investigating “did agent X actually call tool Y at time Z?”

Why introspection (not JWT verification)?

This is a deliberate design choice with a tradeoff worth understanding.

Tokens are opaque, not self-describing. The MCP server can’t decode the token locally — it has to call AtmanID for every validation. This costs one network round-trip per tool invocation (typically ~30-80ms in the same region).

In exchange:

  • AtmanID can revoke a token immediately and the MCP server sees the change on the very next introspection call. With JWT, revocation requires a denylist or short expirations — both have leakage windows.
  • Audit trail is server-side authoritative. Every introspection writes a row; you can’t accidentally lose audit data by failing to log on the MCP server side.
  • Agent status changes propagate instantly. If you suspend or deprovision an agent, the next introspection of any of its tokens returns active: false. (A token’s scope is fixed when it is issued — to narrow it, revoke the token and have the agent mint a new one.)

This is the right trade for privileged agent operations where revocation latency matters more than introspection RTT. For high-throughput non-privileged operations where you can tolerate ~5-minute revocation lag, JWT may be the better fit — file an issue if you want AtmanID to support it as an option.

Common errors

The token endpoint returns RFC 6749 §5.2 errors: { "error": "<code>", "error_description": "<text>" }.

Status error What’s wrong Fix
401 invalid_client client_id/client_secret missing or wrong, credential expired, or the agent isn’t ACTIVE Issue a new credential, or have the agent approved
400 unsupported_grant_type grant_type not client_credentials Only client_credentials is supported
400 invalid_request scope or audience missing, or audience isn’t a known MCP server Send both; check the MCP server’s ID
400 invalid_scope A requested tool isn’t in the agent’s grant for that server Request only granted tools, or widen the agent’s access grant
403 unauthorized_client The agent has no active (unexpired) access grant for that server, or the server is disabled Grant the agent access to the MCP server
400 invalid_dpop_proof The DPoP proof is invalid, or the tenant requires DPoP and none was sent Send a valid DPoP proof header
429 ({ "error": { "code": "RATE_LIMITED" } }) Token endpoint limit hit (5 requests/minute per client address) Cache the token and reuse it until expires_in — don’t mint per request; honour Retry-After
200 { active: false } from introspection Token expired/revoked/unknown (NOT an error per RFC 7662) MCP server returns 401 to the agent caller

Going further

© AtmanID · Privacy