Version: Next

Configuring MCP Servers with AI Assistants

This guide shows how to obtain authentication credentials and configure your AI assistant to connect to OpenChoreo MCP servers.

Prerequisites

Before following this guide:

Review the MCP Servers Overview to understand the available MCP servers
Note your MCP server URLs from the overview page
Have your AI assistant installed and ready to configure

Obtaining an Authentication Token

Both MCP servers require authentication using JWT tokens. OpenChoreo uses an identity provider for authentication. The default identity provider is Asgardeo Thunder.

Finding Your Thunder Hostname

The Thunder hostname is constructed from the global.baseDomain configured during Helm installation: thunder.<global.baseDomain>

To find your configured base domain:

# Check from Helm values
helm get values openchoreo-control-plane -n openchoreo-control-plane | grep baseDomain

# Or derive from the Thunder hostname (OpenChoreo uses Gateway API HTTPRoutes)
kubectl get httproute thunder-openchoreo -n openchoreo-control-plane -o jsonpath='{.spec.hostnames[0]}' | sed 's/^thunder\.//'

Once you have your baseDomain, construct your Thunder URLs:

Developer Portal: http://thunder.<baseDomain>:<port>/develop or https://thunder.<baseDomain>/develop
Token Endpoint: http://thunder.<baseDomain>:<port>/oauth2/token or https://thunder.<baseDomain>/oauth2/token

Self-Hosted Kubernetes Deployment Example

If you used the Self-Hosted Kubernetes Deployment with baseDomain: openchoreo.localhost, your Thunder URLs will be:

Developer Portal: http://thunder.openchoreo.localhost:8080/develop
Token Endpoint: http://thunder.openchoreo.localhost:8080/oauth2/token

Follow these steps to obtain an authentication token.

Step 1: Get the Application ID

Open your browser and navigate to the Thunder developer portal at <thunder-hostname>/develop

Note: Default credentials are admin / admin

Then:

Open the Sample App application
Copy the Application ID

Step 2: Obtain an Admin Token

First, set your environment variables with your Thunder hostname and application ID:

export APPLICATION_ID="<application_id>"
export THUNDER_URL="<thunder-hostname>"

Self-Hosted Kubernetes Deployment Example

export APPLICATION_ID="<application_id>"
export THUNDER_URL="http://thunder.openchoreo.localhost:8080"

Then, obtain the admin token:

ADMIN_TOKEN_RESPONSE=$(curl -k -s -X POST "${THUNDER_URL}/flow/execute" \
  -H 'Content-Type: application/json' \
  -d '{
    "applicationId": "'"${APPLICATION_ID}"'",
    "flowType": "AUTHENTICATION",
    "inputs": {
      "username": "admin",
      "password": "admin",
      "requested_permissions": "system"
    }
  }')

ADMIN_TOKEN=$(echo $ADMIN_TOKEN_RESPONSE | jq -r '.assertion')

Step 3: Create an OAuth2 Application

Create a new OAuth2 application with client credentials grant:

curl -L "${THUNDER_URL}/applications" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{
    "name": "MCP client",
    "description": "MCP client application to use openchoreo MCP servers",
    "auth_flow_graph_id": "auth_flow_config_basic",
    "inbound_auth_config": [
        {
            "type": "oauth2",
            "config": {
                "client_id": "mcp_client",
                "client_secret": "mcp_client_secret",
                "grant_types": [
                    "client_credentials"
                ],
                "token_endpoint_auth_method": "client_secret_basic",
                "token": {
                    "issuer": "thunder",
                    "access_token": {
                        "validity_period": 3600
                    }
                }
            }
        }
    ]
}'

Step 4: Obtain Your Token

Use the client credentials to get an access token:

curl -L "${THUNDER_URL}/oauth2/token" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -u 'mcp_client:mcp_client_secret' \
  -d 'grant_type=client_credentials'

The response will contain an access_token that you can use as the Bearer token for authenticating with both OpenChoreo MCP servers.

Example response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Copy the access_token value for use in your AI assistant configuration.

Configuring AI Assistants

You can configure your AI assistant to connect to one or both MCP servers depending on your needs:

Control Plane MCP Server Only

Configure this if you want to manage OpenChoreo resources (organizations, projects, components, deployments, etc.):

Endpoint URL: Use the Control Plane MCP server URL from the MCP Servers Overview
Use Case: Application development, deployment management, infrastructure configuration

Observability Plane MCP Server Only

Configure this if you want to access observability data:

Endpoint URL: Use the Observability Plane MCP server URL from the MCP Servers Overview
Use Case: Troubleshooting, monitoring, log analysis, performance investigation

Recommended

Configure both servers for the best experience. The Control Plane MCP server provides resource UUIDs that are needed by many Observability Plane MCP tools.

To configure both servers:

Add the Control Plane MCP server configuration with its endpoint URL
Add the Observability Plane MCP server configuration with its endpoint URL
Use the same authentication token for both servers

Your AI assistant will have access to tools from both servers, enabling it to manage resources and troubleshoot issues simultaneously.

Example Configuration

Here's an example of how you might configure both MCP servers in your AI assistant's configuration. Replace the URLs with your actual MCP server URLs from the MCP Servers Overview.

{
  "mcpServers": {
    "openchoreo-control-plane": {
      "url": "<control-plane-api-hostname>/mcp",
      "transport": {
        "type": "http",
        "headers": {
          "Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
        }
      }
    },
    "openchoreo-observability": {
      "url": "<observer-service-hostname>/mcp",
      "transport": {
        "type": "http",
        "headers": {
          "Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
        }
      }
    }
  }
}

Replace:

<control-plane-api-hostname> with your Control Plane API hostname
<observer-service-hostname> with your Observer service hostname
YOUR_ACCESS_TOKEN_HERE with the actual access token from Step 4

Self-Hosted Kubernetes Deployment Examples

Single Cluster:

{
  "mcpServers": {
    "openchoreo-control-plane": {
      "url": "http://api.openchoreo.localhost:8080/mcp",
      ...
    },
    "openchoreo-observability": {
      "url": "http://observer.openchoreo.localhost:11080/mcp",
      ...
    }
  }
}

Multi-Cluster:

{
  "mcpServers": {
    "openchoreo-control-plane": {
      "url": "http://api.openchoreo.localhost:8080/mcp",
      ...
    },
    "openchoreo-observability": {
      "url": "http://observer.observability.openchoreo.localhost:11087/mcp",
      ...
    }
  }
}

Next Steps

After configuring your AI assistant:

Test the connection by asking your AI assistant to list OpenChoreo projects or components
For observability queries, ensure both MCP servers are configured to enable UUID-based queries
Refer to your AI assistant's documentation for MCP-specific features and capabilities

Prerequisites​

Obtaining an Authentication Token​

Finding Your Thunder Hostname​

Step 1: Get the Application ID​

Step 2: Obtain an Admin Token​

Step 3: Create an OAuth2 Application​

Step 4: Obtain Your Token​

Configuring AI Assistants​

Control Plane MCP Server Only​

Observability Plane MCP Server Only​

Example Configuration​

Next Steps​