Build a Secure MCP Server with Keycloak, Go, and RFC 8693 Token Exchange (Part 1)

User: "What's the status of order ord_123?"
 
Claude uses the standard token
→ Gateway forwards the request
→ API validates orders:read
→ Success
 
User: "Cancel order ord_123"
 
Claude uses the standard token
→ API rejects it (no write scope)
 
Claude exchanges the token at Keycloak
→ gets a narrow, short-lived orders:cancel token
→ Gateway retries the call
→ API validates scope, audience, and actor
→ Success

go version           # 1.22 or newer for net/http PathValue
docker version       # with Docker Compose v2
curl --version
jq --version

curl -sL https://agentgateway.dev/install | bash
agentgateway --version

mkdir -p mcp-token-tiering/{cmd/order-api,cmd/orders-mcp,config,keycloak}
cd mcp-token-tiering
go mod init example.com/mcp-token-tiering
go get github.com/golang-jwt/jwt/v5
go get github.com/MicahParks/keyfunc/v3
go get github.com/modelcontextprotocol/go-sdk/mcp

{
  "realm": "mcp-demo",
  "enabled": true,
  "accessTokenLifespan": 1800,
  "users": [
    {
      "username": "demo-user",
      "enabled": true,
      "email": "[email protected]",
      "emailVerified": true,
      "firstName": "Demo",
      "lastName": "User",
      "credentials": [
        { "type": "password", "value": "demo-password", "temporary": false }
      ]
    }
  ],
  "clientScopes": [
    {
      "name": "orders:read",
      "protocol": "openid-connect",
      "attributes": { "include.in.token.scope": "true" }
    },
    {
      "name": "orders:cancel",
      "protocol": "openid-connect",
      "attributes": { "include.in.token.scope": "true" },
      "protocolMappers": [
        {
          "name": "orders-api-audience",
          "protocol": "openid-connect",
          "protocolMapper": "oidc-audience-mapper",
          "config": {
            "included.client.audience": "orders-api",
            "access.token.claim": "true"
          }
        }
      ]
    }
  ],
  "clients": [
    {
      "clientId": "user-client",
      "name": "Normal CLI User",
      "enabled": true,
      "publicClient": true,
      "standardFlowEnabled": true,
      "directAccessGrantsEnabled": true,
      "redirectUris": ["http://localhost:3000/*"],
      "webOrigins": ["+"],
      "defaultClientScopes": ["profile", "email", "orders:read"],
      "optionalClientScopes": [],
      "protocolMappers": [
        {
          "name": "orders-agent-audience",
          "protocol": "openid-connect",
          "protocolMapper": "oidc-audience-mapper",
          "config": {
            "included.client.audience": "orders-agent",
            "access.token.claim": "true",
            "id.token.claim": "false"
          }
        }
      ]
    },
    {
      "clientId": "orders-agent",
      "name": "Agent exchange client",
      "enabled": true,
      "publicClient": false,
      "secret": "orders-agent-secret",
      "serviceAccountsEnabled": true,
      "standardFlowEnabled": false,
      "directAccessGrantsEnabled": false,
      "attributes": {
        "standard.token.exchange.enabled": "true",
        "access.token.lifespan": "120"
      },
      "defaultClientScopes": [],
      "optionalClientScopes": ["orders:cancel"]
    },
    {
      "clientId": "orders-api",
      "name": "Orders API audience",
      "enabled": true,
      "publicClient": false,
      "standardFlowEnabled": false,
      "directAccessGrantsEnabled": false,
      "serviceAccountsEnabled": false
    }
  ]
}

services:
  keycloak:
    image: quay.io/keycloak/keycloak:26.4
    command: ["start-dev", "--import-realm"]
    environment:
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: admin
    ports:
      - "8080:8080"
    volumes:
      - ./keycloak/realm-export.json:/opt/keycloak/data/import/realm-export.json:ro

docker compose up -d
curl -s http://localhost:8080/realms/mcp-demo/.well-known/openid-configuration | jq '.grant_types_supported'

docker compose down && docker compose up -d

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
mcp:
  port: 3000
policies:
  cors:
    allowOrigins:
      - "*"
    allowHeaders:
      - "*"
    exposeHeaders:
      - "Mcp-Session-Id"
targets:
  - name: orders
    mcp:
      host: http://localhost:9000/mcp

