@W-22065947: Allow for disabling the MCP server globally (#309)

* Add BREAK_GLASS_DISABLE_GLOBALLY

* Bump

* Update MCPB

* Update import

* Update doc

* Bump

Author: anyoung-tableau

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

@@ -55,8 +55,10 @@ A comma-separated list of loggers to enable.
 
 - Default: `appLogger`
 - Possible values (may be combined): `fileLogger`, `appLogger`
-  - `fileLogger` — writes log entries and MCP notifications normally only sent to clients to hourly rotating files in the directory specified by[`FILE_LOGGER_DIRECTORY`](#file_logger_directory).
-  Notifications include tool calls and their arguments as well as HTTP traces for the requests and responses to the Tableau REST APIs.
+  - `fileLogger` — writes log entries and MCP notifications normally only sent to clients to hourly
+    rotating files in the directory specified by[`FILE_LOGGER_DIRECTORY`](#file_logger_directory).
+    Notifications include tool calls and their arguments as well as HTTP traces for the requests and
+    responses to the Tableau REST APIs.
   - `appLogger` — writes log entries to stdout as JSON. Enabled by default when transport is `http`.
 - The log file names are in the format `YYYY-MM-DDTHH-00-00-000Z.log` e.g.
   `2025-10-15T22-00-00-000Z.log` meaning this log file contains all log messages for hour 22 of
@@ -394,3 +396,25 @@ Enables product telemetry for tool usage tracking.
   https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_data_sources.htm#query_data_source_connections
 [tab-connect-ds]:
   https://help.tableau.com/current/api/vizql-data-service/en-us/docs/vds_create_queries.html#connect-to-your-data-source
+
+<hr />
+
+## `BREAK_GLASS_DISABLE_GLOBALLY`
+
+Can be used to force all MCP tools to return a "service unavailable" error message. Use with
+discretion.
+
+- Default: `false`
+- When `true`, all tools will return the below result:
+
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "The Tableau MCP server is temporarily unavailable. Please try again later."
+    }
+  ],
+  "isError": true
+}
+```

docs/docs/enterprise/tableau-server.md

@@ -429,8 +429,7 @@ By default, Tableau MCP sends notifications to MCP clients containing the reques
 traces for each request Tableau MCP tools make to the Tableau REST APIs. Many clients will save
 these notifications to their own log files, but if you need a way to gather and audit these traces,
 server-level logging can be enabled. See
-[ENABLED_LOGGERS](../configuration/mcp-config/env-vars#enabled_loggers) for more
-information.
+[ENABLED_LOGGERS](../configuration/mcp-config/env-vars#enabled_loggers) for more information.
 
 ```
 ENABLED_LOGGERS=fileLogger
@@ -673,3 +672,9 @@ For more information and precautions, see
 ```
 ENABLE_PASSTHROUGH_AUTH=true
 ```
+
+### Disable service temporarily
+
+If you need to temporarily disable the service for any reason, you can set
+[BREAK_GLASS_DISABLE_GLOBALLY](../configuration/mcp-config/env-vars.md#break_glass_disable_globally)
+to `true`. The MCP server will continue to handle requests but all tool calls will return an error.

package-lock.json

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

package.json

@@ -244,6 +244,18 @@ describe('Config', () => {
     expect(config.enablePassthroughAuth).toBe(true);
   });
 
+  it('should set breakGlassDisableGlobally to false by default', () => {
+    const config = new Config();
+    expect(config.breakGlassDisableGlobally).toBe(false);
+  });
+
+  it('should set breakGlassDisableGlobally to true when specified', () => {
+    vi.stubEnv('BREAK_GLASS_DISABLE_GLOBALLY', 'true');
+
+    const config = new Config();
+    expect(config.breakGlassDisableGlobally).toBe(true);
+  });
+
   describe('HTTP server config parsing', () => {
     it('should set sslKey to default when SSL_KEY is not set', () => {
       const config = new Config();

src/config.test.ts

@@ -80,6 +80,7 @@ export class Config {
   productTelemetryEndpoint: string;
   productTelemetryEnabled: boolean;
   isHyperforce: boolean;
+  breakGlassDisableGlobally: boolean;
 
   constructor() {
     const cleansedVars = removeClaudeMcpBundleUserConfigTemplates(process.env);
@@ -141,6 +142,7 @@ export class Config {
       PRODUCT_TELEMETRY_ENDPOINT: productTelemetryEndpoint,
       PRODUCT_TELEMETRY_ENABLED: productTelemetryEnabled,
       IS_HYPERFORCE: isHyperforce,
+      BREAK_GLASS_DISABLE_GLOBALLY: breakGlassDisableGlobally,
     } = cleansedVars;
 
     let jwtUsername = '';
@@ -268,6 +270,7 @@ export class Config {
       productTelemetryEndpoint || 'https://prod.telemetry.tableausoftware.com';
     this.productTelemetryEnabled = productTelemetryEnabled !== 'false';
     this.isHyperforce = isHyperforce === 'true';
+    this.breakGlassDisableGlobally = breakGlassDisableGlobally === 'true';
 
     this.auth = isAuthType(auth) ? auth : this.oauth.enabled ? 'oauth' : 'pat';
     this.transport = isTransport(transport) ? transport : this.oauth.enabled ? 'http' : 'stdio';

src/config.ts

@@ -126,6 +126,12 @@ export class ZodiosValidationError extends McpToolError {
   }
 }
 
+export class ServiceUnavailableError extends McpToolError {
+  constructor(message: string) {
+    super({ type: 'service-unavailable', message, statusCode: 503 });
+  }
+}
+
 export class UnknownError extends McpToolError {
   constructor(message: string, statusCode = 500) {
     super({ type: 'unknown', message, statusCode });

src/errors/mcpToolError.ts

@@ -71,6 +71,12 @@ async function startServer(): Promise<void> {
   if (config.disableLogMasking) {
     writeToStderr('⚠️ Log masking is disabled!');
   }
+
+  if (config.breakGlassDisableGlobally) {
+    writeToStderr(
+      '⚠️ BREAK_GLASS_DISABLE_GLOBALLY is enabled! This means that the MCP server will be disabled globally and will return errors to all users!',
+    );
+  }
 }
 
 startServer().catch((error) => {

src/index.ts

@@ -570,6 +570,14 @@ const envVars = {
     required: false,
     sensitive: false,
   },
+  BREAK_GLASS_DISABLE_GLOBALLY: {
+    includeInUserConfig: false,
+    type: 'boolean',
+    title: 'Break Glass Disable Globally',
+    description: 'Force all MCP tools to return a "service unavailable" error message.',
+    required: false,
+    sensitive: false,
+  },
 } satisfies EnvVars;
 
 const userConfig = Object.entries(envVars).reduce<Record<string, McpbUserConfigurationOption>>(

src/scripts/createClaudeMcpBundleManifest.ts

@@ -1,25 +1,25 @@
+import { ServiceUnavailableError } from './errors/mcpToolError.js';
 import { exportedForTesting as serverExportedForTesting } from './server.js';
-import { testProductVersion } from './testShared.js';
+import { stubDefaultEnvVars, testProductVersion } from './testShared.js';
+import { exportedForTesting } from './tools/listDatasources/listDatasources.js';
 import { getQueryDatasourceTool } from './tools/queryDatasource/queryDatasource.js';
+import { TableauToolCallback } from './tools/toolContext.js';
+import { getMockRequestHandlerExtra } from './tools/toolContext.mock.js';
 import { toolNames } from './tools/toolName.js';
 import { toolFactories } from './tools/tools.js';
+import invariant from './utils/invariant.js';
 import { Provider } from './utils/provider.js';
 
 const { Server } = serverExportedForTesting;
 
 describe('server', () => {
-  const originalEnv = process.env;
-
   beforeEach(() => {
-    process.env = {
-      ...originalEnv,
-      INCLUDE_TOOLS: undefined,
-      EXCLUDE_TOOLS: undefined,
-    };
+    vi.unstubAllEnvs();
+    stubDefaultEnvVars();
   });
 
   afterEach(() => {
-    process.env = { ...originalEnv };
+    vi.unstubAllEnvs();
   });
 
   it('should register tools', async () => {
@@ -63,7 +63,7 @@ describe('server', () => {
   });
 
   it('should register tools filtered by includeTools', async () => {
-    process.env.INCLUDE_TOOLS = 'query-datasource';
+    vi.stubEnv('INCLUDE_TOOLS', 'query-datasource');
     const server = getServer();
     await server.registerTools();
 
@@ -80,7 +80,7 @@ describe('server', () => {
   });
 
   it('should register tools filtered by excludeTools', async () => {
-    process.env.EXCLUDE_TOOLS = 'query-datasource';
+    vi.stubEnv('EXCLUDE_TOOLS', 'query-datasource');
     const server = getServer();
     await server.registerTools();
 
@@ -111,7 +111,7 @@ describe('server', () => {
 
   it('should throw error when no tools are registered', async () => {
     const sortedToolNames = [...toolNames].sort((a, b) => a.localeCompare(b)).join(', ');
-    process.env.EXCLUDE_TOOLS = sortedToolNames;
+    vi.stubEnv('EXCLUDE_TOOLS', sortedToolNames);
     const server = getServer();
 
     const sentences = [
@@ -133,6 +133,32 @@ describe('server', () => {
 
     expect(server.server.setRequestHandler).toHaveBeenCalled();
   });
+
+  it('should reject tool calls with service unavailable error when BREAK_GLASS_DISABLE_GLOBALLY is true', async () => {
+    vi.stubEnv('BREAK_GLASS_DISABLE_GLOBALLY', 'true');
+
+    const server = getServer();
+    await server.registerTools();
+
+    const listDatasourcesRegistration = vi
+      .mocked(server.registerTool)
+      .mock.calls.find((call) => call[0 /* tool name */] === 'list-datasources');
+
+    invariant(listDatasourcesRegistration);
+    const listDatasourcesCallback =
+      listDatasourcesRegistration[2 /* callback */] as TableauToolCallback<
+        Partial<typeof exportedForTesting.listDatasourcesParamsSchema>
+      >;
+
+    await expect(listDatasourcesCallback({}, getMockRequestHandlerExtra())).rejects.toSatisfy(
+      (error: unknown) =>
+        error instanceof ServiceUnavailableError &&
+        error.type === 'service-unavailable' &&
+        error.statusCode === 503 &&
+        error.message ===
+          'The Tableau MCP server is temporarily unavailable. Please try again later.',
+    );
+  });
 });
 
 function getServer(): InstanceType<typeof Server> {