MCP-313 Support SONARQUBE_TOOLSETS and SONARQUBE_READ_ONLY headers (#235)

Author: nquinquenel

README.md

@@ -535,8 +535,8 @@ By default, only important toolsets are enabled to reduce context overhead. You
 
 | Environment variable   | Description                                                                                                                                                                                                                                    |
 |------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `SONARQUBE_TOOLSETS`   | Comma-separated list of toolsets to enable. When set, only these toolsets will be available. If not set, default important toolsets are enabled (`analysis`, `issues`, `projects`, `quality-gates`, `rules`, `duplications`, `measures`, `security-hotspots`, `dependency-risks`). **Note:** The `projects` toolset is always enabled as it's required to find project keys for other operations. |
-| `SONARQUBE_READ_ONLY`  | When set to `true`, enables read-only mode which disables all write operations (changing issue status for example). This filter is cumulative with `SONARQUBE_TOOLSETS` if both are set. Default: `false`.                                     |
+| `SONARQUBE_TOOLSETS`   | Comma-separated list of toolsets to enable. When set, only these toolsets will be available. If not set, default important toolsets are enabled (`analysis`, `issues`, `projects`, `quality-gates`, `rules`, `duplications`, `measures`, `security-hotspots`, `dependency-risks`). **Note:** The `projects` toolset is always enabled as it's required to find project keys for other operations. In HTTP(S) mode, clients can send a `SONARQUBE_TOOLSETS` HTTP header to narrow this further per-request, but cannot enable toolsets beyond what the server was launched with (see [HTTP/HTTPS Transport](#2-http) below). |
+| `SONARQUBE_READ_ONLY`  | When set to `true`, enables read-only mode which disables all write operations (changing issue status for example). This filter is cumulative with `SONARQUBE_TOOLSETS` if both are set. Default: `false`. In HTTP(S) mode, clients can send a `SONARQUBE_READ_ONLY` HTTP header to further restrict individual requests to read-only, but cannot lift a server-level read-only restriction (see [HTTP/HTTPS Transport](#2-http) below). |
 
 <details>
 <summary>Available Toolsets</summary>
@@ -648,7 +648,7 @@ Unencrypted HTTP transport. Use HTTPS instead for multi-user deployments.
 **Note:** In HTTP(S) mode, the server is stateless — each client request must include a `SONARQUBE_TOKEN` header carrying the user's own SonarQube token. For SonarQube Cloud, the organization is resolved as follows:
 - If `SONARQUBE_ORG` is set at server startup, all requests are routed to that organization. Clients must **not** send a `SONARQUBE_ORG` header — doing so will result in an error.
 - If `SONARQUBE_ORG` is not set at server startup, each client **must** supply a `SONARQUBE_ORG` header on every request.
-
+Clients can also narrow the visible tools per-request by supplying `SONARQUBE_TOOLSETS` and/or `SONARQUBE_READ_ONLY` headers; these apply additional filtering on top of the server-level configuration — they can only reduce the scope, never expand it.
 No session state is maintained between requests.
 
 #### 3. **HTTPS** (Recommended for Multi-User Production Deployments)
@@ -689,7 +689,9 @@ docker run --init --pull=always -p 8443:8443 \
       "url": "https://your-server:8443/mcp",
       "headers": {
         "SONARQUBE_TOKEN": "<your-token>",
-        "SONARQUBE_ORG": "<your-org>"
+        "SONARQUBE_ORG": "<your-org>",
+        "SONARQUBE_TOOLSETS": "issues,quality-gates",
+        "SONARQUBE_READ_ONLY": "true"
       }
     }
   }
@@ -703,13 +705,17 @@ docker run --init --pull=always -p 8443:8443 \
     "sonarqube-https": {
       "url": "https://your-server:8443/mcp",
       "headers": {
-        "SONARQUBE_TOKEN": "<your-token>"
+        "SONARQUBE_TOKEN": "<your-token>",
+        "SONARQUBE_TOOLSETS": "issues,quality-gates",
+        "SONARQUBE_READ_ONLY": "true"
       }
     }
   }
 }
 ```
 
+> **Note:** `SONARQUBE_TOOLSETS` and `SONARQUBE_READ_ONLY` are optional per-request headers that narrow the server-level tool set for that specific request. They can only reduce scope — they cannot enable toolsets or lift restrictions beyond what the server was launched with.
+
 **Note:** For local development, use Stdio transport instead (the default). HTTPS is intended for multi-user production deployments with proper SSL certificates.
 
 ### Custom Certificates

docs/http-authentication-architecture.md

@@ -8,7 +8,8 @@
 2. [Architecture Components](#architecture-components)
 3. [Authentication Flow](#authentication-flow)
 4. [Token Propagation](#token-propagation)
-5. [Security Considerations](#security-considerations)
+5. [Per-Request Tool Filtering](#per-request-tool-filtering)
+6. [Security Considerations](#security-considerations)
 
 ---
 
@@ -34,7 +35,10 @@ This document focuses on the **HTTP/HTTPS Transport** and its authentication mec
 │            (Cursor, VS Code, etc.)                  │
 └────────────────┬────────────────────────────────────┘
                  │ HTTP POST
-                 │ Headers: SONARQUBE_TOKEN (required), SONARQUBE_ORG (optional, SQC only)
+                 │ Headers: SONARQUBE_TOKEN (required)
+                 │          SONARQUBE_ORG (optional, SQC only)
+                 │          SONARQUBE_TOOLSETS (optional, per-request override)
+                 │          SONARQUBE_READ_ONLY (optional, per-request override)
                  ▼
 ┌─────────────────────────────────────────────────────┐
 │              Jetty HTTP Server                      │
@@ -44,40 +48,51 @@ This document focuses on the **HTTP/HTTPS Transport** and its authentication mec
                  ▼
 ┌─────────────────────────────────────────────────────┐
 │            Servlet Filter Chain                     │
-│  1. AuthenticationFilter (token validation)         │
-│  2. McpSecurityFilter (CORS + Origin validation)    │
+│  1. McpSecurityFilter (CORS + Origin validation)    │
+│  2. AuthenticationFilter (token validation)         │
 └────────────────┬────────────────────────────────────┘
                  │
                  ▼
 ┌─────────────────────────────────────────────────────┐
 │     HttpServletStatelessServerTransport             │
-│   (MCP SDK - stateless, extracts McpTransportCtx)  │
+│   (MCP SDK - stateless, extracts McpTransportCtx)   │
+└────────────────┬────────────────────────────────────┘
+                 │
+                 ▼
+┌─────────────────────────────────────────────────────┐
+│       PerRequestToolFilteringHandler                │
+│  (per-request tools/list filtering)                 │
 └────────────────┬────────────────────────────────────┘
                  │
                  ▼
 ┌─────────────────────────────────────────────────────┐
 │            MCP Tool Execution                       │
-│  (reads token from McpTransportContext ThreadLocal) │
+│  (reads token + toolset filters from                │
+│   McpTransportContext ThreadLocal)                  │
 └─────────────────────────────────────────────────────┘
 ```
 
 ### 2. Key Classes
 
 #### `HttpServerTransportProvider`
 - **Location**: `org.sonarsource.sonarqube.mcp.transport.HttpServerTransportProvider`
