Skip to content

README.md

Latest commit

 

History

History
180 lines (134 loc) · 3.5 KB

README.md

File metadata and controls

180 lines (134 loc) · 3.5 KB

Java Auth MCP Server

An OAuth-protected MCP (Model Context Protocol) server demonstrating JWT token validation and scope-based access control.

Prerequisites

  • Java 17 or later
  • Maven 3.8 or later

Building

mvn package

Running

Development Mode (No Auth)

./run_example.sh --no-auth

With Configuration File

./run_example.sh --config server.config

Direct Java Execution

java -jar target/auth-mcp-server-1.0.0.jar server.config

Configuration

Create a server.config file with the following options:

# Server settings
host=0.0.0.0
port=3001

# OAuth/IDP settings
client_id=my-client
client_secret=my-secret
auth_server_url=https://keycloak.example.com/realms/mcp

# Scopes
allowed_scopes=openid profile email mcp:read mcp:admin

# Cache settings
jwks_cache_duration=3600
jwks_auto_refresh=true
request_timeout=30

# Auth bypass mode (for development)
auth_disabled=true

Endpoints

Health Check

curl http://localhost:3001/health

OAuth Discovery

# Protected Resource Metadata (RFC 9728)
curl http://localhost:3001/.well-known/oauth-protected-resource

# Authorization Server Metadata (RFC 8414)
curl http://localhost:3001/.well-known/oauth-authorization-server

# OpenID Configuration
curl http://localhost:3001/.well-known/openid-configuration

MCP Endpoints

Initialize

curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

List Tools

curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Call Tool (get-weather)

curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":3,
    "method":"tools/call",
    "params":{
      "name":"get-weather",
      "arguments":{"city":"London"}
    }
  }'

Call Tool (get-forecast) - Requires mcp:read scope

curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "jsonrpc":"2.0",
    "id":4,
    "method":"tools/call",
    "params":{
      "name":"get-forecast",
      "arguments":{"city":"Tokyo"}
    }
  }'

Call Tool (get-weather-alerts) - Requires mcp:admin scope

curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "jsonrpc":"2.0",
    "id":5,
    "method":"tools/call",
    "params":{
      "name":"get-weather-alerts",
      "arguments":{"region":"California"}
    }
  }'

Available Tools

Tool Description Required Scope
get-weather Get current weather for a city None
get-forecast Get 5-day weather forecast mcp:read
get-weather-alerts Get weather alerts for a region mcp:admin

Authentication

When authentication is enabled, protected endpoints require a valid JWT bearer token:

curl -X POST http://localhost:3001/mcp \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The token can also be passed as a query parameter:

curl -X POST "http://localhost:3001/mcp?access_token=eyJhbGciOiJSUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

License

MIT License