agentgateway -f config/agentgateway.yaml

[
  {
    "id": "ord_123",
    "owner": "demo-user",
    "status": "PROCESSING"
  },
  {
    "id": "ord_456",
    "owner": "demo-user",
    "status": "PROCESSING"
  }
]

package main
 
import (
	"context"
	"encoding/json"
	"errors"
	"log"
	"net/http"
	"os"
	"strings"
	"sync"
 
	"github.com/MicahParks/keyfunc/v3"
	"github.com/golang-jwt/jwt/v5"
)
 
type claims map[string]any
 
type order struct {
	ID    string `json:"id"`
	Owner string `json:"owner"`
	Status string `json:"status"`
}
 
type orderStore struct {
	mu     sync.Mutex
	orders map[string]*order
}
 
func loadOrders(path string) (*orderStore, error) {
	data, err := os.ReadFile(path)
	if err != nil {
		return nil, err
	}
 
	var list []*order
	if err := json.Unmarshal(data, &list); err != nil {
		return nil, err
	}
 
	store := &orderStore{orders: make(map[string]*order, len(list))}
	for _, o := range list {
		store.orders[o.ID] = o
	}
 
	return store, nil
}
 
func (s *orderStore) get(id string) (*order, bool) {
	s.mu.Lock()
	defer s.mu.Unlock()
	o, ok := s.orders[id]
	return o, ok
}
 
func (s *orderStore) cancel(id string) (*order, bool) {
	s.mu.Lock()
	defer s.mu.Unlock()
	o, ok := s.orders[id]
	if !ok {
		return nil, false
	}
 
	o.Status = "CANCELLED"
	return o, true
}
 
var (
	store  *orderStore
	jwks   keyfunc.Keyfunc
	issuer string
)
 
func envOr(key, fallback string) string {
	if v := os.Getenv(key); v != "" {
		return v
	}
	return fallback
}
 
func parseBearer(r *http.Request) (claims, error) {
	auth := r.Header.Get("Authorization")
	if !strings.HasPrefix(auth, "Bearer ") {
		return nil, errors.New("missing bearer token")
	}
 
	raw := strings.TrimPrefix(auth, "Bearer ")
	token, err := jwt.Parse(raw, jwks.Keyfunc,
		jwt.WithIssuer(issuer),
		jwt.WithExpirationRequired(),
		jwt.WithValidMethods([]string{"RS256", "ES256"}),
	)
 
	if err != nil || !token.Valid {
		return nil, errors.New("invalid token")
	}
 
	mc, ok := token.Claims.(jwt.MapClaims)
	if !ok {
		return nil, errors.New("invalid claims")
	}
 
	out := claims{}
	for k, v := range mc {
		out[k] = v
	}
 
	return out, nil
}
 
func claimString(c claims, name string) string {
	v, _ := c[name].(string)
	return v
}
 
func hasScope(c claims, wanted string) bool {
	for _, scope := range strings.Fields(claimString(c, "scope")) {
		if scope == wanted {
			return true
		}
	}
	return false
}
 
func audienceOK(c claims, wanted string) bool {
	switch aud := c["aud"].(type) {
	case string:
		return aud == wanted
	case []any:
		for _, item := range aud {
			if s, ok := item.(string); ok && s == wanted {
				return true
			}
		}
	}
	return false
}
 
// actorIdentity returns the agent identity from the token.
// Preferred: the RFC 8693 act claim, from an STS that supports delegation.
// Fallback: the azp claim, which Keycloak V2 sets to the client that performed the exchange.
func actorIdentity(c claims) string {
	if act, ok := c["act"].(map[string]any); ok {
		if sub, _ := act["sub"].(string); sub != "" {
			return sub
		}
	}
 
	if azp := claimString(c, "azp"); azp == "orders-agent" {
		return "client:" + azp
	}
 
	return ""
}
 
func writeJSON(w http.ResponseWriter, status int, body any) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	_ = json.NewEncoder(w).Encode(body)
}
 
