@W-21952572: Add support for request level overrides

.cursor/rules/tools.mdc

@@ -68,7 +68,7 @@ Available in `extra` parameter:
 - `config` — server configuration
 - `server` — MCP Server instance
 - `tableauAuthInfo` — auth info (may be undefined for unauthenticated)
-- `getConfigWithOverrides()` — site-specific config overrides
+- `getConfigWithOverrides()` — config with site and request overrides applied
 - `getSiteLuid()` / `getUserLuid()` — resolved identifiers
 - `setSiteLuid()` / `setUserLuid()` — set during auth lifecycle
 - `requestId` — unique request identifier

docs/docs/configuration/mcp-config/README.md

@@ -9,3 +9,8 @@ Environment variables can be provided in many different ways, including:
 - AI tools via their MCP configuration.
 - [A variety of ways](https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables/)
   when running in Docker.
+
+Beyond environment variables, some configuration can be overridden at a more granular level:
+
+- **[Site Settings](site-settings.md)** — Override select configuration variables on a per-site basis via the REST API. Site settings are applied on top of environment variables for all users authenticated to the site.
+- **[Request Overrides](request-overrides.md)** — Override select configuration variables on a per-request basis via an HTTP header. Request overrides are applied on top of site settings and environment variables, and are only available when using the HTTP transport.

docs/docs/configuration/mcp-config/env-vars.md

@@ -175,15 +175,6 @@ data source][tab-connect-ds].
 
 <hr />
 
-## `ENABLE_MCP_SITE_SETTINGS`
-
-When `true`, the Tableau MCP server will fetch and apply site settings overrides for any user session, see [Site Settings](site-settings.md).
-
-- Default: `true`
-- When `false`, Tableau MCP server will not fetch or apply site settings overrides.
-
-<hr />
-
 ## `INCLUDE_TOOLS`
 
 A comma-separated list of tool or tool group names to include in the server. Only these tools will
