Authenticate agents to the MCP gateway
How agents sign in to the MCP gateway, custom agent credentials, revoking access, and DPoP-bound tokens.
Before the MCP gateway runs any tool call, the agent has to prove which agent it is and whom it acts for. This page covers how agents sign in to the MCP gateway, the credentials for agents that can't sign in through a browser, and how to revoke access. For how calls then reach Slack, Jira and other services with each person's own account, see Connections.
Gateway MCP endpoints
Agents connect to the gateway URL or to a scoped gateway: a per-service gateway, a per-server gateway, or a virtual MCP gateway built from policy tags. See Gateway URLs for each one and when to use it.
Agent authentication
Agents connect over MCP and authenticate through the browser sign-in flow the agent surfaces on first connect (see any agent's setup guide, for example Claude Code). The gateway auto-registers the connecting client as a new agent instance and ties it to the user who completed sign-in. See Agents for how instances are tracked afterward.
That flow is standard OAuth.
The gateway serves protected-resource metadata for each endpoint.
The aggregate endpoint uses /.well-known/oauth-protected-resource/gateway/mcp.
A single-MCP endpoint uses /.well-known/oauth-protected-resource/gateway/mcp/{slug}.
The metadata points the agent at your organization's issuer as the authorization server.
It advertises the mcp_gateway, profile, and email scopes.
Each document's resource is the endpoint it describes.
A client following RFC 9728 compares that resource value with the URL it connected to before trusting the metadata.
The tags query parameter is not part of the endpoint path.
A tag-scoped URL uses the same metadata document as the endpoint it extends.
The access token the agent presents must carry the mcp_gateway scope.
A JWT without it is rejected with 403 missing required mcp_gateway scope, while a missing or unreadable token gets a 401 whose WWW-Authenticate header points at the metadata URL for the endpoint that was called and repeats the required scopes.
Those two responses are the first thing to check when an agent won't connect.
Agents that can't run the browser flow are custom agents: create one from the Custom agent button in the Agent Catalog or Quickstart (Custom agent), choosing one of two credential types. A client that can self-register needs neither: it performs its own Dynamic Client Registration on first connect, exactly as a catalog agent does.
Custom agent credential types
- API key – the gateway mints an opaque bearer token, shown once, that you configure in the agent as a static header credential. Pick this for any client that just needs a token to send with every request.
- OAuth – for agents that authenticate over OAuth 2.0 (
authorization_code) but can't self-register via Dynamic Client Registration and instead ask you to hand-paste an authorization URL, token URL, client ID, and client secret into their own settings. Pick this when the agent's own setup screen asks for those fields.
API key
The gateway stores only a hash of the token and resolves each call to that instance and its user. Treat the token like a password: it's shown once and can't be retrieved later.
OAuth
When you choose OAuth, the gateway performs Dynamic Client Registration (RFC 7591) against your organization's own issuer on the agent's behalf. You don't register anything with the issuer yourself. The result is shown once, so copy it immediately:
- Client ID and Client Secret – the registered OAuth client's credentials. The secret is never stored by the gateway and can't be retrieved later.
- Authorization URL and Token URL – the issuer's endpoints for the agent's OAuth flow.
- Scopes – defaults to
mcp_gateway profile email; leave it unless the agent needs something different. - Redirect URI – the value you supplied when creating the instance (the agent's own fixed OAuth callback).
- MCP Server URL – the gateway endpoint to paste into the agent (see Gateway MCP endpoints above).
- Auth Method – the token-endpoint authentication method the issuer assigned (
client_secret_basicorclient_secret_post); set it in the agent if it asks how to send the client secret.
Once created, the agent authenticates through this client using the same OAuth flow described above. The gateway matches incoming JWTs to the instance by client ID, with no further setup on the gateway side. Deleting the instance also removes the registered client at the issuer.
Revoking access
Revoke access on an agent instance cuts off any JWT-based access: the gateway records the revocation time and rejects any JWT issued before it, so the agent must reauthenticate to get back in. This covers both agents registered through the browser flow and custom OAuth agents, since both present a JWT. A custom agent holding a static API key has no JWT to revoke and is cut off by deleting the instance instead, which invalidates the stored token hash.
Revoke access appears on an instance only when the instance authenticates with a JWT and your deployment supplies revocation. Where the button is absent, delete the instance instead.
DPoP-bound tokens
Demonstrating Proof of Possession (DPoP, RFC 9449) stops a stolen access token from working without its client key.
The gateway accepts tokens bound to a client key this way.
A bound token carries the key's thumbprint in its cnf.jkt claim.
Send a bound token with the DPoP scheme: Authorization: DPoP <token>.
Add a DPoP header to every request.
The header holds a new proof signed with that key.
The gateway accepts only ES256 proofs.
The protected-resource metadata lists that algorithm in dpop_signing_alg_values_supported.
In the proof's JWT header, set typ to dpop+jwt.
Put the public key in jwk.
Set these claims in each proof:
htm: the request method.htu: the endpoint URL you called, without the query string.ath: the SHA-256 hash of the access token, base64url-encoded.jti: a value you haven't used in a proof before.iat: a time within 5 minutes of now.
The gateway rejects a bound token sent with the Bearer scheme.
It also rejects the DPoP scheme on a token that isn't bound.
Both get a 401.
The WWW-Authenticate header adds a DPoP challenge with error="invalid_token".
A missing or invalid proof gets error="invalid_dpop_proof".
Other refusals of a token sent with the DPoP scheme also carry a DPoP challenge.
An expired or revoked token gets error="invalid_token".
A token missing a required scope gets a 403 with error="insufficient_scope".
Tokens that aren't bound keep working with the Bearer scheme.
Calling the management API
Everything above authenticates an agent to the gateway's MCP endpoints. A third credential serves a different purpose: calling the management API from your own code. That API configures and reads back policies, resources, agents, and audit data. Here's how to tell the three apart:
- Agent OAuth/JWT identity.
The token an agent presents at
/gateway/mcp, obtained through the browser sign-in flow or a custom OAuth client, tied to the user who authorized it. It works only at the gateway: the management API rejects it with401. - Custom agent API key.
A static bearer token scoped to one agent instance, also presented at
/gateway/mcp, that the gateway resolves to that instance and its user. - Management API key.
A bearer token you create for your own application, unrelated to any agent instance, that calls the management API at
/api/v1/*instead of the MCP endpoints. See API authentication.
After the agent signs in
Agent authentication proves which agent is calling and for whom. The gateway then signs in to each MCP server separately: with each person's own account, through your SSO, or with a shared credential. See MCP server authentication overview.
Next steps
- Connect an agent – register your first agent instance.
- Credential modes – choose the OAuth app behind a resource.
- Connections – how per-user upstream authentication works day to day.