func getOrderStatus(w http.ResponseWriter, r *http.Request) {
	c, err := parseBearer(r)
	if err != nil {
		log.Printf("read order=%s rejected: %v", r.PathValue("id"), err)
		writeJSON(w, http.StatusUnauthorized, map[string]any{"error": err.Error()})
		return
	}
 
	if !hasScope(c, "orders:read") && !hasScope(c, "orders:cancel") {
		log.Printf("read order=%s sub=%v denied: missing read scope", r.PathValue("id"), c["sub"])
		writeJSON(w, http.StatusForbidden, map[string]any{"error": "orders:read scope required"})
		return
	}
 
	o, ok := store.get(r.PathValue("id"))
	if !ok {
		writeJSON(w, http.StatusNotFound, map[string]any{"error": "order not found"})
		return
	}
 
	log.Printf("read order=%s sub=%v scope=%q allowed", o.ID, c["sub"], c["scope"])
	writeJSON(w, http.StatusOK, map[string]any{
		"orderId": o.ID,
		"status": o.Status,
		"subject": c["sub"],
		"scope": c["scope"],
	})
}
 
func cancelOrder(w http.ResponseWriter, r *http.Request) {
	c, err := parseBearer(r)
	if err != nil {
		log.Printf("cancel order=%s rejected: %v", r.PathValue("id"), err)
		writeJSON(w, http.StatusUnauthorized, map[string]any{"error": err.Error()})
		return
	}
 
	actor := actorIdentity(c)
	switch {
	case !hasScope(c, "orders:cancel"):
		log.Printf("cancel order=%s sub=%v denied: missing cancel scope", r.PathValue("id"), c["sub"])
		writeJSON(w, http.StatusForbidden, map[string]any{"error": "orders:cancel scope required"})
 
	case !audienceOK(c, "orders-api"):
		log.Printf("cancel order=%s sub=%v denied: wrong audience", r.PathValue("id"), c["sub"])
		writeJSON(w, http.StatusForbidden, map[string]any{"error": "orders-api audience required"})
 
	case actor == "":
		log.Printf("cancel order=%s sub=%v denied: no actor identity", r.PathValue("id"), c["sub"])
		writeJSON(w, http.StatusForbidden, map[string]any{"error": "actor identity required"})
 
	default:
		o, ok := store.get(r.PathValue("id"))
		if !ok {
			writeJSON(w, http.StatusNotFound, map[string]any{"error": "order not found"})
			return
		}
 
		if o.Status == "CANCELLED" {
			log.Printf("cancel order=%s sub=%v actor=%s conflict: already cancelled", o.ID, c["sub"], actor)
			writeJSON(w, http.StatusConflict, map[string]any{"error": "order already cancelled"})
			return
		}
 
		updated, _ := store.cancel(r.PathValue("id"))
		log.Printf("cancel order=%s sub=%v actor=%s allowed", updated.ID, c["sub"], actor)
		writeJSON(w, http.StatusOK, map[string]any{
			"orderId": updated.ID,
			"status": updated.Status,
			"subject": c["sub"],
			"actor": actor,
		})
	}
}
 
func main() {
	issuer = envOr("OIDC_ISSUER", "http://localhost:8080/realms/mcp-demo")
	jwksURL := envOr("JWKS_URL", issuer+"/protocol/openid-connect/certs")
	ordersPath := envOr("ORDERS_FILE", "orders.json")
 
	var err error
	store, err = loadOrders(ordersPath)
	if err != nil {
		log.Fatalf("failed to load orders from %s: %v", ordersPath, err)
	}
 
	jwks, err = keyfunc.NewDefaultCtx(context.Background(), []string{jwksURL})
	if err != nil {
		log.Fatalf("failed to load JWKS from %s: %v", jwksURL, err)
	}
 
	mux := http.NewServeMux()
	mux.HandleFunc("GET /orders/{id}", getOrderStatus)
	mux.HandleFunc("POST /orders/{id}/cancel", cancelOrder)
 
	log.Println("Order API listening on http://localhost:9100")
	log.Fatal(http.ListenAndServe("127.0.0.1:9100", mux))
}

package main
 
import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
 
	"github.com/modelcontextprotocol/go-sdk/mcp"
)
 
type OrderInput struct {
	OrderID string `json:"orderId" jsonschema:"order ID, for example ord_123"`
}
 
type ToolOutput struct {
	Status int            `json:"status"`
	Body   map[string]any `json:"body"`
}
 
