Skip to main content

ThunderID MCP Server

ThunderID provides a Model Context Protocol (MCP) server that lets AI assistants and MCP clients manage applications, authentication flows, users, and themes directly.

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.

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. 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
  • Node.js and npm installed (to run MCP Inspector via npx)

Setup​

Pick your MCP client below. MCP Inspector works today; step-by-step guides for the other clients are on the way.

1

Register an MCP Client

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

  1. Go to Applications and 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:

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:

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

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. Review and approve the requested permissions on the consent screen.
  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 list_applications and 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.

What You Can Do​

Once connected, your AI assistant can work with ThunderID resources directly. MCP clients discover the available tools automatically, you just describe what you need in natural language.

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.

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​

NODE_EXTRA_CA_CERTS was not set in the terminal that launched Inspector, or it points to the wrong path.

  1. Export it again in the same terminal: export NODE_EXTRA_CA_CERTS=<THUNDERID_HOME>/config/certs/server.cert.
  2. Relaunch MCP Inspector from that terminal.

Redirect URI error during sign-in​

The redirect URI on the application does not exactly match http://localhost:6274/oauth/callback.

  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. Confirm the Scope field in MCP Inspector is set to system.

MCP server not responding​

Verify ThunderID is running and the endpoint is reachable:

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.