Skip to main content

Getting Started with MCP

Connect Claude Desktop, Claude Code, or VS Code with Copilot to ThunderID using the built-in MCP server. Once connected, your AI tool can manage applications, authentication flows, users, and themes directly from your conversation.

The MCP server is available at https://localhost:8090/mcp (or your configured PUBLIC_URL). See the MCP Server guide for the full list of available tools.

Prerequisites​

  • ThunderID server running (default: https://localhost:8090)
  • ThunderID certificate trusted by your system — add backend/cmd/server/repository/resources/security/server.cert to your system's trusted certificate store (Keychain on macOS, certificate store on Linux/Windows)
  • One of the following installed: Claude Desktop, Claude Code CLI, or VS Code with the GitHub Copilot extension
  • Access to the ThunderID Console
1

Create an Application

In the ThunderID Console, create a Backend Service application to use as your MCP client.

  1. Go to Applications and click Add Application.
  2. Select Backend Service as the application type.
  3. Provide a name for the application (for example, My MCP Client).
  4. Select an organization unit and click Create.
Save your client secret

Copy and store the client secret now — it will not be shown again.

After saving the secret, note the Client ID from the application details view. You will need both values in the next steps.

2

Assign the Application to the Administrator Role

Assign your application to the Administrator role so it has the permissions needed to access ThunderID APIs through the MCP server.

  1. Go to Roles and select Administrator.
  2. Click the Assignments tab.
  3. Under Apps, click Add and select the application you created.
3

Get an Access Token

Exchange your application credentials for a bearer token scoped to the MCP server. Replace <CLIENT_ID> and <CLIENT_SECRET> with the values from your application.

curl -kL -X POST https://localhost:8090/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "<CLIENT_ID>:<CLIENT_SECRET>" \
  -d "grant_type=client_credentials" \
  -d "scope=system"

Copy the access_token value from the response. This token is valid for 3600 seconds (1 hour). You will need to repeat this step when it expires.

Refresh the token

When you receive a 401 from the MCP server, generate a new token using the same command and update your configuration with the new value.

4

Configure Your AI Tool

Add the following to your Claude Desktop configuration file. Replace <ACCESS_TOKEN> with the token from the previous step.

Configuration file locations:

OSPath
macOS~/Library/Application Support/Claude/claude_desktop_config.json
Windows%APPDATA%\Claude\claude_desktop_config.json
Linux~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "thunderid-mcp": {
      "type": "http",
      "url": "https://localhost:8090/mcp",
      "headers": {
        "Authorization": "Bearer <ACCESS_TOKEN>"
      }
    }
  }
}

Restart Claude Desktop after saving the file. The ThunderID tools will appear in Claude's tool list.

5

Verify the Connection

Ask your AI assistant to confirm the MCP tools are working:

"List the applications registered in ThunderID"

The assistant will call the thunderid_list_applications tool and return the list of registered applications.

If the assistant cannot reach the server, see the Troubleshooting section below.

Sample Use Case: Integrating Login via React SDK​

This example shows how to use the ThunderID MCP server to scaffold a React application with authentication wired up end-to-end — using just two prompts.

The MCP server gives your AI assistant direct access to ThunderID's APIs. Rather than you manually creating an application, configuring OAuth settings, and reading through SDK documentation, the assistant handles that automatically. Both prompts will create an application in ThunderID if one does not already exist. The assistant selects the right OAuth template, picks a theme, and resolves your organization unit, then generates integration code tailored to that application's configuration.

Prompt 1: Create a React Application with Authentication​

"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 of this prompt you have a running React app with a working sign-in button backed by ThunderID.

Prompt 2: Add Authentication to an Existing React Application​

"Integrate authentication with ThunderID for this application"

Use this prompt when you already have a React application and want to add ThunderID authentication to it. The assistant generates the integration code for your existing codebase. It installs the SDK, configures the auth provider with the correct clientId and server URL, and adds sign-in and sign-out components. It also shows how to access the authenticated user's profile.

Unlike Prompt 1, this does not scaffold a new project. It works on top of your existing app and adds only what is needed for authentication.

Sample Use Case: Integrating Signup via React SDK​

This example extends the login integration to add a signup page using the app-native registration flow.

Step 1: Enable Signup and Integrate a Signup Page​

After integrating login, ask your AI assistant:

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

The assistant enables self-registration on your ThunderID application and generates a signup page for your React app — wired to the registration flow configured in ThunderID. New users can register directly from your application without going through the admin Console.

Step 2: Verify Signup Works​

New users can now register directly from your application. Users created through the signup flow appear in the ThunderID Console under User Management.

Troubleshooting​

401 Unauthorized​

The access token has expired or is invalid.

  1. Generate a new token using the command in Step 3.
  2. Update the Authorization header value in your configuration with the new token.
  3. Claude Desktop: restart after saving the config file.
  4. Claude Code: re-add the server with the new token (claude mcp add ...).
  5. VS Code: run MCP: Reset Stored Inputs from the command palette, then restart the server.

Certificate / TLS Errors​

The ThunderID certificate is not trusted by your system.

  1. Add backend/cmd/server/repository/resources/security/server.cert to your system's trusted certificate store.
  2. Restart your AI tool so it picks up the updated certificate trust settings.

MCP Server Not Responding​

Verify ThunderID is running and the MCP endpoint is reachable:

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

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

ThunderID LogoThunderID Logo

Product

DocsAPIsSDKs

Community

ContributingDiscussionsReport an Issue

Resources

ReleasesGitHub
© WSO2 LLC. All rights reserved.Privacy PolicyCookie Policy