func callJSON(ctx context.Context, method, url, bearer string) (ToolOutput, error) {
	req, err := http.NewRequestWithContext(ctx, method, url, bytes.NewReader([]byte("{}")))
	if err != nil {
		return ToolOutput{}, err
	}
 
	req.Header.Set("Authorization", bearer)
	req.Header.Set("Content-Type", "application/json")
 
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return ToolOutput{}, err
	}
	defer resp.Body.Close()
 
	raw, _ := io.ReadAll(resp.Body)
	log.Printf("forward %s %s -> %d", method, url, resp.StatusCode)
 
	var parsed map[string]any
	if err := json.Unmarshal(raw, &parsed); err != nil {
		parsed = map[string]any{"raw": string(raw)}
	}
 
	out := ToolOutput{Status: resp.StatusCode, Body: parsed}
	if resp.StatusCode >= 400 {
		return out, fmt.Errorf("downstream API rejected call: %s", string(raw))
	}
 
	return out, nil
}
 
func newOrdersMCPServer(orderAPI string, bearer string) *mcp.Server {
	server := mcp.NewServer(&mcp.Implementation{
		Name:    "orders-mcp",
		Version: "v0.1.0",
	}, nil)
 
	mcp.AddTool(
		server,
		&mcp.Tool{
			Name:        "get_order_status",
			Description: "Read order status. Low-risk read tool. Requires orders:read.",
		},
		func(ctx context.Context, req *mcp.CallToolRequest, input OrderInput) (*mcp.CallToolResult, ToolOutput, error) {
			out, err := callJSON(ctx, http.MethodGet, orderAPI+"/orders/"+input.OrderID, bearer)
			return nil, out, err
		},
	)
 
	mcp.AddTool(
		server,
		&mcp.Tool{
			Name:        "cancel_order",
			Description: "Cancel an order. Write tool. Requires an exchanged token with orders:cancel.",
		},
		func(ctx context.Context, req *mcp.CallToolRequest, input OrderInput) (*mcp.CallToolResult, ToolOutput, error) {
			out, err := callJSON(ctx, http.MethodPost, orderAPI+"/orders/"+input.OrderID+"/cancel", bearer)
			return nil, out, err
		},
	)
 
	return server
}
 
func main() {
	orderAPI := os.Getenv("ORDER_API")
	if orderAPI == "" {
		orderAPI = "http://localhost:9100"
	}
 
	handler := mcp.NewStreamableHTTPHandler(
		func(r *http.Request) *mcp.Server {
			return newOrdersMCPServer(orderAPI, r.Header.Get("Authorization"))
		},
		&mcp.StreamableHTTPOptions{
			JSONResponse: true,
			Stateless:    true,
		},
	)
 
	mux := http.NewServeMux()
	mux.Handle("/mcp", handler)
 
	log.Println("Orders MCP server listening on http://localhost:9000/mcp")
	log.Fatal(http.ListenAndServe("127.0.0.1:9000", mux))
}

export ORDERS_FILE="cmd/order-api/orders.json"
go run ./cmd/order-api

export ORDER_API="http://localhost:9100"
go run ./cmd/orders-mcp

export KC_TOKEN="http://localhost:8080/realms/mcp-demo/protocol/openid-connect/token"
 
decode_jwt() {
  local payload
  payload=$(printf '%s' "$1" | cut -d. -f2 | tr '_-' '/+')
  while [ $((${#payload} % 4)) -ne 0 ]; do payload="${payload}="; done
  printf '%s' "$payload" | base64 -d
}

RESP=$(
  curl -s -X POST "$KC_TOKEN" \
    -d "grant_type=password" \
    -d "client_id=user-client" \
    -d "username=demo-user" \
    -d "password=demo-password"
)
 
echo "$RESP" | jq .
export STANDARD_TOKEN=$(echo "$RESP" | jq -r .access_token)

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlZ3UlQyVjBGQzBVRUUzVT1zVEFpVQ==...",
  "expires_in": 1800,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlZ3UlQyVjBGQzBVRUUzVT1zVEFpVQ==...",
  "token_type": "Bearer",
  "session_state": "ab443036-a0b6-ff5e-8485-a81f3c05375a",
  "scope": "orders:read"
}

decode_jwt "$STANDARD_TOKEN" | jq '{sub, azp, scope, aud}'

{
  "sub": null,
  "azp": "user-client",
  "scope": "orders:read",
  "aud": "orders-agent"
}

RESP=$(
  curl -s -i -X POST "http://localhost:3000/mcp/http" \
    -H "authorization: Bearer ${STANDARD_TOKEN}" \
    -H "content-type: application/json" \
    -H "accept: application/json, text/event-stream" \
    -d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "initialize",
      "params": {
        "protocolVersion": "2025-11-25",
        "capabilities": {},
        "clientInfo": { "name": "curl", "version": "0.1.0" }
      }
    }'
)
 
echo "$RESP"
export SESSION=$(echo "$RESP" | grep -i '^mcp-session-id:' | tr -d '\r' | awk '{print $2}')

curl -s -X POST "http://localhost:3000/mcp/http" \
  -H "authorization: Bearer ${STANDARD_TOKEN}" \
  -H "mcp-session-id: ${SESSION}" \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_order_status",
      "arguments": { "orderId": "ord_123" }
    }
  }' | grep '^data:' | sed 's/^data: //' | jq

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"body\":{\"orderId\":\"ord_123\",\"scope\":\"orders:read\",\"status\":\"PROCESSING\",\"subject\":null},\"status\":200}"
      }
    ],
    "structuredContent": {
      "body": {
        "orderId": "ord_123",
        "scope": "orders:read",
        "status": "PROCESSING",
        "subject": null
      },
      "status": 200
    }
  }
}

