Use WorkOS Connect token exchange to swap the user's MCP token for one scoped to your API, then check the claims your API needs to trust it.
An MCP server should call your API on the user's behalf by exchanging the user's access token for a new token issued for your API, using OAuth 2.0 token exchange (RFC 8693). With WorkOS Connect, the MCP server sends the user's token to the token endpoint and names your API as the resource. It gets back a token for the same user and organization, with your API as the audience and an act claim that names the MCP server.
This post walks through the setup, the exchange request, what changes in the token, what your API should check, and the errors you will run into. For why every hop in an agent chain should get its own token, see Why agent-to-agent chains need per-hop delegated tokens.
Sequence diagram of WorkOS Connect token exchange between an MCP client, your MCP server, WorkOS and your API
Why can't the MCP server forward the user's token to your API? #
An MCP server can't forward the user's token to your API because WorkOS issues that token for the MCP server, so its aud claim is the MCP server's URL and your API should reject it. When an MCP client such as Claude or Cursor connects through WorkOS Connect, it requests a token with your MCP server's URL as the resource, and that value becomes the token's audience.
Accepting the token anyway would mean your API trusts tokens issued for a different service. The MCP specification forbids this pattern, called token passthrough, because it removes the audience check that keeps one service's tokens from working at another. Token exchange keeps the check: your API only accepts tokens issued for your API.
What do you need before your MCP server can exchange tokens? #
To exchange tokens with WorkOS Connect, your MCP server needs its own first-party Connect application with a client secret, and both your MCP server and your API need to be registered as Resource Indicators.
- A first-party Connect application for the MCP server. The exchange is done by your MCP server, not by the MCP client. MCP clients usually connect as public or dynamically registered clients, and those can't use the token exchange grant. Your MCP server authenticates with its own
client_idandclient_secret, so keep the secret on the server. - Resource Indicators for both services. Add your MCP server's URL (for example
https://mcp.example.com) and your API's URL (for examplehttps://api.example.com) asResource Indicators in the WorkOS Dashboard. The API's URL is what the MCP server passes asresourcein the exchange. - Token exchange enabled for the environment. If the token endpoint answers with
unsupported_grant_type, token exchange isn't enabled for your environment.
How does the MCP server exchange the user's token? #
The MCP server exchanges the user's token by calling the WorkOS Connect token endpoint, POST /oauth2/token, with the token exchange grant type, the user's token as subject_token, and your API's URL as resource. The token exchange grant reference lists every parameter.
userToken is the bearer token the MCP client sent with the tool call, after your MCP server has verified it as described in the MCP guide. The subject_token must be an access token issued by the same WorkOS environment through the authorization code, refresh token or token exchange grant. Client credentials (M2M) tokens can't be exchanged.
The response contains only an access token. WorkOS doesn't return a refresh token or ID token, and the exchanged token expires no later than the user's token. When it expires, the MCP server exchanges the user's current token again.
How do you give the API token fewer permissions than the user's token? #
To give the API token fewer permissions, pass a scope parameter with only the scopes the call needs. Token exchange in WorkOS Connect can narrow scopes but never widen them. Scopes that the user's token doesn't carry are dropped, and if none of the requested scopes remain, the request fails with invalid_scope. If you leave scope out, the new token gets the same scopes as the user's token.
Request scopes per operation rather than per server. A tool that only reads invoices should exchange for invoices:read, even if the user granted the MCP client more.
What changes between the user's token and the exchanged token? #
The exchanged token keeps who the user is and changes who the token is for. WorkOS Connect copies sub, sid, client_id and org_id from the user's token, sets aud to the requested resource, and adds an act claim whose sub is the client ID of the app that did the exchange.
Two details matter when you read these claims. First, client_id still names the MCP client the user consented to, so use act.sub to see which app is calling your API. Second, if a token that was already exchanged is exchanged again by a different app, the earlier actor is nested inside the new act claim, so the outermost act.sub is always the app currently calling. An app that exchanges its own exchanged token again doesn't add another level.
The exchange doesn't change the user's consent record. If the user's authorization for the MCP client is removed, later exchanges fail with invalid_grant.
What should your API check in the exchanged token? #
Your API should verify the exchanged token like any WorkOS Connect access token: check the signature against the JWKS endpoint, check that iss is your AuthKit domain and that aud is your API's own URL, then check act and scope before acting. The token claims reference describes each claim.
The audience check is what makes token exchange worth doing. Without it, your API would also accept the MCP server's tokens and any other token from the same environment.
The act check lets your API decide which apps may act for users. A token without act was issued directly for your API, for example to your own web app, so this sample allows it. If your API should only ever be called through the MCP server, reject tokens without act instead.
You can also use act.sub in logs and audit trails, so a request shows both the user and the app that made it on their behalf.
Can your MCP server check whether a user's token is still active? #
Yes. Your MCP server can check whether a user's token is still active by calling the WorkOS Connect token introspection endpoint with its first-party application credentials. Verifying a JWT happens offline, so a verified token stays valid until it expires even if the user's access was removed in the meantime. Introspection asks WorkOS for the current state.
Any app can introspect tokens issued to itself. A first-party app can also introspect access tokens issued to public clients in the same environment, such as MCP clients registered through Client ID Metadata Documents (CIMD) or Dynamic Client Registration (DCR) without a secret. For any other token, including tokens issued to clients with a secret, the response is {"active": false}. In an active response, client_id names the app the token was issued to, not the app that asked.
Introspection doesn't check aud for you. If you use it, still check that aud matches the service you expect. The introspection response also doesn't include the act claim, so read the actor from the verified JWT.
Which errors can token exchange return, and what do they mean? #
The WorkOS Connect token endpoint returns standard OAuth error codes for a failed exchange. Most come from the app type, the resource value or the state of the user's token.
Secure your MCP server with WorkOS Connect #
WorkOS Connect covers every step in this post out of the box, so you never build or run an authorization server for your MCP server. It registers MCP clients like Claude and Cursor through both CIMD and DCR, runs the user's sign-in and consent, issues tokens bound to each Resource Indicator, and exchanges them for tokens your API accepts, with the user, the organization and the acting app already in the claims.
The parts that are easy to get wrong are enforced by WorkOS, not by code you maintain: each token is bound to one audience, exchanged tokens can only lose scopes and never outlive the original, and every app that exchanges a token is recorded in act. Your team writes the tools and the checks in your API.
Start with the MCP guide to protect your server. When your first tool needs to call your API, the token exchange grant reference has every parameter and error.