Connect the Okta MCP Server to MCPlama

The Okta Open Source MCP Server exposes Okta administration tools to compatible AI clients. When you run it as a Docker server managed by MCPlama, it needs to authenticate to your Okta organization without stopping for a person to sign in interactively.

For this containerized setup, use an Okta API Services app integration with the Private Key JWT client authentication flow. Device Authorization is another supported path for interactive use, but it is designed around a user completing a browser sign-in. Follow Okta’s current authentication guide for the latest Admin Console screens.

1. Create an Okta API Services app

In the Okta Admin Console, go to Applications and Resources → Applications → Create App Integration. Choose API Services as the sign-in method, continue, name the integration, and save it.

An API Services app uses the Client Credentials grant for service-to-service access. A Native app configured for Authorization Code or Device Authorization is a different flow and will not work as a substitute for this browserless setup.

2. Configure Private Key JWT

In the app’s Client Credentials settings, choose Public key / Private key for client authentication. Register a public signing key with the app, then save the matching private key securely. Okta can generate a PEM key pair, or you can register a public key generated in your own environment. Copy the app’s Client ID and the key’s Key ID (KID).

The private key configured in MCPlama must match the public key registered for this same app and KID. If Okta generated the pair, save the private key when it is shown; you may not be able to retrieve it later.

In the app’s General Settings, disable Require Demonstrating Proof of Possession (DPoP) header in token requests. The Okta MCP server’s Private Key JWT flow does not send a DPoP proof, so requiring one can produce an invalid_dpop_proof token error.

3. Grant only the scopes you need

Open the app’s Okta API Scopes tab and grant the API scopes needed by the tools you intend to use. Start with read-only access, for example:

okta.users.read
okta.groups.read

Also add the requested scopes to the server’s OKTA_SCOPES value as one space-separated string:

okta.users.read okta.groups.read

A scope must be both granted to the app and requested by the MCP server. The server loads tools according to configured scopes, so it may return fewer tools than expected if some resource scopes are missing. Add scopes such as okta.apps.read, okta.logs.read, or okta.policies.read only when needed. Use .manage scopes only for workflows that require changes.

Assign the service app an Okta admin role that limits it to the resources and operations it needs. Scopes and admin roles work together: granting a scope alone does not replace the role permissions. Avoid assigning broader privileges than the integration requires.

4. Add the Okta server in MCPlama

In MCPlama, add or edit the Docker-based Okta MCP server and set its environment variables. Replace the example values with the ones from your Okta API Services app:

OKTA_ORG_URL=https://your-org.okta.com
OKTA_CLIENT_ID=<API_SERVICES_CLIENT_ID>
OKTA_KEY_ID=<KID_FOR_THE_REGISTERED_PUBLIC_KEY>
OKTA_PRIVATE_KEY=<MATCHING_RSA_PRIVATE_KEY_IN_PEM_FORMAT>
OKTA_SCOPES=okta.users.read okta.groups.read
OKTA_LOG_LEVEL=INFO
OKTA_LOG_FILE=

Use the PEM private key, including its BEGIN and END lines. If the environment variable editor expects a single line, represent PEM line breaks with literal \n sequences. Do not paste the public JWK into OKTA_PRIVATE_KEY. Keep the key out of source control, screenshots, and issue reports.

Use a valid log level such as INFO, WARNING, or ERROR. Leave OKTA_LOG_FILE empty unless the server setup specifically requires a file path.

5. Test the connection

Run MCPlama’s server connection test. It initializes the MCP session and requests the tool list. A successful test means the Okta process authenticated and returned its available tools. Confirm that the returned set includes the user, group, or other tools covered by your configured scopes.

If the test succeeds but the tool list is shorter than expected, check both places: the scopes granted in Okta and the scopes listed in OKTA_SCOPES. Expand access only for tools you plan to use.

Troubleshoot common Okta MCP errors

tools/list failed with HTTP 400

This is the gateway’s outer error. For a Docker stdio server started by MCPlama’s broker, inspect the broker log for the underlying Okta error:

docker exec mcplama sh -c 'tail -200 /var/log/mcplama/broker.log'

invalid_client: The client_assertion signature is invalid

The KID and private key likely do not match, or the PEM was changed while copying. Register a new public key and configure its matching private key and KID together.

invalid_client: The client_assertion JWT kid is invalid

The KID is not registered on the app identified by OKTA_CLIENT_ID. Make sure both values belong to the same API Services integration.

unauthorized_client

Check that you created an API Services app and selected Public key / Private key authentication. A Native app using an interactive grant does not support this server-to-server flow.

invalid_dpop_proof

Disable the app setting that requires a DPoP header in token requests, then retry the connection.

EADDRINUSE: address already in use

This indicates a local listener collision rather than an Okta credential or scope problem. Check the broker log for an earlier test session that has not closed, then retry after the failed session is cleaned up.

Keep the integration secure

Treat the private key as a production credential, even in a test tenant. If it is exposed, revoke the registered public key and create a replacement pair. Protect the broker log as well, and review server logging before using real credentials to ensure it does not print environment variables, access tokens, or private keys.

For more context, see the Okta MCP authentication guide, the Okta MCP server configuration guide, and Okta’s guide to service app OAuth. To understand the gateway side, read the MCPlama documentation or visit the MCPlama homepage.