curl -s -X POST "http://localhost:3000/mcp/http" \
  -H "authorization: Bearer ${STANDARD_TOKEN}" \
  -H "mcp-session-id: ${SESSION}" \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "cancel_order",
      "arguments": { "orderId": "ord_123" }
    }
  }' | grep '^data:' | sed 's/^data: //' | jq

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "downstream API rejected call: {\"error\":\"orders:cancel scope required\"}\n"
      }
    ],
    "isError": true
  }
}

decode_jwt "$STANDARD_TOKEN" | jq '.aud'

RESP=$(
  curl -s -X POST "$KC_TOKEN" \
    -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    -d "client_id=orders-agent" \
    -d "client_secret=orders-agent-secret" \
    -d "subject_token=${STANDARD_TOKEN}" \
    -d "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
    -d "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
    -d "audience=orders-api" \
    -d "scope=orders:cancel"
)
 
echo "$RESP" | jq .
export WRITE_TOKEN=$(echo "$RESP" | jq -r .access_token)

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJXd2tldUZPTzk4Y0taWG1sWFY4eXJHZk5Cc0x5blRpdFhjdTNZTTdtNXdjIn0...",
  "expires_in": 120,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "ab443036-a0b6-ff5e-8485-a81f3c05375a",
  "scope": "orders:cancel",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}

curl -s -X POST "http://localhost:3000/mcp/http" \
  -H "authorization: Bearer ${WRITE_TOKEN}" \
  -H "mcp-session-id: ${SESSION}" \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "cancel_order",
      "arguments": { "orderId": "ord_123" }
    }
  }' | grep '^data:' | sed 's/^data: //' | jq

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"body\":{\"actor\":\"client:orders-agent\",\"orderId\":\"ord_123\",\"status\":\"CANCELLED\",\"subject\":\"1db033bd-8186-4de0-864d-a42b56b25cbb\"},\"status\":200}"
      }
    ],
    "structuredContent": {
      "body": {
        "actor": "client:orders-agent",
        "orderId": "ord_123",
        "status": "CANCELLED",
        "subject": "1db033bd-8186-4de0-864d-a42b56b25cbb"
      },
      "status": 200
    }
  }
}

sleep 120

curl -s -X POST "http://localhost:3000/mcp/http" \
  -H "authorization: Bearer ${WRITE_TOKEN}" \
  -H "mcp-session-id: ${SESSION}" \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "cancel_order",
      "arguments": { "orderId": "ord_456" }
    }
  }' | grep '^data:' | sed 's/^data: //' | jq

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "downstream API rejected call: {\"error\":\"invalid token\"}\n"
      }
    ],
    "isError": true
  }
}

decode_jwt "$STANDARD_TOKEN" | jq '{sub, azp, scope, aud}'
decode_jwt "$WRITE_TOKEN" | jq '{sub, azp, scope, aud, iat, exp}'

{
  "sub": "<demo-user id>",
  "azp": "orders-agent",
  "scope": "orders:cancel",
  "aud": "orders-api",
  "iat": 1783411200,
  "exp": 1783411320
}