-- **Purpose**: Bootstraps Jetty server and configures the stateless servlet transport with a context extractor that reads the `SONARQUBE_TOKEN` header into a `McpTransportContext` for each request
+- **Purpose**: Bootstraps Jetty server and configures the stateless servlet transport with a context extractor that reads `SONARQUBE_TOKEN`, `SONARQUBE_ORG`, `SONARQUBE_TOOLSETS`, and `SONARQUBE_READ_ONLY` headers into a `McpTransportContext` for each request
 
 #### `AuthenticationFilter`
 - **Location**: `org.sonarsource.sonarqube.mcp.authentication.AuthenticationFilter`
-- **Purpose**: Validates that every request carries a non-blank `SONARQUBE_TOKEN` header. No session state is created or maintained.
+- **Purpose**: Validates that every request carries a non-blank `SONARQUBE_TOKEN` header. No session state is created or maintained. Runs **after** `McpSecurityFilter` so CORS preflight (OPTIONS) requests and Origin validation are handled before authentication, allowing browsers to complete their preflight handshake without a token.
 
 #### `McpSecurityFilter`
 - **Location**: `org.sonarsource.sonarqube.mcp.transport.McpSecurityFilter`
-- **Purpose**: Security and CORS handling
+- **Purpose**: Security and CORS handling (Origin validation, CORS headers)
+
+#### `PerRequestToolFilteringHandler`
+- **Location**: `org.sonarsource.sonarqube.mcp.transport.PerRequestToolFilteringHandler`
+- **Purpose**: Wraps the SDK's `McpStatelessServerHandler` to intercept `tools/list` responses and filter the returned tool list based on the per-request `SONARQUBE_TOOLSETS` and `SONARQUBE_READ_ONLY` headers from `McpTransportContext`. A well-behaved MCP client will only call tools it received from `tools/list`, so filtering the list is sufficient enforcement.
 
 #### `SonarQubeMcpServer` (ServerApiProvider)
 - **Location**: `org.sonarsource.sonarqube.mcp.SonarQubeMcpServer`
