Secure MCP tools with OAuth2 and Okta

This is a Konnect tutorial and requires a Konnect personal access token.

1. Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.

2. Export your token to an environment variable:

    export KONNECT_TOKEN='YOUR_KONNECT_PAT'
   

   Copied!

3. Run the quickstart script to automatically provision a Control Plane and Data Plane, and configure your environment:

    curl -Ls https://get.konghq.com/quickstart | bash -s -- -k $KONNECT_TOKEN --deck-output
   

   Copied!

   This sets up a Konnect Control Plane named quickstart, provisions a local Data Plane, and prints out the following environment variable exports:

    export DECK_KONNECT_TOKEN=$KONNECT_TOKEN
    export DECK_KONNECT_CONTROL_PLANE_NAME=quickstart
    export KONNECT_CONTROL_PLANE_URL=https://us.api.konghq.com
    export KONNECT_PROXY_URL='http://localhost:8000'
   

   Copied!

   Copy and paste these into your terminal to configure your session.

This tutorial requires Kong Gateway Enterprise. If you don’t have Kong Gateway set up yet, you can use the quickstart script with an enterprise license to get an instance of Kong Gateway running almost instantly.

1. Export your license to an environment variable:

    export KONG_LICENSE_DATA='LICENSE-CONTENTS-GO-HERE'
   

   Copied!

2. Run the quickstart script:

   curl -Ls https://get.konghq.com/quickstart | bash -s -- -e KONG_LICENSE_DATA 
   

   Copied!

   Once Kong Gateway is ready, you will see the following message:

    Kong Gateway Ready
   

decK is a CLI tool for managing Kong Gateway declaratively with state files. To complete this tutorial, install decK version 1.43 or later.

This guide uses deck gateway apply, which directly applies entity configuration to your Gateway instance. We recommend upgrading your decK installation to take advantage of this tool.

You can check your current decK version with deck version.

For this tutorial, you’ll need Kong Gateway entities, like Gateway Services and Routes, pre-configured. These entities are essential for Kong Gateway to function but installing them isn’t the focus of this guide. Follow these steps to pre-configure them:

1. Run the following command:

   echo '
   _format_version: "3.0"
   services:
     - name: weather-api-service
       url: https://api.weatherapi.com/v1
   routes:
     - name: weather-api-route
       paths:
       - "/api/weather"
       service:
         name: weather-api-service
       protocols:
       - http
       - https
     - name: weather-mcp
       paths:
       - "/weather/mcp"
       - "/.well-known/oauth-protected-resource/weather/mcp"
       service:
         name: weather-api-service
       protocols:
       - http
       - https
   ' | deck gateway apply -
   

   Copied!

To learn more about entities, you can read our entities documentation.

1. Go to WeatherAPI.
2. Sign up for a free account.
3. Navigate to your dashboard and copy your API key.

4. Export your API key:

    export DECK_WEATHERAPI_API_KEY='your-weatherapi-api-key'
   

   Copied!

You need an Okta admin account with a developer organization.

Complete the following steps to configure Okta for MCP OAuth2 authentication. This setup creates two application registrations: a Web Application (used by AI Gateway for token introspection) and a Native Application (used by MCP Inspector for the authorization code flow).

Add a custom scope

1. Go to Security > API > Authorization Servers.
2. Click default.
3. Go to the Scopes tab.
4. Click Add Scope.
5. Name: mcp:access
6. Display phrase: Access MCP tools
7. Check Set as a default scope.
8. Click Create.

Add an access policy

1. In the same default authorization server, go to the Access Policies tab.
2. Click Add Policy.
3. Name: MCP Access
4. Assign to: All clients
5. Click Create Policy.

Add a rule to the policy

1. Inside the MCP Access policy, click Add Rule.
2. Rule Name: Allow MCP
3. Grant type: check Client Credentials, Authorization Code, and Device Authorization.
4. User is: Any user assigned the app
5. Scopes requested: Any scopes
6. Click Create Rule.

Export your Okta authorization server URL and introspection endpoint. To find these values:

1. Go to Security > API > Authorization Servers.
2. Click the default server.
3. Copy the Issuer URI (for example, https://your-org.okta.com/oauth2/default). This is the authorization server URL.
4. Append /v1/introspect to the Issuer URI to get the introspection endpoint.

export DECK_OKTA_AUTH_SERVER='https://your-org.okta.com/oauth2/default'
export DECK_OKTA_INTROSPECTION_ENDPOINT='https://your-org.okta.com/oauth2/default/v1/introspect'

Create the web application (used by AI Gateway for introspection)

1. Go to Applications > Applications > Create App Integration.
2. Sign-in method: OIDC - OpenID Connect
3. Application type: Web Application
4. App integration name: Kong MCP Gateway
5. Grant types: check Client Credentials and Authorization Code.
6. Set Sign-in redirect URIs to any valid URL (for example, http://localhost/unused). Kong does not use the redirect flow for this app, but Okta requires the field.
7. Assignments: Skip group assignment for now
8. Click Save.
9. Copy the Client ID and Client Secret. These go into the AI Gateway ai-mcp-oauth2 plugin config.
10. Go to the Assignments tab, click Assign > Assign to People, and assign your user.

11. Export the credentials:

     export DECK_OKTA_CLIENT_ID='your-kong-web-app-client-id'
     export DECK_OKTA_CLIENT_SECRET='your-kong-web-app-client-secret'
    

    Copied!

Create the native application (used by MCP Inspector)

1. Go to Applications > Applications > Create App Integration.
2. Sign-in method: OIDC - OpenID Connect
3. Application type: Native Application
4. App integration name: MCP Inspector
5. Grant types: check Authorization Code.
6. Sign-in redirect URIs: http://localhost:6274/oauth/callback/debug
7. Assignments: Skip group assignment for now
8. Click Save.
9. Go to the Assignments tab, click Assign > Assign to People, and assign your user.
10. Copy the Client ID. This is the Client ID you enter in MCP Inspector. No secret is needed for this public client.

The two applications serve different purposes. The Web Application Client ID and Client Secret go into the AI Gateway ai-mcp-oauth2 Plugin config for token introspection. The Native Application Client ID is what you enter in MCP Inspector when connecting to the OAuth-protected MCP endpoint.

This guide uses the MCP Inspector to test the OAuth-protected MCP endpoint.

1. Ensure you have Node.js and npm installed. If needed, download them from https://nodejs.org.

2. Update npx to the latest version:

    npm install -g npx
   

   Copied!
3. Install the Inspector:

    npm install -g @modelcontextprotocol/inspector
   

   Copied!