feat: Add MCP Inspector compatibility to Keycloak OAuth example

Enable MCP Inspector support for the Keycloak OAuth example by addressing
three key compatibility requirements:

1. CORS Configuration (server.py):
   - Add CORSMiddleware with proper headers for browser-based clients
   - Expose mcp-session-id header required for stateful HTTP transport
   - Configure allowed headers: mcp-protocol-version, mcp-session-id, Authorization
   - Reference: https://gofastmcp.com/deployment/http#cors-for-browser-based-clients

2. Trusted Hosts (realm-fastmcp.json):
   - Add github.com to trusted hosts for MCP Inspector origin
   - Enable dynamic client registration from Inspector's GitHub-hosted UI

3. Offline Access Support (realm-fastmcp.json):
   - Add defaultOptionalClientScopes: ["offline_access"]
   - Grant offline_access realm role to test user
   - Enable long-lived refresh tokens for Inspector sessions

Additional improvements:
- Remove FileTokenStorage in favor of automatic retry mechanism
- Disable audience validation by default (Keycloak doesn't include aud claim)
- Simplify realm configuration (minimal scopes: openid, profile, email, offline_access)
- Add comprehensive MCP Inspector documentation to README
- Update troubleshooting guide with Inspector-specific restart instructions
- Document Docker Compose v2 syntax and realm configuration reload process

Both Python client and MCP Inspector now work seamlessly with Keycloak OAuth.

Author: stephaneberle9

examples/auth/keycloak_auth/README.md

@@ -49,10 +49,41 @@ Manually import the realm:
    python server.py
    ```
 
-3. In another terminal, run the client:
+3. Test the server:
+
+   You have two options to test the OAuth-protected server:
+
+   **Option A: Using the Python Client (Programmatic)**
+
+   In another terminal, run the example client:
 
    ```bash
    python client.py
    ```
 
-The client will open your browser for Keycloak authentication.
+   The client will open your browser for Keycloak authentication, then demonstrate calling the protected tools.
+
+   **Option B: Using MCP Inspector (Interactive)**
+
+   The MCP Inspector provides an interactive web UI to explore and test your MCP server.
+
+   **Prerequisites**: Node.js must be installed on your system.
+
+   1. Launch the Inspector:
+      ```bash
+      npx -y @modelcontextprotocol/inspector
+      ```
+
+   2. In the Inspector UI (opens in your browser):
+      - Click "Add Server"
+      - Enter server URL: `http://localhost:8000/mcp`
+      - Select connection type: **"Direct"** (connects directly to the HTTP server)
+      - Click "Connect"
+      - The Inspector will automatically handle the OAuth flow and open Keycloak for authentication
+      - Once authenticated, you can interactively explore available tools and test them
+
+   The Inspector is particularly useful for:
+   - Exploring the server's capabilities without writing code
+   - Testing individual tools with custom inputs
+   - Debugging authentication and authorization issues
+   - Viewing request/response details

examples/auth/keycloak_auth/keycloak/README.md

@@ -23,22 +23,33 @@ This script will:
 
 ## Preconfigured Realm
 
-The Docker setup automatically imports a preconfigured realm configured for dynamic client registration. The default settings are described below and can be adjusted or complemented as needed by editing the [`realm-fastmcp.json`](realm-fastmcp.json) file before starting Keycloak. If settings are changed after Keycloak has been started, restart Keycloak with
+The Docker setup automatically imports a preconfigured realm configured for dynamic client registration. The default settings are described below and can be adjusted or complemented as needed by editing the [`realm-fastmcp.json`](realm-fastmcp.json) file before starting Keycloak.
+
+### Updating Realm Configuration
+
+If you modify the `realm-fastmcp.json` file after Keycloak has been started, you need to recreate the container to apply the changes:
 
 ```bash
-docker-compose restart
+docker compose down -v  # Stop and remove volumes
+docker compose up -d    # Start fresh with updated config
 ```
 
-to apply the changes.
+**Note**: The `-v` flag removes the volumes, which forces Keycloak to re-import the realm configuration. Without it, Keycloak will skip the import with "Realm already exists."
+
+**Expected Warning**: You may see this warning in the logs during realm import:
+```
+Failed to deserialize client policies in the realm fastmcp. Fallback to return empty profiles.
+```
+This is a harmless Keycloak parser issue with the JSON format and doesn't affect functionality. The realm and policies are imported correctly.
 
 ### Realm: `fastmcp`
 
 The realm is configured with:
 
 - **Dynamic Client Registration** enabled for `http://localhost:8000/*`
 - **Registration Allowed**: Yes
-- **Allowed Client Scopes**: `openid`, `profile`, `email`, `roles`, `offline_access`, `web-origins`, `basic`
-- **Trusted Hosts**: `localhost`, `172.17.0.1`, `172.18.0.1`
+- **Allowed Client Scopes**: `openid`, `profile`, `email`, `offline_access`
+- **Trusted Hosts**: `localhost`, `172.17.0.1`, `172.18.0.1`, `github.com` (allows MCP Inspector and other GitHub-hosted clients)
 
 ### Test User
 
@@ -91,7 +102,7 @@ For production use, consider:
 ### View Keycloak Logs
 
 ```bash
-docker-compose logs -f keycloak
+docker compose logs -f keycloak
 ```
 
 ### Common Issues
@@ -115,5 +126,5 @@ docker-compose logs -f keycloak
 
 4. **"Client not found" error after Keycloak restart**
    - This can happen when Keycloak is restarted and the previously registered OAuth client no longer exists
-   - **No action needed**: The FastMCP OAuth client automatically detects this condition and re-registers with Keycloak
-   - Simply run your client again and it will automatically handle the re-registration process
+   - **Python client**: No action needed - the FastMCP client automatically detects this condition and re-registers with Keycloak. Simply run your client again and it will handle the re-registration process.
+   - **MCP Inspector**: Stop the Inspector with Ctrl+C in the terminal where you started it, then restart it with `npx -y @modelcontextprotocol/inspector` and reconnect to the server. This triggers a fresh OAuth flow and client registration.

examples/auth/keycloak_auth/keycloak/realm-fastmcp.json

@@ -4,6 +4,7 @@
   "enabled": true,
   "keycloakVersion": "26.3.5",
   "registrationAllowed": true,
+  "defaultOptionalClientScopes": ["offline_access"],
   "components": {
     "org.keycloak.services.clientregistration.policy.ClientRegistrationPolicy": [
       {
@@ -18,7 +19,8 @@
           "trusted-hosts": [
             "localhost",
             "172.17.0.1",
-            "172.18.0.1"
+            "172.18.0.1",
+            "github.com"
           ],
           "client-uris-must-match": [
             "true"
@@ -41,7 +43,8 @@
           "value": "password123",
           "temporary": false
         }
-      ]
+      ],
+      "realmRoles": ["offline_access"]
     }
   ],
   "clientPolicies": {
@@ -57,10 +60,7 @@
                 "openid",
                 "profile",
                 "email",
-                "roles",
-                "offline_access",
-                "web-origins",
-                "basic"
+                "offline_access"
               ]
             }
           }

