@W-21817321: Add Tableau MCP site level configuration support (#291)

* rough draft mcpSiteSettings

* change mcpSiteSettings mock

* fix sidebar positions

* add site overrides

* add override tests

* remove unused functions

* version bump

* add comments to overriableConfig constructor

* Update ENV variables with site override info.

* finally, site settings docs.

* remove invalid links in docs

* update version check logic

* update docs and logic

* update mock for OAuth test.

* version bump

* add mcp scope

* update package version

* add scope for custom_view

Author: stephendeoca

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

@@ -150,10 +150,19 @@ 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
-be available.
+be available. This variable is site overridable, see [Site Settings](site-settings.md).
 
 - Default: Empty string (_all_ are included)
 - For a list of available tools and groups, see
@@ -165,7 +174,7 @@ be available.
 ## `EXCLUDE_TOOLS`
 
 A comma-separated list of tool or tool group names to exclude from the server. All other tools will
-be available.
+be available. This variable is site overridable, see [Site Settings](site-settings.md).
 
 - Default: Empty string (_none_ are excluded)
 - Cannot be provided with `INCLUDE_TOOLS`.
@@ -184,13 +193,13 @@ The maximum timeout for requests to the Tableau Server REST API.
 ## `MAX_RESULT_LIMIT`
 
 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) environment
-variable.
+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).
 
 :::warning
 
-Take care when setting this value and be sure to set appropriate tool-specific limits in the
-[`MAX_RESULT_LIMITS`](#max_result_limits) environment variable.
+Take care when setting this value and be sure to set appropriate tool-specific limits using the
+[`MAX_RESULT_LIMITS`](#max_result_limits) variable.
 
 :::
 
@@ -202,7 +211,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.
+each tool (or tools in the group) can return. This variable is site overridable, see [Site Settings](site-settings.md).
 
 :::info
 
@@ -229,7 +238,7 @@ This means that:
   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
-  [`MAX_RESULT_LIMIT`](#max_result_limit) environment variable will be used instead.
+  [`MAX_RESULT_LIMIT`](#max_result_limit) variable will be used instead.
 - Each limit must be a positive number.
 
 <hr />
@@ -238,7 +247,7 @@ This means that:
 
 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.
+query the datasource. This variable is site overridable, see [Site Settings](site-settings.md).
 
 - Default: `false`
 - When `true`, skips validation of queries against metadata results and validation of SET and MATCH
@@ -263,6 +272,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).
 
 - Default: `false`
 - When `true`, skips requests to the `graphql` endpoint that provides additional context to field
@@ -302,6 +312,17 @@ 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/http-server.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 4
 ---
 
 # HTTP Server

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 3
 ---
 
 # Enabling OAuth

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

@@ -0,0 +1,43 @@
+---
+sidebar_position: 6
+---
+
+# Site Settings
+
+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).
+
+## Configuring Site Settings
+
+Only site and server administrators are able to configure Tableau MCP site settings.
+Not every Tableau MCP configuration variable is overridable with site settings, only the ones listed as [Site Overridable Variables](#site-overridable-variables).
+
+When creating or updating site settings via REST API:
+- To use a variable's default value or clear limits and bounds set by the Tableau MCP server, you can provide an empty string as the override value.
+- To remove an override variable from the list of site settings and restore its value back to what is set by the Tableau MCP server,
+  you can `POST` the current list of site settings minus the variable you want to remove or include the variable in a `PUT` request with a null value or omit the value property entirely.
+
+:::warning
+
+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).
+
+:::
+
+## Site Overridable Variables
+
+- ### [`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)
+- ### [`INCLUDE_DATASOURCE_IDS`](tool-scoping.md#include_datasource_ids)
+- ### [`INCLUDE_PROJECT_IDS`](tool-scoping.md#include_project_ids)
+- ### [`INCLUDE_TOOLS`](env-vars.md#include_tools)
+- ### [`INCLUDE_TAGS`](tool-scoping.md#include_tags)
+- ### [`INCLUDE_WORKBOOK_IDS`](tool-scoping.md#include_workbook_ids)
+- ### [`MAX_RESULT_LIMIT`](env-vars.md#max_result_limit)
+- ### [`MAX_RESULT_LIMITS`](env-vars.md#max_result_limits)

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 5
 ---
 
 # Tool Scoping
@@ -30,9 +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.
+be queried or will be included in the results of the tools. This variable is site overridable, see [Site Settings](site-settings.md).
 
-- When set, cannot be empty.
+- 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.
 - 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),
@@ -59,9 +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.
+be included in the results of the tools. This variable is site overridable, see [Site Settings](site-settings.md).
 
 - When set, cannot be empty.
+- When overriden by site settings, 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
@@ -76,9 +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.
+tools. This variable is site overridable, see [Site Settings](site-settings.md).
 
 - When set, cannot be empty.
+- When overriden by site settings, 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
@@ -94,9 +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.
+results of the tools. This variable is site overridable, see [Site Settings](site-settings.md).
 
 - When set, cannot be empty.
+- When overriden by site settings, 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-lock.json

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

package.json

@@ -220,16 +220,16 @@ describe('Config', () => {
     expect(config.mcpSiteSettingsCheckIntervalInMinutes).toBe(2);
   });
 
-  it('should set enableMcpSiteSettings to false by default', () => {
+  it('should set enableMcpSiteSettings to true by default', () => {
     const config = new Config();
-    expect(config.enableMcpSiteSettings).toBe(false);
+    expect(config.enableMcpSiteSettings).toBe(true);
   });
 
-  it('should set enableMcpSiteSettings to true when specified', () => {
-    vi.stubEnv('ENABLE_MCP_SITE_SETTINGS', 'true');
+  it('should set enableMcpSiteSettings to false when specified', () => {
+    vi.stubEnv('ENABLE_MCP_SITE_SETTINGS', 'false');
 
     const config = new Config();
-    expect(config.enableMcpSiteSettings).toBe(true);
+    expect(config.enableMcpSiteSettings).toBe(false);
   });
 
   it('should set enablePassthroughAuth to false by default', () => {

src/config.test.ts

@@ -189,7 +189,7 @@ export class Config {
       },
     );
 
-    this.enableMcpSiteSettings = enableMcpSiteSettings === 'true';
+    this.enableMcpSiteSettings = enableMcpSiteSettings !== 'false';
     this.enablePassthroughAuth = enablePassthroughAuth === 'true';
     const disableOauthOverride = disableOauth === 'true';
     const disableScopes = oauthDisableScopes === 'true';