@@ -219,7 +210,7 @@ The maximum timeout for requests to the Tableau Server REST API.
 
 The maximum number of results that every tool with a `limit` parameter can return when no
 tool-specific max result limit is set in the [`MAX_RESULT_LIMITS`](#max_result_limits)
-variable. This variable is site overridable, see [Site Settings](site-settings.md).
+variable. This variable is site and request overridable, see [Site Settings](site-settings.md) and [Request Overrides](request-overrides.md).
 
 :::warning
 
@@ -236,7 +227,7 @@ Take care when setting this value and be sure to set appropriate tool-specific l
 ## `MAX_RESULT_LIMITS`
 
 A comma-separated list of tool names (or tool group names) and the maximum number of results that
-each tool (or tools in the group) can return. This variable is site overridable, see [Site Settings](site-settings.md).
+each tool (or tools in the group) can return. This variable is site and request overridable, see [Site Settings](site-settings.md) and [Request Overrides](request-overrides.md).
 
 :::info
 
@@ -262,17 +253,17 @@ This means that:
 - Tool names take precedence over tool group names. That is, `datasource:1000,list-datasources:20`
   means that the `list-datasources` tool can return up to 20 data sources but the `query-datasource`
   tool can only return up to 1000 results.
-- If a tool-specific limit is not set, the global limit specified by the
+- If a tool is not included in the comma-separated list, the global limit specified by the
   [`MAX_RESULT_LIMIT`](#max_result_limit) variable will be used instead.
-- Each limit must be a positive number.
+- Each limit must be a positive number, or `*` to indicate unbounded results.
 
 <hr />
 
 ## `DISABLE_QUERY_DATASOURCE_VALIDATION_REQUESTS`
 
 Disables requests that are made to the VizQl Data Service for validating queries in the
 [`query-datasource`](../../tools/data-qna/query-datasource.md) tool. Does not disable the ability to
-query the datasource. This variable is site overridable, see [Site Settings](site-settings.md).
+query the datasource. This variable is site and request overridable, see [Site Settings](site-settings.md) and [Request Overrides](request-overrides.md).
 
 - Default: `false`
 - When `true`, skips validation of queries against metadata results and validation of SET and MATCH
@@ -297,7 +288,7 @@ Disable validation of SET and MATCH filter values in the
 
 Disables `graphql` requests to the Tableau Metadata API in the
 [`get-datasource-metadata`](../../tools/data-qna/get-datasource-metadata.md) tool.
-This variable is site overridable, see [Site Settings](site-settings.md).
+This variable is site and request overridable, see [Site Settings](site-settings.md) and [Request Overrides](request-overrides.md).
 
 - Default: `false`
 - When `true`, skips requests to the `graphql` endpoint that provides additional context to field
@@ -337,17 +328,6 @@ variable.
 
 <hr />
 
-## `MCP_SITE_SETTINGS_CHECK_INTERVAL_IN_MINUTES`
-
-When site settings are enabled by the Tableau MCP server, settings will be fetched for the given site and applied to each session.
-Rather than fetching site settings with every request, the MCP server will cache the settings and only check it again after the interval
-specified by this environment variable.
-
-- Default: `10` minutes
-- Must be a positive number between `1` and `1440` (1 day).
-
-<hr />
-
 ## `TELEMETRY_PROVIDER`
 
 The telemetry provider to use for metrics collection.

docs/docs/configuration/mcp-config/request-overrides.md

@@ -0,0 +1,160 @@
+---
+sidebar_position: 7
+---
+
+# Request Overrides
+
+Tableau MCP supports overriding certain configuration variables on a per-request basis via an HTTP header. This allows MCP clients to adjust server behavior for individual requests without changing the server's environment variables or site settings.
+
+Request overrides are only available when using the [HTTP transport](http-server.md).
+
+## Enabling Request Overrides
+
+Request overriding is disabled by default. To enable it, the Tableau MCP server must specify which variables are allowed to be overridden and their [restriction type](#restriction-types) using the `ALLOWED_REQUEST_OVERRIDES` variable.
+
+### `ALLOWED_REQUEST_OVERRIDES`
+
+A comma-separated list of allowed [request overridable variables](#request-overridable-variables) and their [restriction type](#restriction-types).
+This variable can be configured on a per-site basis when [`ALLOW_SITES_TO_CONFIGURE_REQUEST_OVERRIDES`](#allow_sites_to_configure_request_overrides) is `true`.
+
+- Default: Empty string (request overriding is disabled)
+- Use `*` to target all request overridable variables (when used, `*` must be specified first in comma-separated list).
+- If a restriction type is not specified, the request override variable will be `restricted` by default.
+
+:::info
+
+Examples
+
+```
+1. ALLOWED_REQUEST_OVERRIDES=INCLUDE_DATASOURCE_IDS,INCLUDE_WORKBOOK_IDS:unrestricted
+
+2. ALLOWED_REQUEST_OVERRIDES=*:unrestricted,MAX_RESULT_LIMIT:restricted,MAX_RESULT_LIMITS:restricted
+
+3. ALLOWED_REQUEST_OVERRIDES=*
+```
+
+Result in the following:
+1. only `INCLUDE_DATASOURCE_IDS` (restricted) and `INCLUDE_WORKBOOK_IDS` (unrestricted) are allowed as request overrides.
+2. all request overrides are allowed and unrestricted, except for `MAX_RESULT_LIMIT` and `MAX_RESULT_LIMITS` which are restricted.
+3. all request overrides are allowed and restricted.
+
+:::
+
+<hr />
+
+### `ALLOW_SITES_TO_CONFIGURE_REQUEST_OVERRIDES`
+
+When `true`, sites can specify their own set of [`ALLOWED_REQUEST_OVERRIDES`](#allowed_request_overrides), see [Site Settings](site-settings.md).
+
+- Default: `false`
+- When `false`, sites can not specify their own set of [`ALLOWED_REQUEST_OVERRIDES`](#allowed_request_overrides).
+
+## Restriction Types
+
+Each allowed request override variable has a restriction type that determines what values are permitted as overrides.
+
+### `restricted`
+
+When a variable is restricted, request overrides can only narrow or maintain the current configuration. They cannot expand access or remove limits.
+
+### `unrestricted`
+
+When a variable is unrestricted, request overrides can set any valid value, including values that expand beyond the current configuration or clear existing limits.
+
+## Providing Request Overrides
+
+When making a [tool call](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#calling-tools) request, overrides can be specified using the `x-tableau-mcp-config` HTTP header. The header value is a string of key-value pairs separated by `&`.
+
+```
+x-tableau-mcp-config: INCLUDE_TAGS=sales,marketing&MAX_RESULT_LIMIT=50
+```
+
+- Each key must be a [request overridable variable](#request-overridable-variables).
+- Each key must have a value (the `=` sign is required). An empty value (e.g. `MAX_RESULT_LIMIT=`) is valid and is used to override a variable to its default value.
+- Any unrecognized keys or invalid override values will cause the request to fail with an error.
+
+## Request Overridable Variables
+
+The following variables can be overriden on a per-request basis. Each variable has different behavior depending on whether it is `restricted` or `unrestricted`.
+
+### [`INCLUDE_PROJECT_IDS`](tool-scoping.md#include_project_ids)
+
+Overrides which project IDs constrain tool arguments and results.
+
+| Restriction Type | Behavior |
+|---|---|
+| `restricted` | If there are any current bounds set, the override value must be a **subset** of the current bounds. Cannot clear existing bounds. |
+| `unrestricted` | Override value can be any valid set of project IDs, including values not in the current bounds. Can clear existing bounds with an empty value. |
+
+### [`INCLUDE_DATASOURCE_IDS`](tool-scoping.md#include_datasource_ids)
+
+Overrides which data source IDs constrain tool arguments and results.
+
+| Restriction Type | Behavior |
+|---|---|
+| `restricted` | If there are any current bounds set, the override value must be a **subset** of the current bounds. Cannot clear existing bounds. |
+| `unrestricted` | Override value can be any valid set of data source IDs, including values not in the current bounds. Can clear existing bounds with an empty value. |
+
+### [`INCLUDE_WORKBOOK_IDS`](tool-scoping.md#include_workbook_ids)
+
+Overrides which workbook IDs constrain tool arguments and results.
+
+| Restriction Type | Behavior |
+|---|---|
+| `restricted` | If there are any current bounds set, the override value must be a **subset** of the current bounds. Cannot clear existing bounds. |
+| `unrestricted` | Override value can be any valid set of workbook IDs, including values not in the current bounds. Can clear existing bounds with an empty value. |
+
+### [`INCLUDE_TAGS`](tool-scoping.md#include_tags)
+
+Overrides which tags constrain tool arguments and results.
+
+| Restriction Type | Behavior |
+|---|---|
+| `restricted` | If there are any current bounds set, the override value must be a **subset** of the current bounds. Cannot clear existing bounds. |
+| `unrestricted` | Override value can be any valid set of tags, including values not in the current bounds. Can clear existing bounds with an empty value. |
+
+### [`MAX_RESULT_LIMIT`](env-vars.md#max_result_limit)
+
+Overrides the global maximum number of results for tools with a `limit` parameter.
+
+| Restriction Type | Behavior |
+|---|---|
+| `restricted` | Override value must be **less than or equal to** the current limit. Cannot clear existing limit. |
+| `unrestricted` | Override value can be any positive number. Can clear existing limit with an empty value. |
+
+### [`MAX_RESULT_LIMITS`](env-vars.md#max_result_limits)
+
+Overrides per-tool maximum result limits.
+
+| Restriction Type | Behavior |
+|---|---|
+| `restricted` | For tools that currently have a limit, the override value must be **less than or equal to** the current tool-specific limit. New tools added in the override must have a limit less than or equal to the `MAX_RESULT_LIMIT` value (which may have its own override value). |
+| `unrestricted` | Override value can set any valid per-tool limits (either a positive number, or `*` for unbounded results). Can clear all per-tool limits with an empty value. |
+
+### [`DISABLE_QUERY_DATASOURCE_VALIDATION_REQUESTS`](env-vars.md#disable_query_datasource_validation_requests)
+
+Overrides whether query validation requests are disabled.
+
+| Restriction Type | Behavior |
+|---|---|
+| `restricted` | Can only be overridden to `true`. |
+| `unrestricted` | Can be overridden to `true` or `false`. |
+
+### [`DISABLE_METADATA_API_REQUESTS`](env-vars.md#disable_metadata_api_requests)
+
+Overrides whether Metadata API requests are disabled.
+
+| Restriction Type | Behavior |
+|---|---|
+| `restricted` | Can only be overridden to `true`. |
+| `unrestricted` | Can be overridden to `true` or `false`. |
+
+## Override Hierarchy
+
+Request overrides are applied on top of site overrides and environment variables in the following order of precedence (highest to lowest):
+
+1. **Request overrides** (per-request, via `x-tableau-mcp-config` header)
+2. **Site overrides** (per-site, via REST API, see [Site Settings](site-settings.md))
+3. **Environment variables** (server-wide)
+
+For example, if the environment sets `MAX_RESULT_LIMIT=100`, a site override sets it to `50`, and a request override sets it to `25`, the effective value for that request is `25`.

docs/docs/configuration/mcp-config/site-settings.md

@@ -6,9 +6,25 @@ sidebar_position: 6
 
 Tableau MCP supports configuration on a per-site basis via REST API. When a Tableau MCP user is authenticated to a given site, the site's configuration is fetched and applied to their session such that each setting will override any current value set by the Tableau MCP server.
 
-In order to use site settings:
-- Only available in Tableau versions 2026.2 or higher.
-- Site settings must be enabled by the Tableau MCP server, see [`ENABLE_MCP_SITE_SETTINGS`](env-vars.md#enable_mcp_site_settings).
+## Enabling Site Settings
+
+Site settings are enabled by default, and are only available in Tableau versions 2026.2 or higher.
+
+### `ENABLE_MCP_SITE_SETTINGS`
+
+When `true`, the Tableau MCP server will fetch and apply site settings overrides for any user session.
+
+- Default: `true`
+- When `false`, the Tableau MCP server will not fetch or apply site settings overrides.
+
+<hr />
+
+### `MCP_SITE_SETTINGS_CHECK_INTERVAL_IN_MINUTES`
+
+Rather than fetching site settings with every request, the MCP server will cache the settings and only refresh them after the interval specified by this environment variable.
+
+- Default: `10` minutes
+- Must be a positive number between `1` and `1440` (1 day).
 
 ## Configuring Site Settings
 
@@ -25,12 +41,13 @@ When creating or updating site settings via REST API:
 When configuring site settings, make sure to validate your overrides have been applied successfully.
 Tableau MCP will ignore any overrides if it does not recognize the variable being overriden, or if the override value is invalid.
 
-You might not see changes take immediate effect due to caching, see [`MCP_SITE_SETTINGS_CHECK_INTERVAL_IN_MINUTES`](env-vars.md#mcp_site_settings_check_interval_in_minutes).
+You might not see changes take immediate effect due to caching, see [`MCP_SITE_SETTINGS_CHECK_INTERVAL_IN_MINUTES`](#mcp_site_settings_check_interval_in_minutes).
 
 :::
 
 ## Site Overridable Variables
 
+- ### [`ALLOWED_REQUEST_OVERRIDES`](request-overrides.md#allowed_request_overrides)
 - ### [`DISABLE_METADATA_API_REQUESTS`](env-vars.md#disable_metadata_api_requests)
 - ### [`DISABLE_QUERY_DATASOURCE_VALIDATION_REQUESTS`](env-vars.md#disable_query_datasource_validation_requests)
 - ### [`EXCLUDE_TOOLS`](env-vars.md#exclude_tools)

docs/docs/configuration/mcp-config/tool-scoping.md

@@ -30,10 +30,10 @@ The following optional environment variables can be used to configure the tool s
 
 A comma-separated list of project IDs by which to constrain tool arguments and results. Only data
 sources and workbooks (or views from those workbooks) that are members of the provided projects can
-be queried or will be included in the results of the tools. This variable is site overridable, see [Site Settings](site-settings.md).
+be queried or will be included in the results of the tools. This variable is site and request overridable, see [Site Settings](site-settings.md) and [Request Overrides](request-overrides.md).
 
 - When set by the Tableau MCP server, cannot be empty.
-- When overriden by site settings, can be empty to clear any bounds set by the Tableau MCP server.
+- When overriden, can be empty to clear any bounds set by the Tableau MCP server.
 - Project IDs can be determined using the
   [Query Projects](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_projects.htm#query_projects)
   REST API or by the [List Data Sources](../../tools/data-qna/list-datasources.md),
@@ -60,10 +60,10 @@ Example: `d87d843b-4326-4ce3-bc50-a68c1e6c9ca5,861566`
 
 A comma-separated list of data source IDs by which to constrain tool arguments and results. Only
 data sources or Pulse metrics and definitions derived from those data sources can be queried or will
-be included in the results of the tools. This variable is site overridable, see [Site Settings](site-settings.md).
+be included in the results of the tools. This variable is site and request overridable, see [Site Settings](site-settings.md) and [Request Overrides](request-overrides.md).
 
 - When set, cannot be empty.
-- When overriden by site settings, can be empty to clear any bounds set by the Tableau MCP server.
+- When overriden, can be empty to clear any bounds set by the Tableau MCP server.
 - Data source IDs can be determined using the
   [Query Data Sources](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_data_sources.htm#query_data_sources)
   REST API or the [List Data Sources](../../tools/data-qna/list-datasources.md) tool (assuming tool
@@ -78,10 +78,10 @@ Example: `2d935df8-fe7e-4fd8-bb14-35eb4ba31d4`
 
 A comma-separated list of workbook IDs by which to constrain tool arguments and results. Only
 workbooks or views from those workbooks can be queried or will be included in the results of the
-tools. This variable is site overridable, see [Site Settings](site-settings.md).
+tools. This variable is site and request overridable, see [Site Settings](site-settings.md) and [Request Overrides](request-overrides.md).
 
 - When set, cannot be empty.
-- When overriden by site settings, can be empty to clear any bounds set by the Tableau MCP server.
+- When overriden, can be empty to clear any bounds set by the Tableau MCP server.
 - Workbook IDs can be determined using the
   [Query Workbooks](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#query_workbooks)
   REST API or the [List Workbooks](../../tools/workbooks/list-workbooks.md) tool (assuming tool
@@ -97,10 +97,10 @@ Example: `222ea993-9391-4910-a167-56b3d19b4e3b`
 
 A comma-separated list of case-sensitive tags by which to constrain tool arguments and results. Only
 data sources, workbooks, or views with the provided tags can be queried or will be included in the
-results of the tools. This variable is site overridable, see [Site Settings](site-settings.md).
+results of the tools. This variable is site and request overridable, see [Site Settings](site-settings.md) and [Request Overrides](request-overrides.md).
 
 - When set, cannot be empty.
-- When overriden by site settings, can be empty to clear any bounds set by the Tableau MCP server.
+- When overriden, can be empty to clear any bounds set by the Tableau MCP server.
 - Tags can be determined using the
   [Tableau product](https://help.tableau.com/current/pro/desktop/en-us/tags.htm) or the REST APIs
   for querying

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tableau/mcp-server",
   "description": "Helping agents see and understand data.",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/tableau/tableau-mcp.git"