examples/auth/keycloak_auth/keycloak/start-keycloak.sh

@@ -84,4 +84,7 @@ echo ""
 echo "Useful commands:"
 echo "  • Check Keycloak logs: docker logs -f keycloak-fastmcp"
 echo "  • Stop Keycloak: $DOCKER_COMPOSE_DISPLAY down"
-echo "  • Restart Keycloak: $DOCKER_COMPOSE_DISPLAY restart"
+echo "  • Reload realm config: $DOCKER_COMPOSE_DISPLAY down -v && $DOCKER_COMPOSE_DISPLAY up -d"
+echo ""
+echo "⚠️  Note: To apply changes to realm-fastmcp.json, you must stop and remove volumes:"
+echo "    $DOCKER_COMPOSE_DISPLAY down -v && $DOCKER_COMPOSE_DISPLAY up -d"

examples/auth/keycloak_auth/server.py

@@ -17,6 +17,8 @@
 import os
 
 from dotenv import load_dotenv
+from starlette.middleware import Middleware
+from starlette.middleware.cors import CORSMiddleware
 
 from fastmcp import FastMCP
 from fastmcp.server.auth.providers.keycloak import KeycloakAuthProvider
@@ -75,7 +77,23 @@ async def get_access_token_claims() -> dict:
 
 if __name__ == "__main__":
     try:
-        mcp.run(transport="http", port=8000)
+        # Enable CORS for MCP Inspector and other browser-based clients
+        # See: https://gofastmcp.com/deployment/http#cors-for-browser-based-clients
+        cors_middleware = Middleware(
+            CORSMiddleware,
+            allow_origins=["*"],  # Allow all origins for development
+            allow_credentials=True,
+            allow_methods=["GET", "POST", "DELETE", "OPTIONS"],
+            allow_headers=[
+                "mcp-protocol-version",
+                "mcp-session-id",
+                "Authorization",
+                "Content-Type",
+            ],
+            expose_headers=["mcp-session-id"],  # Required for MCP Inspector
+        )
+
+        mcp.run(transport="http", port=8000, middleware=[cors_middleware])
     except KeyboardInterrupt:
         # Graceful shutdown, suppress noisy logs resulting from asyncio.run task cancellation propagation
         pass