-- **Purpose**: In HTTP stateless mode, reads the current request's `McpTransportContext` from a `ThreadLocal` to extract the token and create a per-request `ServerApi` instance
+- **Purpose**: In HTTP stateless mode, reads the current request's `McpTransportContext` from a `ThreadLocal` to extract the token and create a per-request `ServerApi` instance.
 
 ---
 
@@ -103,26 +118,38 @@ Clients configure the HTTP endpoint with authentication:
 ### 2. Request Flow
 
 ```
-1. Client sends HTTP POST with token header
-   └─> SONARQUBE_TOKEN: squ_abc123
+1. Client sends HTTP POST with headers
+   └─> SONARQUBE_TOKEN: squ_abc123          (required)
+   └─> SONARQUBE_ORG: my-org                (optional, SQC only)
+   └─> SONARQUBE_TOOLSETS: issues,rules     (optional, per-request override)
+   └─> SONARQUBE_READ_ONLY: true            (optional, per-request override)
+
+2. McpSecurityFilter validates security
+   ├─> Allow OPTIONS preflight without authentication (enables CORS handshake)
+   ├─> Check Origin header
+   ├─> Set CORS headers
+   └─> Pass to next filter
 
-2. AuthenticationFilter intercepts request
+3. AuthenticationFilter intercepts request
    ├─> Extract token from SONARQUBE_TOKEN header
    ├─> Reject with 401 if token is missing or blank
-   └─> Pass to next filter if token is present
-
-3. McpSecurityFilter validates security
-   ├─> Check Origin header
-   ├─> Set CORS headers
-   └─> Pass to servlet
+   ├─> Validate SONARQUBE_ORG header (SonarQube Cloud only)
+   ├─> Validate SONARQUBE_READ_ONLY header (must be 'true' or 'false' if present)
+   └─> Pass to servlet if all checks pass
 
 4. HttpServletStatelessServerTransport processes request
-   ├─> contextExtractor runs: reads SONARQUBE_TOKEN header
-   ├─> Creates McpTransportContext with the token value
+   ├─> contextExtractor runs: reads SONARQUBE_TOKEN, SONARQUBE_ORG,
+   │   SONARQUBE_TOOLSETS, and SONARQUBE_READ_ONLY headers
+   ├─> Creates McpTransportContext with all extracted values
    ├─> Parse JSON-RPC message
-   └─> Dispatch to tool handler (context available via ThreadLocal)
+   └─> Dispatch to PerRequestToolFilteringHandler
 
-5. Tool execution (ServerApiProvider.get())
+5. PerRequestToolFilteringHandler (tools/list only)
+   ├─> Read SONARQUBE_TOOLSETS and SONARQUBE_READ_ONLY from McpTransportContext
+   ├─> If per-request headers are present, filter tool list accordingly
+   └─> Return filtered tools/list response (bypasses SDK's unfiltered response)
+
+6. Tool execution - tools/call (ServerApiProvider.get())
    ├─> Read McpTransportContext from ThreadLocal
    ├─> Extract CONTEXT_TOKEN_KEY value
    ├─> Resolve org: use server-level env var (header must be absent) OR per-request header (required if env var not set)
@@ -138,6 +165,8 @@ Clients configure the HTTP endpoint with authentication:
 - Uses custom header format:
   - `SONARQUBE_TOKEN: <token>` — required on every request
   - `SONARQUBE_ORG: <org>` — for SonarQube Cloud, identifies the organization. **Mutually exclusive with the server-level `SONARQUBE_ORG` env var**: if the env var is set at startup, clients must not send this header (results in an error); if the env var is not set, clients must send this header on every request
+  - `SONARQUBE_TOOLSETS: <comma-separated-keys>` — optional; narrows the server-level toolset for this request (cannot add toolsets beyond what the server was launched with)
+  - `SONARQUBE_READ_ONLY: true|false` — optional; can further restrict to read-only for this request (cannot lift a server-level read-only restriction)
 
 #### `OAUTH` Mode (Not Yet Implemented)
 - OAuth 2.1 with PKCE
@@ -156,13 +185,15 @@ The MCP SDK makes this context available via a `ThreadLocal<McpTransportContext>
 
 ```
 1. HTTP Request arrives
-   └─> contextExtractor reads SONARQUBE_TOKEN and SONARQUBE_ORG headers
+   └─> contextExtractor reads SONARQUBE_TOKEN, SONARQUBE_ORG,
+       SONARQUBE_TOOLSETS, and SONARQUBE_READ_ONLY headers
    └─> McpTransportContext stored in ThreadLocal for this request thread
 
-2. Tool Execution Handler
-   └─> ThreadLocal<McpTransportContext> is already populated by the SDK
+2. PerRequestToolFilteringHandler (tools/list only)
+   └─> Reads SONARQUBE_TOOLSETS and SONARQUBE_READ_ONLY from McpTransportContext
+   └─> Filters the SDK's full tool list down to the per-request allowed subset
 
-3. ServerApiProvider.get()
+3. ServerApiProvider.get() (tools/call)
    └─> Reads McpTransportContext from ThreadLocal
    └─> Extracts token and org (strict: server-level env var XOR per-request header — mixing both is an error)
    └─> Creates a fresh ServerApi for this request
@@ -177,6 +208,47 @@ The MCP SDK makes this context available via a `ThreadLocal<McpTransportContext>
 
 ---
 
