- User Authentication: Authenticate specific users through the AI Gateway using the Authorization Code flow with refresh tokens
- Machine-to-Machine Authentication: Enable programmatic access without user interaction using the Client Credentials grant flow
Guide to creating the MCP server and adding Oauth
Write a basic MCP Server and test it locally
get_me tool.http://localhost:8000/mcp. Test the server using this Python script:Create an Okta Authorization Server
Create an Okta App
Instructions to create the Okta app
Instructions to create the Okta app
- Navigate to Applications > Applications in the Okta dashboard
- Click Create App Integration
- Select OIDC - OpenID Connect
- Select Web Application as the application type

- Configure the application:
- App integration name:
CalculatorMCPClient - Grant type: Check:
- Client Credentials (required for machine-to-machine authentication)
- Authorization Code (required for user authentication via Gateway)
- Refresh Token (required to enable automatic token refresh)
- Sign-in redirect URIs: Add
https://<your-tfy-control-plane-url>/api/svc/v1/llm-gateway/mcp-servers/oauth2/callback
- App integration name:

- Click Save
- Note the Client ID and Client Secret from the application page

Assign the Okta App to the Authorization Server
Instructions to create the access policy and rule
Instructions to create the access policy and rule
- In your Authorization Server, go to the Access Policies tab.

- Click Add New Access Policy
- Configure:
- Name:
CalculatorMCPAccessPolicy - Description: Policy for MCP server access
- Assign to: Select your OAuth application
- Name:

- Click Create Policy
- Click Add Rule to create a default rule:
- Rule Name:
Default Rule - Grant type is: Check Authorization Code and Device Authorization and Client Credentials
- User is: Any user assigned the app
- Scopes requested: Any scopes
- Access token lifetime: 1 hour (or as per your requirements)
- Rule Name:
- Click Create Rule

