# Okta

## Before you begin

You’ll need:

- An Okta subscription eligible for Managed MCP Server, currently an Early Access feature.
- A super admin who can enable it in the org you want to connect.
- Permission to configure an OIDC app and grant its API scopes in that org.

Each person connects using their own Okta account.

## Guided setup (recommended)
Take the guesswork out of connecting Okta to your agents. Speakeasy guides you through the required configuration and helps you verify the connection, so you can get started with confidence.

In the MCP Catalog, find **Okta Managed MCP Server** and click **Add**. Select **User Identity** to start guided setup.

## Manual setup

### Enable Okta Managed MCP Server
1. Sign in to the target org’s Okta Admin Console.
2. Open **Settings > Features**. Enable **Core Identity** for users, groups, apps, policies, devices, and logs, or **Identity Governance** for access requests, reviews, entitlements, and resource ownership. Enable both if you need both sets of tools.
3. Record the public org URL, such as `https://example.okta.com`. Use the org host ending in `okta.com`, `oktapreview.com`, or `okta-emea.com`. Speakeasy guided setup uses these public org domains.
4. Append `/mcp` to the org URL for the MCP server URL.

If a feature is missing, confirm the subscription and org with your Okta admin. See [Okta’s guide to enabling Early Access features](https://help.okta.com/oie/en-us/content/Topics/security/manage-ea-and-beta-features.htm).

<!-- screenshot: Okta Settings > Features with the available Managed MCP Server options visible -->

### Configure an OIDC app
1. Open **Applications and resources > Applications**.
2. For a new app, click **Create App Integration**, select **OIDC - OpenID Connect**, and choose **Web Application** or **Native Application**. Web is recommended for Speakeasy. Click **Next** and enter an **App integration name**.
3. To reuse an existing Web or Native Application, open the app, select **General**, and click **Edit** in **General Settings**.
4. Select **Authorization code** under **Grant type**.
5. Add the following value under **Sign-in redirect URIs**. Keep any redirects the existing application still uses.

   ```text
   https://ai.speakeasy.com/mcp/remote_login_callback
   ```

   In guided setup, use the redirect URI displayed there.

6. Save the app. On its **General** tab, confirm **Proof Key for Code Exchange (PKCE)** is selected. Use a client secret for a Web Application. For a Native Application, use PKCE with no client secret.

<!-- screenshot: Okta app General settings with Authorization code, the redirect URI, and PKCE visible -->

### Assign users and grant scopes
1. Assign the people or groups who will use the MCP connection. For a new app, set **Assignments** during creation. For an existing app, open its **Assignments** tab and add the intended users or groups.
2. Open the **Okta API Scopes** tab. Click **Grant** for the minimum scopes required by the tools you intend to use. For example, follow Okta’s scope table to choose the read scopes for the resources you want to view. [Okta’s tool and scope reference](https://help.okta.com/mcp/en-us/content/topics/mcpserver/scope-based-tool-loading.htm).
3. Confirm that the connecting user has the underlying Okta permissions the tools require. App assignment gives a user access to sign in. API grants govern the scopes the app can request.

<!-- screenshot: Okta app Assignments and Okta API Scopes tabs, with user names redacted -->

### Copy the client credentials
On the app’s **General** tab, copy its **Client ID**. For a Web Application, also copy its **Client Secret**. A Native Application uses only the Client ID. Continue to [manual setup in Speakeasy](#add-server-in-speakeasy) or return to the guided setup to save the credentials.

<!-- screenshot: Okta app General tab showing Client Credentials, with both values redacted -->

### Add the server in Speakeasy
1. In the Speakeasy sidebar, under **MCP Gateway**, select **MCP**.
2. Click **Add new** and choose **Hosted remotely**.
3. In **MCP server URL**, enter your [Okta MCP server URL](#enable-okta-mcp), such as `https://example.okta.com/mcp`.
4. Leave **User session issuer** at its default.
5. Click **Verify connectivity**.
6. Select **User Identity**.
7. Click **Save**.
8. Open the server’s **Settings > Identity** to configure its credentials.

If you already added the server, open its **Settings > Identity** and continue below.

<!-- screenshot: New remote MCP server with the provider URL and User Identity selected -->

### Connect your credentials
1. Open the server’s **Settings > Identity** and confirm **User Identity** is selected.
2. In **Choose an authorization server**, select the issuer matching the public org URL. The issuer is the org origin, such as `https://example.okta.com`. If the correct issuer is missing, create it using the steps below.
3. Choose **Manual** and paste the [Client ID](#copy-client-credentials). For a Web Application, paste its **Client secret**. For a Native Application, leave the secret empty so Speakeasy uses public-client authentication.
4. Leave **Advanced > Scope** blank to use discovered scopes. If setting an explicit override, request only scopes granted to the app and needed by the intended tools.
5. Click **Save** and confirm if prompted.
6. In **Settings > Danger Zone > Server Availability**, turn on **Enable MCP server** and confirm it shows **Enabled**.
7. When an assigned user first uses the server, have them sign in to the intended Okta org and authorize the app.

If the correct issuer is missing:

1. Open the provider picker and click **Create a custom authorization server**, then click **New Authorization Server**.
2. Set **Issuer URL** to your public Okta org URL, such as `https://example.okta.com`, and click **Discover**. Under **Endpoints**, verify **Authorization Endpoint** is the org URL followed by `/oauth2/v1/authorize` and **Token Endpoint** is the org URL followed by `/oauth2/v1/token`. Enter those values if discovery leaves them empty.
3. Keep the derived **Slug** and click **Create**.
4. Return to the server’s **Settings > Identity**, select the new provider, and continue with **Manual** credentials in step 3.

<!-- screenshot: Settings > Identity with User Identity, Okta org issuer, and Manual credentials, with the credential values redacted -->

## Troubleshoot sign-in and tool access

- If the server is unreachable, check the org hostname, the `/mcp` path, and the enabled Okta features.
- If the user can’t sign in, confirm the app is in that same org, the connecting user is assigned, and the registered redirect URI matches Speakeasy’s callback. Verify Authorization Code and PKCE and that the credentials match the app type.
- If tools are missing or return a permissions error, confirm the relevant features, app scope grants, granted token scopes, and the user’s Okta permissions. After changing scope grants, sign in again so Okta can issue a token with the updated scopes. Then test again. [Okta’s tool and scope reference](https://help.okta.com/mcp/en-us/content/topics/mcpserver/scope-based-tool-loading.htm).

---

Index of every Speakeasy page for agents: [llms.txt](https://www.speakeasy.com/llms.txt). AI control plane and MCP gateway content in one file: [llms-full.txt](https://www.speakeasy.com/llms-full.txt). Any page is available as markdown by appending `.md` to its URL or by requesting it with `Accept: text/markdown`.
