Authenticate MCP clients with OAuth

Overview

This page explains how to connect an MCP-aware AI client - Claude Code or Visual Studio Code - to a CAST MCP Server using OAuth, instead of passing a CAST Imaging API key in the client configuration. It is intended for the administrator who configures Keycloak, and for the end user who configures the AI client. It applies to both MCP Server for CAST Imaging and MCP Server for CAST Gatekeeper.

With OAuth enabled, the first request from the AI client opens a browser window and the user signs in to CAST Imaging through Keycloak. The access token is then exchanged by CAST Imaging so that all downstream API calls carry the roles and permissions of the signed-in user. No API key is stored in the client configuration file.

Requirements

• CAST Imaging 3.6.6-funcrel or later (see below)
• the MCP Server release matching the results you query:
  • MCP Server for CAST Imaging: 3.0.4-funcrel or later
  • MCP Server for CAST Gatekeeper: 3.0.1-funcrel or later
• access to the Keycloak admin UI at http://<imaging-services-fqdn>:8090/auth with the kcadmin account - see Configure authentication and Keycloak accounts and passwords
• an MCP-aware client, either Claude Code or Visual Studio Code
• for a production setup HTTPS configuration enabled on the CAST Imaging gateway is highly recommended

What is already configured

The following is provided by the CAST Imaging installation and requires no action:

• the Keycloak CIMD feature is enabled out of the box
• the mcp:* client scopes, their audience mappers, and the confidential mcp-token-exchange client are created automatically at start up
• the CAST Imaging gateway (the imaging-services component) performs the token exchange for MCP requests

The configuration you perform is the per-client CIMD policy in Keycloak (Step 1) and the AI client configuration itself (Step 2), plus the PUBLIC_URL environment variable described below for a Windows installation accessed over http.

Windows installations accessed over HTTP

This applies to a Windows installation only, when CAST Imaging is accessed over http. No action is required for a Docker installation, or when HTTPS configuration is enabled.

On the machine on which the imaging-services component is installed, create a SYSTEM level environment variable called PUBLIC_URL, using the fully qualified domain name of that machine and the user access port 8090:

PUBLIC_URL=http://<imaging-services-fqdn>:8090

Restart the imaging-services services for the change to be taken into account.

Step 1 - Create the CIMD client policy in Keycloak

In Keycloak, a CIMD policy consists of two linked objects:

• a profile, which holds the rules
• a policy, which determines the clients the rules apply to

Create one profile and one policy per AI client you intend to support. Log in to the Keycloak admin UI, ensure you are working in the aip-realm realm, then navigate to Realm Settings > Client Policies.

Use the tabs below to select the configuration matching your deployment: HTTPS for a production deployment, HTTP for a development or test deployment only.

• HTTPS (production)
• HTTP (development only)

About the two trusted domain lists

The two Trusted domains lists serve different purposes and are not interchangeable:

• the list in the profile defines where Keycloak fetches the client metadata document from, and validates the loopback callback address, which is why it includes localhost and 127.0.0.1
• the list in the policy matches the origin of the client_id URL only

Each AI client presents a fixed client_id:

The client_id must contain a path and must not carry a query string or a fragment. For the full description of the executor and condition see the Keycloak MCP authorization server documentation .

Step 2 - Configure your AI client

The AI client must point to the CAST Imaging gateway - the machine on which the imaging-services component is installed - and not to the MCP Server directly. Use:

• either http or https depending on whether HTTPS configuration has been enabled
• the fully qualified domain name of the machine, such as imaging.corp.mycompany.com, or its IP address
• the user access port for CAST Imaging, either 8090 (http) or 443 (https) - when https runs on port 443 the port can be omitted
• the endpoint of the target MCP Server:

• Claude Code
• Visual Studio Code

$ claude mcp add --transport http --scope user cast-imaging http[s]://<fqdn-or-IP-address-imaging-services-machine:[port]>/mcp

$ claude mcp list

{
  "servers": {
    "cast-imaging": {
      "type": "http",
      "url": "http[s]://<fqdn-or-IP-address-imaging-services-machine:[port]>/mcp"
    }
  }
}

Step 3 - Verify

Run the following from any machine that can reach the CAST Imaging gateway, replacing the URL and the endpoint with your own values:

# Protected resource metadata, unauthenticated - returns JSON pointing at the Keycloak issuer
$ curl -s http[s]://<fqdn-or-IP-address-imaging-services-machine:[port]>/.well-known/oauth-protected-resource/mcp | jq

# The healthcheck endpoint remains open - expect 200
$ curl -s -o /dev/null -w '%{http_code}\n' http[s]://<fqdn-or-IP-address-imaging-services-machine:[port]>/mcp/healthcheck

# An unauthenticated POST returns the Bearer challenge
$ curl -s -i -X POST http[s]://<fqdn-or-IP-address-imaging-services-machine:[port]>/mcp | grep -i www-authenticate

The last command returns a header of the following form:

WWW-Authenticate: Bearer resource_metadata="http[s]://<fqdn-or-IP-address-imaging-services-machine:[port]>/.well-known/oauth-protected-resource/mcp"

The setup is complete when, after signing in from the AI client, a query such as List all applications returns results.

Troubleshooting

FAQ

See the frequently asked questions for MCP Server for CAST Imaging and for MCP Server for CAST Gatekeeper.