implementation of the mcp-auth endpoint

Author: blublinsky

README.md

@@ -390,7 +390,7 @@ mcp_servers:
       Authorization: "kubernetes"    # Uses user's k8s token from request auth
 ```
 
-The user's Kubernetes token is extracted from the incoming request's `Authorization` header and forwarded to the MCP server.
+**Note:** Kubernetes token-based MCP authorization only works when Lightspeed Core Stack is configured with Kubernetes authentication (`authentication.k8s`). For any other authentication types, MCP servers configured with `Authorization: "kubernetes"` are removed from the available MCP servers list.
 
 ##### 3. Client-Provided Tokens (For Per-User Authentication)
 
@@ -418,6 +418,34 @@ curl -X POST "http://localhost:8080/v1/query" \
 
 **Structure**: `MCP-HEADERS: {"<server-name>": {"<header-name>": "<header-value>", ...}, ...}`
 
+##### Client-Authenticated MCP Servers Discovery
+
+To help clients determine which MCP servers require client-provided tokens, use the **MCP Client Auth Options** endpoint:
+
+```bash
+GET /v1/mcp-auth/client-options
+```
+
+**Response:**
+```json
+{
+  "servers": [
+    {
+      "name": "user-specific-service",
+      "client_auth_headers": ["Authorization", "X-User-Token"]
+    },
+    {
+      "name": "github-integration",
+      "client_auth_headers": ["Authorization"]
+    }
+  ]
+}
+```
+
+This endpoint returns only MCP servers configured with `authorization_headers: "client"`, along with the specific header names that need to be provided via `MCP-HEADERS`. Servers using file-based or Kubernetes authentication are not included in this response.
+
+**Use case:** Clients can call this endpoint at startup or before making requests to discover which servers they can authenticate with using their own tokens.
+
 ##### Combining Authentication Methods
 
 You can mix and match authentication methods across different MCP servers, and even combine multiple methods for a single server:

dev-tools/mcp-mock-server/Dockerfile

@@ -0,0 +1,15 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install curl for health checks
+RUN apt-get update && apt-get install -y --no-install-recommends curl && rm -rf /var/lib/apt/lists/*
+
+# Copy the mock server script
+COPY dev-tools/mcp-mock-server/server.py .
+
+# Expose HTTP port (we'll only use HTTP in Docker for simplicity)
+EXPOSE 3000
+
+# Run the mock server (HTTP only on port 3000)
+CMD ["python", "server.py", "3000"]

docker-compose-library.yaml

@@ -1,4 +1,21 @@
 services:
+  # Mock MCP server for testing
+  mcp-mock-server:
+    build:
+      context: .
+      dockerfile: dev-tools/mcp-mock-server/Dockerfile
+    container_name: mcp-mock-server
+    ports:
+      - "3000:3000"
+    networks:
+      - lightspeednet
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/"]
+      interval: 5s
+      timeout: 3s
+      retries: 3
+      start_period: 5s
+
   # Lightspeed Stack with embedded llama-stack (library mode)
   lightspeed-stack:
     build:
@@ -8,6 +25,11 @@ services:
     container_name: lightspeed-stack
     ports:
       - "8080:8080"
+    depends_on:
+      mcp-mock-server:
+        condition: service_healthy
+    networks:
+      - lightspeednet
     volumes:
       # Mount both config files - lightspeed-stack.yaml should have library mode enabled
       - ./lightspeed-stack.yaml:/app-root/lightspeed-stack.yaml:Z
@@ -48,3 +70,6 @@ services:
       retries: 3      # how many times to retry before marking as unhealthy
       start_period: 15s # time to wait before starting checks (increased for library initialization)
 
+networks:
+  lightspeednet:
+    driver: bridge

docker-compose.yaml

@@ -1,4 +1,21 @@
 services:
+  # Mock MCP server for testing
+  mcp-mock-server:
+    build:
+      context: .
+      dockerfile: dev-tools/mcp-mock-server/Dockerfile
+    container_name: mcp-mock-server
+    ports:
+      - "3000:3000"
+    networks:
+      - lightspeednet
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/"]
+      interval: 5s
+      timeout: 3s
+      retries: 3
+      start_period: 5s
+
   # Red Hat llama-stack distribution with FAISS
   llama-stack:
     build:
@@ -63,6 +80,8 @@ services:
     depends_on:
         llama-stack:
           condition: service_healthy
+        mcp-mock-server:
+          condition: service_healthy
     networks:
       - lightspeednet
     healthcheck: