Updated August 6, 2026Blog

How to Add Okta Authentication and Tool-Level Authorization to an MCP Server

Table of contents

MCP servers can expose databases, APIs, SaaS applications, and operational tools to AI agents. Okta authenticates the user, application, or workload and issues an OAuth access token. Datawiza Agent Gateway then uses that identity context, including scopes, groups, and custom claims, to enforce which MCP servers, tools, actions, and downstream resources the caller may access.

This guide shows how to protect an existing self-hosted HTTP-based MCP server with Okta and Datawiza Agent Gateway. The gateway sits in front of the MCP server, automatically publishes OAuth Protected Resource Metadata, validates Okta-issued access tokens, applies server-, tool-, and action-level policy, and forwards only approved requests. The backend MCP server stays focused on tools and business logic instead of implementing OAuth discovery, token validation, and authorization in every service.

What this guide shows

Choose the correct Okta authorization server for a protected MCP resource.
Connect interactive MCP clients with authorization code and PKCE, or connect unattended agents with an appropriate workload identity flow.
Automatically publish OAuth Protected Resource Metadata so compatible MCP clients can discover Okta as the authorization server.
Validate Okta access tokens before requests reach the MCP server.
Enforce least-privilege access by MCP server, tool, action, user, group, application, workload, and environment.
Keep the backend MCP server private and record allowed and denied decisions.

What you will build

You will place Datawiza Agent Gateway in front of an HTTP-based MCP server. The client connects to a trusted HTTPS endpoint on the gateway, while the backend MCP server remains reachable only through the private network path.

Okta authenticates the user, application, workload, or agent and issues an OAuth access token from the expected custom authorization server.
Datawiza publishes protected resource metadata and returns the OAuth discovery challenge required by compatible MCP clients.
Datawiza validates the token signature, issuer, audience, lifetime, scopes, groups, and relevant custom claims.
Datawiza evaluates MCP server-, tool-, and action-level policy before forwarding the request.
The private MCP server receives only approved traffic and continues to run its existing tools.
Allowed and denied requests are recorded with identity and policy context.

Okta OAuth architecture for MCP servers

Okta OAuth authentication and MCP tool-level authorization through Datawiza Agent Gateway

For an interactive MCP client, Okta uses the OAuth 2.0 authorization-code flow with PKCE. That flow satisfies the applicable OAuth 2.1 security requirements used by MCP. The client receives an access token for the protected MCP resource and presents it to the Datawiza endpoint with each MCP request.

Autonomous agents use the same enforcement point but may obtain tokens differently. An unattended workload can use client credentials and a tightly scoped service application. An agent acting for a signed-in user can use a delegated or token-exchange design when downstream operations must preserve user context. In every case, the resulting bearer token is presented to Datawiza for validation and least-privilege policy enforcement.

The MCP client, user, application, or agent obtains an access token from Okta.
The client sends the MCP request and bearer access token to the Datawiza-protected endpoint.
Datawiza validates token integrity, issuer, audience, expiration, scopes, groups, and relevant claims.
Policy decides which MCP server, tool, action, data path, and environment the identity may reach.
Only approved requests reach the backend MCP server, and the decision is logged.

Why put an identity-aware agent gateway in front of your MCP server?

Okta can authenticate a user, application, workload, or agent and issue an access token. The protected endpoint must still validate that token, map Okta identity claims to MCP permissions, enforce the decision, and record the activity. Rebuilding those controls in every MCP server produces duplicated security logic and inconsistent policy.

Datawiza Agent Gateway centralizes that enforcement in front of existing MCP servers. Identity and security teams get one policy point, while MCP developers keep their services focused on tools and business logic.

Protect existing HTTP-based MCP servers without adding OAuth discovery or token-validation libraries to each server.
Automatically provide OAuth Protected Resource Metadata and direct compatible clients to the configured Okta authorization server.
Apply consistent issuer, audience, signature, expiration, scope, group, client, and custom-claim checks.
Enforce least-privilege server-, tool-, and action-level policy beyond broad OAuth scopes.
Keep backend MCP servers private while exposing one controlled HTTPS endpoint to approved clients.
Record the user, client, workload or agent, tool call, matched policy, and outcome in one audit trail.

