Skip to main content

ThunderID MCP Server

Connect your AI coding assistant to the ThunderID Model Context Protocol (MCP) server to manage applications and authentication flows, inspect themes, and generate React integration code.

Overview​

The MCP server is available through the /mcp endpoint of your ThunderID instance (default: https://localhost:8090/mcp). MCP clients discover the available tools automatically through the protocol.

Protocol Version Support​

ThunderID supports MCP protocol versions 2024-11-05 through 2026-07-28, including the stateless core introduced in 2026-07-28. Existing MCP clients continue to work without changes; ThunderID negotiates the protocol version per request. See the MCP specification for what changes between versions.

Authentication​

The endpoint follows the MCP Authorization Specification. The MCP server publishes protected resource metadata at /.well-known/oauth-protected-resource, advertising ThunderID as the OAuth authorization server. If a trusted issuer is configured, the metadata advertises that issuer instead. Spec-compliant MCP clients discover this automatically and run an OAuth authorization code + PKCE flow: you sign in through the browser, and the client obtains and refreshes tokens on its own. There is no manual token handling.

Access requires the system scope, and permissions come from the signed-in user, so sign in with an administrator account.

Prerequisites​

  • ThunderID server running (default: https://localhost:8090)
  • Access to the ThunderID Console with an administrator account
  • Your selected agent client installed: Claude Code or Codex CLI

Setup​

Select your agent client below to connect it to a local ThunderID instance. After connecting, ask the agent to list your applications or integrate authentication into your project.

For this local setup, Claude Code uses Dynamic Client Registration to register its own OAuth client. You do not need to create an application in the Console.

1

Enable Dynamic Client Registration

Claude Code also supports a pre-registered OAuth client through --client-id. To enable Dynamic Client Registration for this walkthrough, add the following to deployment.yaml in your ThunderID distribution:

yaml
oauth:
  dcr:
    insecure: true
warning

This setting is for local development only. It lets any client register with ThunderID without authentication. Do not enable it in production.

Restart ThunderID after saving the file.

2

Trust the Certificate for Claude Code

Claude Code runs on Node.js. Point it at the ThunderID self-signed certificate so TLS connections to https://localhost:8090 are trusted, without adding anything to your system trust store:

bash
export NODE_EXTRA_CA_CERTS=<THUNDERID_HOME>/config/certs/server.cert

<THUNDERID_HOME> is the directory of your ThunderID distribution. The certificate generated during setup includes subject alternative names for localhost and 127.0.0.1, so modern TLS clients accept it once it is trusted. Run the export in the same terminal session you launch claude from.

3

Add the MCP Server to Claude Code

bash
claude mcp add --transport http thunderid-mcp https://localhost:8090/mcp

Verify it was added:

bash
claude mcp list

You should see thunderid-mcp in the list.

4

Authenticate with ThunderID

  1. Start Claude Code from the same terminal where you exported NODE_EXTRA_CA_CERTS:
    bash
    claude
  2. Run /mcp inside the Claude Code prompt.
  3. Select thunderid-mcp and choose the authenticate option.
  4. A browser tab opens with the ThunderID sign-in page. Sign in with your administrator account.
  5. Review and approve the requested permissions on the consent screen.

Claude Code obtains and refreshes tokens automatically from here on. It discovers the required system scope from the server's metadata, so there is nothing else to configure.

5

Verify Claude Code Access

Ask Claude Code to use a tool, for example:

"List the applications registered in ThunderID"

Claude Code calls the matching tool and returns the list of registered applications. To remove the server later, run claude mcp remove "thunderid-mcp" -s local.

What You Can Do​

After connecting, ask your agent to use the ThunderID MCP server for tasks such as creating an application, inspecting an authentication flow, or generating SDK integration code. The agent discovers the available tools automatically.

ToolsetDescription
applicationsCreate, configure, and manage OAuth applications with pre-built templates for SPA, Mobile, Server, and M2M
flowsDesign and modify authentication and registration flows
themesBrowse and inspect login page themes, colors, and typography
organization_unitsList organization units
user_typesList user types and self-registration settings
react_sdkGet tailored integration code for the ThunderID React SDK

Example prompts:

  • "Create a new single-page application for my React project"
  • "Show me the current authentication flow"
  • "Add a second factor step to the default login flow"
  • "What colors and typography does the default theme use?"
  • "Integrate authentication with ThunderID for this application"

Use Cases​

Scaffold a React App with Login​

Ask the assistant to create a new React application with authentication wired up end-to-end:

"Create a new React application with authentication using ThunderID"

The assistant scaffolds a React project using Vite, installs the ThunderID React SDK, and wires up the auth provider with the correct clientId and server URL from the application registered in ThunderID. By the end you have a running app with a working sign-in button backed by ThunderID.

To add authentication to an existing React application instead:

"Integrate authentication with ThunderID for this application"

The assistant installs the SDK, configures the auth provider, and adds sign-in and sign-out components without scaffolding a new project.

Add Signup to a React App​

After integrating login, add a registration page:

"Integrate a signup page in the application and enable signup"

The assistant enables self-registration on your ThunderID application and generates a signup page wired to the registration flow. New users can register directly from your application and appear in the ThunderID Console under User Management.

Test and Debug with MCP Inspector​

Use MCP Inspector to list tools, call them manually, and inspect responses when testing the ThunderID MCP server or diagnosing a connection problem. To use these tools through an AI agent, follow Setup.

Install Node.js and npm before running MCP Inspector.

1

Register an MCP Client

In the ThunderID Console, register an application for MCP Inspector.

  1. In the Console, navigate to Applications. Click Add application.
  2. Select MCP client.
  3. Enter a name (for example, MCP Inspector).
  4. If prompted, select an organization unit.
  5. On the Client type step, select On behalf of a user. This configures the Authorization Code flow with PKCE as a public client.
  6. Under Redirect URIs, add http://localhost:6274/oauth/callback. The wizard shows this exact URI as a copyable hint for MCP Inspector.
  7. Click Finish.
  8. From the completion screen, copy the Client ID. You need it when connecting from MCP Inspector. No client secret is required because this is a public client.
2

Allow the MCP Inspector Origin

MCP Inspector runs in the browser at http://localhost:6274 and calls ThunderID cross-origin, so its origin must be allowed in the CORS configuration.

Create or update config/resources/server_configs/cors.yaml in your ThunderID distribution, or use PUT /server-config/cors after startup:

yaml
name: cors
value:
  allowedOrigins:
    - "http://localhost:6274"

If the file already exists, append the origin to the existing allowedOrigins list instead of replacing it. Restart ThunderID after editing the file so the change takes effect.

3

Trust the ThunderID Certificate

MCP Inspector's proxy runs on Node.js. Point Node.js at the ThunderID self-signed certificate so TLS connections to https://localhost:8090 are trusted, without adding anything to your system trust store:

bash
export NODE_EXTRA_CA_CERTS=<THUNDERID_HOME>/config/certs/server.cert

<THUNDERID_HOME> is the directory of your ThunderID distribution. The certificate generated during setup includes subject alternative names for localhost and 127.0.0.1, so modern TLS clients accept it once it is trusted. Run the export in the same terminal session you launch MCP Inspector from.

4

Launch MCP Inspector

bash
npx @modelcontextprotocol/inspector

The Inspector UI opens at http://localhost:6274.

5

Connect to the MCP Server

  1. Set Transport type to Streamable HTTP.
  2. Set URL to https://localhost:8090/mcp.
  3. Expand the Authentication section and select OAuth.
  4. Enter the Client ID you copied earlier. Leave Client secret empty.
  5. Set Scope to system.
  6. Click Connect.
  7. A browser tab opens with the ThunderID sign-in page. Sign in with your administrator account.
  8. If a consent screen appears, review the requested permissions. Approve them to continue.
  9. You are redirected back to MCP Inspector, now connected. Tokens are obtained and refreshed automatically from here on.
6

Verify the Connection

  1. In MCP Inspector, open the Tools tab and click List Tools.
  2. Select a tool such as thunderid_list_applications. Run it.
  3. The response lists the applications registered in ThunderID, including the MCP Inspector application you just created.

If the connection fails, see the Troubleshooting section below.

Troubleshooting​

Browser shows a CORS error or the connection hangs​

The Inspector origin is missing from the CORS configuration.

  1. Re-check the cors.yaml step under Allow the MCP Inspector Origin.
  2. Restart ThunderID after saving the change.

Certificate or TLS errors​

Set the certificate variable for the client you are using:

  • Codex: export CODEX_CA_CERTIFICATE=<THUNDERID_HOME>/config/certs/server.cert
  • Claude Code or MCP Inspector: export NODE_EXTRA_CA_CERTS=<THUNDERID_HOME>/config/certs/server.cert

Replace <THUNDERID_HOME> with your distribution path. Confirm the certificate file exists, then restart your client from the same terminal.

Codex or Claude Code cannot register an OAuth client​

Client registration is disabled or requires authentication.

  1. For the local setup above, set oauth.dcr.insecure: true in deployment.yaml.
  2. Restart ThunderID.
  3. Confirm the certificate variable is set for your client.

OAuth client registration fails with "An application with the same name already exists"​

A new Dynamic Client Registration request can conflict with an application created during an earlier sign-in. ThunderID rejects duplicate application names.

  1. In the ThunderID Console, navigate to Applications.
  2. Identify the application from your previous client registration, such as Codex or Claude Code (thunderid-mcp). Delete it only if you no longer need that registration.
  3. Retry sign-in with codex mcp login thunderid-mcp --scopes system, or authenticate Claude Code from /mcp.

Redirect URI error during sign-in​

For MCP Inspector, the redirect URI on the application must match http://localhost:6274/oauth/callback. Other clients use their own redirect URIs. The Codex setup above registers its redirect URI automatically.

  1. Edit the application in the Console.
  2. Correct the redirect URI under Redirect URIs and save.

403 or insufficient scope after connecting​

The signed-in user lacks administrator permissions, or the scope was not set to system.

  1. Sign in with an administrator account.
  2. For Codex, run codex mcp login thunderid-mcp --scopes system to sign in again with the required scope. For MCP Inspector, set Scope to system.

MCP server not responding​

Verify ThunderID is running and the endpoint is reachable:

bash
curl -k https://localhost:8090/mcp

A 401 Unauthorized response with a WWW-Authenticate header confirms the endpoint is up and secured. Any other error indicates the server is not running or the URL is incorrect.

Explore with AI

ThunderID LogoThunderID Logo

Product

DocsAPIsSDKs

Community

ContributingEventsDiscussionsReport an Issue

Resources

ReleasesGitHubBrand Guidelines
© Copyright Linux Foundation Europe.For web site terms of use, trademark policy and other project policies please see https://linuxfoundation.eu/en/policies.