Secure MCP Server with Keycloak

A demonstration project showing how to secure a Spring Boot MCP (Model Context Protocol) server using Keycloak with OAuth 2.0 Dynamic Client Registration and Token Exchange.

Overview

This project implements a secure architecture for MCP servers that allows AI clients (like Claude) to authenticate and call downstream services. It uses two advanced OAuth 2.0 patterns:

• Dynamic Client Registration (DCR): Allows MCP clients to register themselves programmatically
• Token Exchange: Enables the MCP server to exchange tokens when calling downstream services

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   AI Client     │────▶│   MCP Server    │────▶│   Temperature   │◀────│    Keycloak     │
│   (Claude)      │     │   (Spring Boot) │     │   API           │     │   (OAuth 2.0)   │
└─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                                               │
        │                       │                                               │
        └───────────────────────┴──────── Token Exchange ──────────────────────┘

The setup consists of:

• MCP Server: Exposes MCP tools to AI clients, handles OAuth 2.0 authentication
• Temperature API: A resource server that returns temperature readings
• Keycloak: Identity and access management with two realms:
  • demo-mcp-servers: For MCP client registrations (DCR)
  • demo-users: Contains users and protects the Temperature API
• Traefik: Reverse proxy that routes traffic

Prerequisites

• Docker and Docker Compose
• Java 25+ (for building the applications)
• Maven (or use the included Maven wrapper)
• ngrok (or similar tunneling service) for exposing services to the internet
• Terraform (optional, for automated Keycloak configuration)

Quick Start

Step 1: Set Up a Public URL

Since MCP clients like Claude need to reach your services over the internet, you need a public URL. Using ngrok:

ngrok http 80

Note your ngrok URL (e.g., https://xxxx-xx-xxx-xx-xxx.ngrok-free.app).

Step 2: Update Configuration

Update the ngrok domain in the following files:

docker-compose.yaml - Replace all occurrences of 04f7-81-240-46-212.ngrok-free.app with your ngrok domain:

# Line 17: Keycloak hostname
KC_HOSTNAME: your-ngrok-domain.ngrok-free.app

# Line 32: MCP Server issuer URI
ISSUER_URI: https://your-ngrok-domain.ngrok-free.app/keycloak/realms/demo-mcp-servers

# Line 33: Temperature API URL
TEMPERATURE_API: https://your-ngrok-domain.ngrok-free.app/api

# Line 51: Temperature API issuer URI
ISSUER_URI: https://your-ngrok-domain.ngrok-free.app/keycloak/realms/demo-users

keycloak/terraform/variables.tf - Update the Keycloak URL:

variable "keycloak_url" {
  type    = string
  default = "https://your-ngrok-domain.ngrok-free.app/keycloak"
}

Step 3: Build Docker Images

Build the MCP Server:

cd mcp-server
chmod +x build-docker.sh
./build-docker.sh
cd ..

Build the Temperature API:

cd temperature-api
chmod +x build-docker.sh
./build-docker.sh
cd ..

Step 4: Start the Services (First Run)

Start only Keycloak first to configure it:

docker compose up keycloak traefik -d

Wait for Keycloak to be fully started (check logs with docker compose logs -f keycloak).

Step 5: Configure Keycloak

You have two options:

Option A: Using Terraform (Recommended)

cd keycloak/terraform
terraform init
terraform apply
cd ../..

Then, configure Dynamic Client Registration manually in Keycloak. See the Configure DCR.

Option B: Manual Configuration

Follow the complete manual setup guide in the [blog post](https://bl

... View full README on GitHub