Prerequisites

An Okta organization.
An Okta production plan with API Access Management if you need a custom authorization server for your own MCP APIs and resources.
Permission to create or configure an authorization server, OIDC applications, scopes, claims, access policies, and rules.
An existing HTTP-based MCP server reachable from the gateway over an internal network path.
A public HTTPS hostname and trusted certificate for the protected MCP endpoint.
A Datawiza Agent Gateway deployment in your cloud, private network, on-premises environment, or Datawiza-hosted service.
An MCP client or agent workflow that can use the selected OAuth client registration and token flow.

Step 1: Choose the right Okta authorization server

This is the most important Okta-specific decision. Every Okta org has an org authorization server, but its access tokens are intended for Okta APIs. Okta states that those tokens are not intended for validation or use by your own applications and resource servers.

To protect your own MCP server, use an Okta custom authorization server. A custom authorization server lets you define the audience, scopes, claims, access policies, and rules for your MCP resource. In production, this capability requires Okta API Access Management.

Configure the MCP resource

Choose the custom authorization-server issuer, such as https://your-okta-domain/oauth2/default or the issuer for a dedicated server.
Set an audience that uniquely identifies the protected MCP resource and configure Datawiza to expect the same value.
Create a narrow scope such as mcp.access and add more specific scopes only when they represent meaningful resource permissions.
Add only the groups and custom claims required for policy. Avoid placing an organization's entire directory context into every token.
Create an access policy and rule that permits only the intended clients, users, groups, and grant types.

Configuration reference

Issuer: the exact custom authorization-server issuer trusted by the gateway.
Audience: the identifier for the protected MCP resource, matched against the access token aud claim.
Scopes: delegated or application permissions such as mcp.access, with narrower scopes where useful.
Claims: controlled groups and custom attributes used for MCP policy.
Protected MCP URL: the public HTTPS endpoint used by the client.
Backend MCP URL: the private endpoint reached only through Datawiza.
Redirect URI: the exact client-specific callback registered in Okta for interactive clients.

Step 2: Register the MCP client or agent

Create an Okta OIDC application for the MCP client or workload. Register only the redirect URIs and grant types the use case requires, assign only the intended users or groups, and grant access to the MCP scopes exposed by the custom authorization server.

Choose the identity pattern

Signed-in user: use authorization code with PKCE. The access token represents delegated access by a user through the client.
Unattended agent or workload: use a service application and client credentials with narrowly assigned scopes.
Agent acting for a signed-in user: use a delegated or token-exchange design when downstream actions must preserve user context.

Interactive clients such as ChatGPT, Claude, Visual Studio Code, and Cursor can have different callback URLs, client-registration expectations, and connection settings. Register the exact callback produced by the client and verify its current OAuth behavior rather than copying settings from another client.

Step 3: Put Datawiza Agent Gateway in front of the MCP server

Configure the gateway's public service with the protected MCP hostname and point its backend to the existing private MCP server. The client connects only to the Datawiza endpoint; the backend MCP server does not need to be directly reachable from the internet.

Configure Okta access-token authentication with the exact custom authorization-server issuer and audience. Datawiza validates the token on every request before the backend sees it. Use a trusted TLS certificate because hosted MCP clients commonly reject self-signed certificates.

How the MCP client learns about Okta

Datawiza Agent Gateway automatically publishes OAuth Protected Resource Metadata for the protected MCP endpoint. When an unauthenticated compatible client connects, the gateway returns 401 Unauthorized and uses the WWW-Authenticate challenge to point the client to the resource metadata. That metadata identifies Okta as the authorization server and supplies the protected-resource information required to begin the OAuth flow.

The backend MCP server does not need to implement this discovery behavior. Protected-resource discovery and client registration are separate concerns, so pre-register each supported client in Okta unless your chosen client and authorization-server design explicitly support another registration mechanism.