+## Per-Request Tool Filtering
+
+In HTTP(S) mode, clients can **narrow** the set of visible tools on a per-request basis by sending optional HTTP headers. These headers apply additional filtering on top of the server-level `SONARQUBE_TOOLSETS` and `SONARQUBE_READ_ONLY` environment variables — they can only reduce the scope, never expand it:
+
+- If the server was launched with `SONARQUBE_READ_ONLY=true`, write tools are absent from the server's tool set and cannot be re-enabled per-request.
+- If the server was launched with a restricted `SONARQUBE_TOOLSETS`, per-request headers can select a subset of those toolsets, but cannot add toolsets beyond what the server was launched with.
+
+### Headers
+
+| Header | Description |
+|--------|-------------|
+| `SONARQUBE_TOOLSETS` | Comma-separated list of toolset keys to enable for this request (e.g., `issues,quality-gates`). Must be a subset of the server-level `SONARQUBE_TOOLSETS`; toolsets not enabled at server startup are silently ignored. The `projects` toolset is always included regardless of this header. |
+| `SONARQUBE_READ_ONLY` | Set to `true` to restrict this request to read-only tools only. Has no effect if the server was already launched with `SONARQUBE_READ_ONLY=true` (write tools are already absent). |
+
+### Filtering
+
+Per-request filtering is applied at the **`tools/list` response**: `PerRequestToolFilteringHandler` intercepts the SDK's response and removes tools that are not allowed for this request. The MCP client only sees tools it is permitted to use, reducing its context window accordingly. A well-behaved MCP client will only call tools it received from `tools/list`, so filtering the list is sufficient.
+
+### Security Notes
+
+- The `SONARQUBE_TOOLSETS` and `SONARQUBE_READ_ONLY` headers are **not** authentication headers. They are read by the SDK's `contextExtractor` inside the servlet — which only runs after both `McpSecurityFilter` and `AuthenticationFilter` have passed the request through. An unauthenticated request is rejected with HTTP 401 by `AuthenticationFilter` before the `contextExtractor` (and thus any filtering logic) runs.
+- The raw header values are **never** echoed back in responses or error messages. Invalid toolset keys are silently discarded by `ToolCategory.parseCategories()`, preventing any header injection via error payloads.
+
+### Example Client Configuration
+
+```json
+{
+  "mcpServers": {
+    "sonarqube-https": {
+      "url": "https://your-server:8443/mcp",
+      "headers": {
+        "SONARQUBE_TOKEN": "<your-token>",
+        "SONARQUBE_ORG": "<your-org>",
+        "SONARQUBE_TOOLSETS": "issues,quality-gates",
+        "SONARQUBE_READ_ONLY": "true"
+      }
+    }
+  }
+}
+```
+
 ## Security Considerations
 
 ### DNS Rebinding Protection

src/main/java/org/sonarsource/sonarqube/mcp/SonarQubeMcpServer.java

@@ -165,11 +165,12 @@ public SonarQubeMcpServer(Map<String, String> environment) {
   public void start() {
     if (httpServerManager != null) {
       httpServerManager.startServer().join();
-      statelessSyncServer = McpServer.sync(httpServerManager.getTransportProvider())
+      var enabledTools = filterForEnabledTools(supportedTools);
+      statelessSyncServer = McpServer.sync(httpServerManager.getFilteringTransport(enabledTools))
         .serverInfo(new McpSchema.Implementation(SONARQUBE_MCP_SERVER_NAME, mcpConfiguration.getAppVersion()))
         .instructions(composedInstructions)
         .capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
-        .tools(filterForEnabledTools(supportedTools).stream().map(this::toStatelessSpec).toArray(McpStatelessServerFeatures.SyncToolSpecification[]::new))
+        .tools(enabledTools.stream().map(this::toStatelessSpec).toArray(McpStatelessServerFeatures.SyncToolSpecification[]::new))
         .build();
     } else {
       stdioSyncServer = McpServer.sync(transportProvider)