Configuring MCP Servers with AI Assistants

This guide shows how to connect your AI assistant to OpenChoreo MCP servers using the pre-configured default OAuth applications or custom setups.

Prerequisites

Before following this guide:

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

Quick Start (Default Setup)

This guide uses the pre-created OAuth applications available in the default Thunder IdP that ships with the k3d setup. No manual IdP configuration is required. The following AI agents are supported:

AI Agent	Browser-Based	Client Credentials
Claude Code	Yes	Yes
Cursor	Yes	Yes
VS Code (GitHub Copilot)	—	Yes
Codex CLI	—	Yes

Browser-Based (Recommended)

Browser-based authentication uses the user_mcp_client OAuth application (public client with PKCE, authorization code grant), which is pre-created in the default Thunder IdP.

When prompted, log in with the default credentials:

• Username: admin@openchoreo.dev
• Password: Admin@123

Claude Code

Add both MCP servers using the Claude Code CLI:

claude mcp add --transport http \
  --client-id user_mcp_client --callback-port 8075 \
  openchoreo-cp http://api.openchoreo.localhost:8080/mcp

claude mcp add --transport http \
  --client-id user_mcp_client --callback-port 8075 \
  openchoreo-obs http://observer.openchoreo.localhost:11080/mcp

Then, inside a Claude Code session, run /mcp to verify the servers are connected. Select a server and authenticate in the browser when prompted.

Cursor

Add the following to ~/.cursor/mcp.json (or via Cursor Settings > Tools & Integrations > Add Custom MCP):

{
  "mcpServers": {
    "openchoreo-cp": {
      "protocol": "http",
      "url": "http://api.openchoreo.localhost:8080/mcp",
      "auth": {
        "CLIENT_ID": "user_mcp_client"
      }
    },
    "openchoreo-obs": {
      "protocol": "http",
      "url": "http://observer.openchoreo.localhost:11080/mcp",
      "auth": {
        "CLIENT_ID": "user_mcp_client"
      }
    }
  }
}

On first use, a browser window opens for authentication. Log in with the default credentials above.

Client Credentials

Client credentials authentication uses the service_mcp_client OAuth application (confidential client, client_credentials grant), which is pre-created in the default Thunder IdP. This method works with any AI agent that supports custom HTTP headers.

Step 1: Obtain an Access Token

curl -s -X POST "http://thunder.openchoreo.localhost:8080/oauth2/token" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -u 'service_mcp_client:service_mcp_client_secret' \
  -d 'grant_type=client_credentials'

The response contains an access_token:

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

Copy the access_token value and replace <ACCESS_TOKEN> in the configuration below.

Step 2: Configure Your AI Agent

Claude Code

claude mcp add --transport http \
  --header "Authorization: Bearer <ACCESS_TOKEN>" \
  openchoreo-cp http://api.openchoreo.localhost:8080/mcp

claude mcp add --transport http \
  --header "Authorization: Bearer <ACCESS_TOKEN>" \
  openchoreo-obs http://observer.openchoreo.localhost:11080/mcp

Cursor

Add the following to ~/.cursor/mcp.json (or via Cursor Settings > Tools & Integrations > Add Custom MCP):

{
  "mcpServers": {
    "openchoreo-cp": {
      "protocol": "http",
      "url": "http://api.openchoreo.localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer <ACCESS_TOKEN>"
      }
    },
    "openchoreo-obs": {
      "protocol": "http",
      "url": "http://observer.openchoreo.localhost:11080/mcp",
      "headers": {
        "Authorization": "Bearer <ACCESS_TOKEN>"
      }
    }
  }
}

VS Code (GitHub Copilot)

Create a .vscode/mcp.json file in your workspace:

{
  "servers": {
    "openchoreo-cp": {
      "type": "http",
      "url": "http://api.openchoreo.localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer <ACCESS_TOKEN>"
      }
    },
    "openchoreo-obs": {
      "type": "http",
      "url": "http://observer.openchoreo.localhost:11080/mcp",
      "headers": {
        "Authorization": "Bearer <ACCESS_TOKEN>"
      }
    }
  }
}

Codex CLI

Set the access token as an environment variable:

export OPENCHOREO_MCP_TOKEN="<ACCESS_TOKEN>"

Then add the following to ~/.codex/config.toml:

[mcp_servers.openchoreo-cp]
url = "http://api.openchoreo.localhost:8080/mcp"
bearer_token_env_var = "OPENCHOREO_MCP_TOKEN"

[mcp_servers.openchoreo-obs]
url = "http://observer.openchoreo.localhost:11080/mcp"
bearer_token_env_var = "OPENCHOREO_MCP_TOKEN"

Token Expiry

Access tokens expire (default: 1 hour). When your token expires, re-run the curl command from Step 1 to obtain a new token and update your AI agent configuration.

Advanced Configuration

For custom AI agents, non-default IdP configurations, or custom OAuth application setups.

Creating a Custom OAuth Application

If you need to create your own OAuth application (e.g., for a different IdP, custom redirect URIs, or non-default client settings), create an application in your IdP with one of the following configurations:

Client Credentials (Programmatic Access):

Setting	Value
Grant Type	client_credentials
Client ID	Your chosen client ID
Client Secret	Your chosen client secret

Authorization Code (Browser-Based Access):

Setting	Value
Grant Types	authorization_code, refresh_token
Client ID	Your chosen client ID
Public Client (PKCE)	true
Redirect URIs	Configure per your AI agent's callback URL
Scopes	openid, profile, email

Redirect URIs

The redirect URI must match your AI agent's OAuth callback URL. Refer to your AI agent's MCP documentation for the correct callback URL and port.

Configuring Non-Default Installations

If your OpenChoreo installation uses a custom base domain or non-standard ports, refer to the MCP Servers Overview for instructions on constructing the correct MCP server URLs. Replace the openchoreo.localhost URLs in the examples above with your actual MCP server URLs.