Step 4: Connect the MCP client

Configure the MCP client with the Datawiza-protected URL, not the internal server URL. For an interactive client, the user completes the Okta authorization flow and the client attaches the resulting bearer access token to subsequent MCP requests. For an unattended agent, configure the approved workload token flow instead of borrowing a human user's token.

The MCP authorization specification requires compatible remote clients to discover the authorization server through Protected Resource Metadata, use PKCE for authorization-code protection, and present access tokens through the Authorization header. Client behavior continues to evolve, so validate the exact client and protocol version in your deployment.

Step 5: Add MCP server-, tool-, and action-level authorization

A valid Okta access token establishes trusted identity context. It does not grant blanket permission to every tool. Datawiza can evaluate issuer, audience, scopes, groups, custom claims, user, client, workload, agent context, target server, tool, action, and environment before allowing the request.

Practical least-privilege example

Suppose an Okta group named MCP-Finance-Readers needs invoice visibility but must not initiate or alter payments. After token validation, Datawiza can apply policy that allows read tools and denies sensitive write tools:

Allow list_invoices.
Allow get_invoice.
Allow search_vendors.
Deny create_payment.
Deny update_bank_account.
Deny delete_vendor.

Authentication confirms who or what is calling. Tool-level authorization determines what that identity may do after authentication succeeds.

Map stable Okta claims to policy

Validate iss and aud first, then use stable subject, client, scope, group, and controlled custom-claim values for authorization. Treat names and email addresses as display attributes rather than primary authorization keys. Filter group claims to the groups that matter for MCP policy so tokens remain focused and predictable.

For a broader policy model, see MCP access control.

What Datawiza removes from the MCP server

Without a shared enforcement layer, every MCP server team may need to implement and maintain the same identity controls. Datawiza centralizes:

OAuth Protected Resource Metadata, Okta discovery, and access-token validation.
Signature, issuer, audience, lifetime, scope, group, client, and custom-claim checks.
User, client, workload, and agent identity mapping.
MCP server-, tool-, and action-level policy enforcement.
Allowed- and denied-request logging with policy context.

The backend MCP server generally does not need to implement enterprise OAuth or Okta token validation. Network, DNS, TLS, routing, client registration, authorization-server configuration, and the business policy model still need to be configured.

Step 6: Test authentication, authorization, and audit

Test failure paths as deliberately as the successful connection:

Call the protected endpoint without a token and confirm it returns 401 Unauthorized with a WWW-Authenticate challenge pointing to valid protected resource metadata.
Reject an expired token, an ID token, an org authorization-server token, and an access token issued for another audience.
Allow a read-only Okta identity to call an approved read tool.
Return 403 Forbidden when that valid identity calls a denied write or administrative tool.
Verify that caller context, MCP server, tool, matched policy, decision, and outcome appear in the audit trail.

Use 401 when authentication is missing or invalid. Use 403 when authentication is valid but the identity lacks permission for the requested operation.

Common Okta MCP authentication problems

The token came from the org authorization server

Symptom: sign-in succeeds, but the token is unsuitable for your MCP resource. Use a custom authorization server for your own APIs and MCP servers. Configure its audience, scopes, claims, access policy, and rule, then align the gateway issuer and audience with the resulting access token.

The client cannot discover the protected resource metadata

Symptom: the client reaches the MCP endpoint but does not begin the Okta authorization flow. Confirm that the public endpoint returns the expected 401 challenge, its metadata URL is reachable over trusted HTTPS, and the metadata identifies the correct Okta custom authorization server and MCP resource.

The client sends an ID token

Symptom: user sign-in succeeds but the MCP request is rejected. An ID token tells the client that a user authenticated; it is not an access token for the MCP resource. Confirm that the bearer token has the expected custom authorization-server issuer, audience, and scopes.

The access-token audience does not match

Symptom: a correctly signed token still receives 401. Inspect the access token aud claim, the custom authorization-server audience, the requested resource or scope, and the audience configured in Datawiza. They must describe the same protected MCP resource.