Collect Necessary Information
https://dev-12345678.okta.com/oauth2/aus123abc), you can access the well-known URL:OAUTH_WELL_KNOWN_URL: {OAUTH_ISSUER}/.well-known/oauth-authorization-server
- OAUTH_AUDIENCE: The audience value you configured in the authorization server (e.g.,
calculator-mcp-server.example.com) - CLIENT_ID and CLIENT_SECRET: From your user-facing OAuth application (for TrueFoundry MCPGateway integration)
Modify MCP server code to add Oauth Token verification
Get the token and call the MCP server in test.py (Machine-to-Machine authentication)
OAUTH_WELL_KNOWN_URL enables the MCP server to expose the /.well-known/oauth-authorization-server endpoint, which allows the AI Gateway to auto-discover OAuth configuration details. This endpoint redirects to your Okta authorization server’s well-known endpoint.- Using cURL
- Using Python
- Using Python with requests-oauthlib
audience parameter matching the audience configured in your authorization server.Host the MCP server and get the endpoint URL
https://calculator-oauth-mcp-server.example.com for the rest of the steps.
After deploying, check once using the test.py script above by changing the MCP server URL to the deployed URL. You should be able to fetch the tools from the MCP server.Add the MCP server to the TrueFoundry AI Gateway
- In your MCP Server Group, click Add MCP Server
- Select Remote MCP
-
Configure the server:
- Name:
oauth-mcp-server - Description: OAuth-authenticated MCP server with Okta
- URL: Your deployed service endpoint (e.g.,
https://calculator-oauth-mcp-server.example.com/mcp). - Transport:
streamable-http - Authentication Type: Select OAuth2
- Name:
-
In the OAuth2 configuration section, provide the Okta credentials:
- OAuth2 Client ID: Your Okta application client ID
- OAuth2 Client Secret: Your Okta application client secret
/.well-known/oauth-authorization-server endpoint once you provide the MCP server URL.You can optionally configure:- OAuth2 Scopes: The scopes are prefilled, but you can change them if needed to use your custom scopes.
- Include
offline_accessin the scopes to enable refresh tokens. This allows the AI Gateway to automatically refresh expired access tokens without requiring users to re-authenticate. - You can store the client id and secrets in truefoundry secrets and reference them by FQN in the configuration.
- Set access control: Select teams or users who should have access to this MCP server.

- Click Save to add the MCP server
- The server will appear in your MCP Server Group
- Users can now connect and use the server through the AI Gateway
Test the MCP server in the Playground
- Navigate to the Playground in the AI Gateway.
- Click Add Tool/MCP Servers
- Find your
calculator-oauth-mcp-serverin the list - Click Connect Now to initiate OAuth authorization

- You’ll be redirected to Okta to authorize access
- Click Allow to grant access
- You’ll be redirected back to the AI Gateway
- The AI Gateway will store your OAuth tokens securely and refresh them automatically when they expire
- You’ll see the
addandsubtracttools from your MCP server - Select the tools and click Done
- Try sending a prompt like
Add 1 and 2. Use the tools provided - The tool will return the result from your MCP server

Okta setup for On-Behalf-Of (OBO) token exchange
This runbook covers the Okta admin console setup for the OAuth2 Token Exchange (OBO) outbound grant type, where the AI Gateway exchanges each caller’s Okta SSO access token for a fresh On-Behalf-Of token before calling the MCP server. For the gateway-side configuration (manifests, caller contract, troubleshooting), see the Okta OBO Token Exchange scenario in Authentication and Security. Okta’s own guide: Set up token exchange. You need two custom authorization servers, a native app for user sign-in, and an API Services app that performs the exchange.Create two authorization servers
- A user authorization server — issues the SSO access tokens your users sign in with. Set its Audience (e.g.
user). - A service authorization server — performs the token exchange and issues the OBO tokens. Set its Audience (e.g.
service). This audience becomes theaudclaim of the exchanged token and theaudiencevalue in the MCP server manifest.
subject_token.Create a native app for user sign-in
- Select OIDC - OpenID Connect, then Native Application.
- Name the app and select Allow everyone in your organization to access.
- Save, and note the Client ID — this is the value you will map on the TrueFoundry Virtual Account, because it appears as the
cidclaim in every user access token.
Create an API Services app for the exchange
- Select API Services.
- Name the app (e.g.
mcp-obo-service), then save. - In General Settings, click Edit and uncheck “Require Demonstrating Proof of Possession (DPoP) header in token requests” — the AI Gateway authenticates with a client secret, not DPoP.
- In the Grant type section, expand Advanced and enable Token Exchange. Save.
- Note the Client ID and Client Secret — these go into the MCP server manifest’s
auth_data.
Add custom scopes
api:access:read, api:access:write). These are the scopes the gateway requests in the exchange and are minted into the OBO token’s scp claim.Create access policies and rules
- Go to Access Policies and add a policy assigned to the native app (Assign to > The following clients).
- Add a rule allowing the scopes users sign in with (e.g.
openid) under Scopes requested > The following scopes.
- Add a policy assigned to the API Services app.
- Add a rule that allows the API scopes (
api:access:read,api:access:write) and, under Grant type is > Advanced, enables Token Exchange.
Verify the exchange manually
This is the RFC 8693 request the AI Gateway performs against the service authorization server on your behalf — useful for validating the Okta setup and debugging a failing exchange:client_secret_post, shown above) or as an Authorization: Basic base64(client_id:client_secret) header (client_secret_basic). Both work — but use one method or the other, never both in the same request.FAQ
What is Machine to Machine Authentication?
What is Machine to Machine Authentication?
Which Okta app to create if I only want Machine to Machine authentication?
Which Okta app to create if I only want Machine to Machine authentication?
openid, profile, and email won’t work for API Service Integrations. For detailed instructions on implementing M2M authentication using the Client Credentials grant type, see the Okta documentation.How can different services access the MCP server with different scopes?
How can different services access the MCP server with different scopes?
- One App Per Service: Each service accessing the MCP server has its own API Service Integration app, providing isolation and granular access control
- Shared MCP Server: Multiple services can access the same MCP server, but each uses different Okta apps with different scopes
- Custom Authorization Server: All apps use the same custom authorization server (not the Org Authorization Server, which is only for Okta APIs)
How to get an access token from Okta for Machine-to-Machine authentication?
How to get an access token from Okta for Machine-to-Machine authentication?
{OAUTH_ISSUER}/.well-known/oauth-authorization-server. The response includes the token_endpoint:token_endpoint value from this response in your token requests.How to access the the token details and user identity in the tool in MCP server?
How to access the the token details and user identity in the tool in MCP server?
How to refresh tokens in client for Machine to Machine authentication?
How to refresh tokens in client for Machine to Machine authentication?
TokenManager class that handles automatic token renewal (adapt the token endpoint URL and parameters to match your OAuth provider):