The custom authorization server has no matching access policy

Symptom: Okta refuses token issuance even though the client and scope exist. Confirm that the custom authorization server has an access policy and rule covering the client, user or workload, grant type, and requested scopes. New test organizations can require this setup on the default custom authorization server.

Groups or custom claims are missing

Symptom: authentication succeeds, but group-based policy never matches. Confirm that the claim is configured for access tokens from the custom authorization server, that its filter includes the expected group, and that the relevant flow actually emits the claim.

The redirect URI is rejected

Symptom: Okta returns a redirect mismatch during sign-in. Register the exact callback produced by the MCP client and use the correct Okta application type. Different clients can require different callback patterns.

Authentication succeeds, but authorization is too broad

Symptom: any valid Okta identity can call every MCP tool. Add explicit server-, tool-, action-, environment-, group-, user-, client-, workload-, and agent-level policies. A valid access token should be an input to authorization, not blanket approval.

What this architecture does and does not do

It adds Okta access-token validation in front of an HTTP-based MCP server.
It automatically publishes OAuth Protected Resource Metadata for compatible MCP clients.
It enforces identity-aware server-, tool-, and action-level policies and can keep the backend private.
It supports interactive and workload access patterns when the Okta applications, authorization server, scopes, and policies are configured for those flows.
It does not define the correct business permissions for every MCP tool; your team owns the policy model.
It does not replace downstream application authorization or automatically preserve user identity across every downstream service.
It does not apply this remote OAuth pattern to local STDIO MCP servers, which use a different credential model.

Okta MCP server FAQ

Does MCP use OAuth 2.1 or OAuth 2.0 with Okta?

The MCP authorization specification applies OAuth 2.1 security requirements. Okta documents its authorization servers as OAuth 2.0 and OpenID Connect. In this architecture, an interactive MCP client uses Okta's authorization-code flow with PKCE, receives an OAuth access token for the MCP resource, and presents it to Datawiza for validation and MCP-specific authorization.

Should we use the Okta org or custom authorization server?

Use a custom authorization server for your own MCP server or API. Okta's org authorization-server access tokens are intended for Okta APIs and are not intended for validation by your applications. Production use of custom authorization servers requires Okta API Access Management.

Can I add Okta authentication without changing my MCP server code?

Yes, for an HTTP-based MCP server that can be placed behind the gateway. Datawiza handles protected-resource discovery, Okta access-token validation, and policy enforcement before forwarding approved requests. Network, DNS, TLS, routing, Okta application registration, and authorization-server configuration still need to be completed.

Can Okta groups control MCP tool access?

Yes, when the relevant group or custom-claim information is included in the access token. Datawiza can use that context to decide which MCP servers, tools, actions, data paths, and environments a request may reach.

Does a valid Okta access token authorize every MCP tool?

No. Token validation establishes trusted identity context. Authorization must still decide which MCP server, tool, action, data path, and environment that identity may access.

Does the backend MCP server need to be public?

No. The Datawiza-protected endpoint must be reachable by the MCP client, but the backend MCP server can remain on a private network and accept traffic only from Datawiza Agent Gateway.

Next step

Start with one MCP server and a small set of read-only tools. Confirm Okta token issuance and validation, define narrow tool permissions, test denied requests, and review the audit trail before expanding to sensitive write actions or additional servers.

To review your Okta MCP architecture with an engineer, book a demo. Explore Datawiza Agent Gateway for centralized identity, least-privilege policy, credential handling, and audit across MCP and API connections.

MCP Server Authentication and Authorization for Enterprise AI Agents

MCP Gateway for enterprise AI agents

MCP Security for Enterprise AI Agents

MCP Access Control for Enterprise AI Agents

How to add Microsoft Entra ID authentication and tool-level authorization to an MCP server

Primary technical sources

Okta Developer: Authorization servers

Okta Developer: API Access Management

Okta Developer: Validate access tokens

Okta Developer: Customize tokens with a groups claim

MCP authorization specification (2025-11-25)