@W-20976712: Add MCP OAuth scope support and enforcement #205

mattcfilbert · 2026-01-21T16:11:11Z

Description

Implemented MCP OAuth scope support and best‑practice authorization challenges. Added scope config knobs, advertised scopes_supported, validated requested scopes, persisted scopes across auth/refresh flows, embedded scopes in access tokens, and enforced required scopes with insufficient_scope challenges. Updated OAuth docs with a recommended beta scope set and rationale for MCP scopes.

Motivation and Context

MCP lacked spec‑aligned scope handling and challenge responses, which blocked least‑privilege access and step‑up behavior. This change brings OAuth behavior in line with the MCP authorization spec and provides a clear scope configuration for beta.

Type of Change

How Has This Been Tested?

Not run (logic is unit‑level; tests can be added in a follow‑up).

Related Issues

MCP OAuth scope support + best‑practice authorization challenges #204

Checklist

I have updated the version in the package.json file by using npm run version. For example,
use npm run version:patch for a patch version bump.
I have made any necessary changes to the documentation
I have added tests that prove my fix is effective or that my feature works
New and existing unit tests pass locally with my changes
I have documented any breaking changes in the PR description. For example, renaming a config
environment variable or changing its default value.

Contributor Agreement

By submitting this pull request, I confirm that:

I have read the CONTRIBUTING guidelines for this project and followed
its Contribution Checklist.

salesforce-cla · 2026-01-21T16:11:18Z

Thanks for the contribution! Unfortunately we can't verify the commit author(s): mfilbert <m***@s***.com>. One possible solution is to add that email to your GitHub account. Alternatively you can change your commits to another email and force push the change. After getting your commits associated with your GitHub account, refresh the status of this Pull Request.

anyoung-tableau · 2026-01-22T18:35:19Z

src/server/oauth/scopes.ts

+export type McpScope =
+  | 'tableau:content:read'
+  | 'tableau:viz_data_service:read'
+  | 'tableau:views:download'
+  | 'tableau:insight_definitions_metrics:read'
+  | 'tableau:insight_metrics:read'
+  | 'tableau:metric_subscriptions:read'
+  | 'tableau:insights:read'
+  | 'tableau:insight_brief:create';


In my mind, I was thinking we wouldn't use an API scope to protect an MCP resource directly ("resource" as in OAuth resource, not MCP resource). That is: an access token must have, say, the tableau:mcp:datasource:read MCP scope to even call the query-datasource tool, but that same access token would also need the 'tableau:viz_data_service:read' API scope since it's going to be re-used to call into VDS.

anyoung-tableau · 2026-01-22T18:37:02Z

src/server/oauth/scopes.ts

+ * Validates that a scope string is a valid MCP scope
+ */
+export function isValidScope(scope: string): scope is McpScope {
+  return DEFAULT_SCOPES_SUPPORTED.includes(scope as McpScope);


You can avoid the type assertion using DEFAULT_SCOPES_SUPPORTED.some((s) => s === scope);

anyoung-tableau · 2026-01-22T18:42:00Z

src/server/oauth/scopes.ts

+ * @param endpoint - The MCP endpoint or tool name
+ * @returns Array of required scopes for the endpoint
+ */
+export function getRequiredScopesForTool(toolName: ToolName | string): string[] {


Since we are going to need to maintain this map, let's use it as the source of truth for when tools generate a JWT with scopes.

For example, the query-datasource tool currently passes jwtScopes: ['tableau:viz_data_service:read'], to useRestApi().

Instead, it could pass: jwtScopes: getRequiredScopesForTool(queryDatasourceTool.name),.

This way we can never accidentally forget to update this map or the tool implementation.

anyoung-tableau · 2026-01-22T18:43:34Z

src/server/oauth/scopes.ts

+ * @returns Array of required scopes for the endpoint
+ */
+export function getRequiredScopesForTool(toolName: ToolName | string): string[] {
+  const toolScopeMap: Record<ToolName, McpScope[]> = {


Let's pull toolScopeMap outside of the function definition. It doesn't need to be initialized every time the function is called.

anyoung-tableau · 2026-01-22T18:48:04Z

src/server/oauth/scopes.ts

+ * @param endpoint - The MCP endpoint or tool name
+ * @returns Array of required scopes for the endpoint
+ */
+export function getRequiredScopesForTool(toolName: ToolName | string): string[] {


Let's change the type on the toolName parameter to be ToolName. Calling sites can provide their tool name using queryDatasourceTool.name (or even this.name if we call this function from tool.ts) for example. Then we don't need the if (toolName in toolScopeMap) or the fallback return DEFAULT_REQUIRED_SCOPES; below.

Also were you planning to wire this function up in a followup PR?

anyoung-tableau · 2026-01-22T18:49:10Z

src/server/oauth/scopes.ts

+ * @param endpoint - The MCP endpoint or tool name
+ * @returns Array of required scopes for the endpoint
+ */
+export function getRequiredScopesForTool(toolName: ToolName | string): string[] {


If scopes are disabled, getRequiredScopesForTool should return an empty array? Or were you planning to not call this function when scopes are disabled?

anyoung-tableau · 2026-01-22T18:53:33Z

src/server/oauth/.well-known/oauth-authorization-server.ts

      code_challenge_methods_supported: ['S256'],
-      scopes_supported: [],
+      scopes_supported: scopesSupported,
      token_endpoint_auth_methods_supported: ['client_secret_basic', 'client_secret_post'],


While we're here, would you mind making a driveby change here and add 'none' to token_endpoint_auth_methods_supported?

https://salesforce-internal.slack.com/archives/C08QYBH8AE5/p1769075292144669

anyoung-tableau · 2026-01-22T18:57:26Z

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

+For the initial release, use an inclusive scope set (MCP + Tableau API scopes) to avoid token
+exchange. This keeps consent simple and aligns with the current MCP server behavior.


Internal decisions and implementation details don't need to be documented.

anyoung-tableau · 2026-01-22T18:58:57Z

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

+- Not all MCP tools call Tableau APIs. Some tools can operate entirely within the MCP server
+  (for example, generating a TWB). Tableau API scopes do not describe those operations.
+- MCP also exposes non-API concepts like prompts and resources that should be gated behind MCP
+  scopes. Those do not have a natural Tableau API scope equivalent.
+- Keeping MCP scopes separate from API scopes clarifies intent and avoids over-granting: MCP scopes
+  authorize what the MCP server can do; Tableau API scopes authorize what downstream APIs can do.


I don't think we need to go into these details in the docs. We should describe more of the "what", and not necessarily the "why" here.

anyoung-tableau · 2026-01-22T19:04:31Z

src/server/oauth/authorize.ts

+    if (scopesToGrant.length > 0) {
+      oauthUrl.searchParams.set('scope', formatScopes(scopesToGrant));
+    }


So, the /oauth2/v1/auth endpoint on Tableau doesn't support scopes or consent. Not sure it makes sense to provide the scopes if they're going to be ignored.

tests/e2e/workbooks/listWorkbooks.test.ts

anyoung-tableau · 2026-01-22T19:12:26Z

OAUTH_IMPLEMENTATION_PLAN.md

+3. **Token Exchange**: 
+   - What is the endpoint for token exchange?
+   - What format should the request/response be?
+   - How do we convert MCP tokens to Tableau REST API tokens?


We aren't going to use token exchange for initial release

thank you for the reminder - I'm going through all of your great feedback now

anyoung-tableau · 2026-01-27T19:21:48Z

src/config.ts

+      TELEMETRY_PROVIDER: _telemetryProvider,
+      TELEMETRY_PROVIDER_CONFIG: _telemetryProviderConfig,


Was the rename of the telemetryProvider and telemetryProviderConfig variables intentional?

Accident after linting + merge. Will revert

anyoung-tableau · 2026-01-27T19:22:53Z

src/restApiInstance.ts

-  | 'tableau:insights:read'
-  | 'tableau:views:download'
-  | 'tableau:insight_brief:create';
+type JwtScopes = TableauApiScope;


Let's kill the JwtScopes type entirely.

salesforce-cla bot added the cla:missing label Jan 21, 2026

mattcfilbert force-pushed the W-20976712-mcp-oauth-scopes branch from a6ca30b to 01c9f2e Compare January 21, 2026 16:15

salesforce-cla bot removed the cla:missing label Jan 21, 2026

mattcfilbert force-pushed the W-20976712-mcp-oauth-scopes branch 2 times, most recently from baa916b to 41415fa Compare January 21, 2026 17:40

mattcfilbert requested a review from anyoung-tableau January 21, 2026 18:57

anyoung-tableau reviewed Jan 22, 2026

View reviewed changes

tests/e2e/workbooks/listWorkbooks.test.ts Show resolved Hide resolved

anyoung-tableau reviewed Jan 22, 2026

View reviewed changes

mattcfilbert added 8 commits January 23, 2026 14:43

@W-20976712: Add MCP OAuth scope support and enforcement

a3d186f

@W-20976712: Add OAuth scope env vars to MCP bundle manifest

59b4c8f

@W-20976712: Fix formatting for OAuth scope changes

6f36c54

@W-20976712: Update OAuth config tests for scopes

fb3f8fb

@W-20976712: Stabilize list-workbooks E2E filter test

3ecd52b

@W-20976712: Update OAuth tests for scope field

84ad976

@W-20976712: Align scopes with MCP guidance and tool mappings

99555ff

@W-20976712: Resolve lint issues and telemetry env merge

c4ebe90

mattcfilbert force-pushed the W-20976712-mcp-oauth-scopes branch from 655038b to c4ebe90 Compare January 23, 2026 20:44

mattcfilbert added 2 commits January 23, 2026 14:47

@W-20976712: Fix telemetry provider variable names

2e54ef8

@W-20976712: Fix restApiInstance import order

85345fd

mattcfilbert added 2 commits January 23, 2026 15:23

@W-20976712: Fix restApiInstance import sort order

dbded67

@W-20976712: Apply eslint import order for restApiInstance

bf0cd27

anyoung-tableau reviewed Jan 27, 2026

View reviewed changes

mattcfilbert added 5 commits January 28, 2026 16:03

@W-20976712: Disable scope enforcement in tests

8793359

@W-20976712: Guard scope lookups when oauth config is missing

b98eeca

@W-20976712: Apply telemetry cleanup and scope guard

7faba05

@W-20976712: axios package added

257c83b

@W-20976712: Add axios dependency for shared client

8dcea9d

		For the initial release, use an inclusive scope set (MCP + Tableau API scopes) to avoid token
		exchange. This keeps consent simple and aligns with the current MCP server behavior.

		TELEMETRY_PROVIDER: _telemetryProvider,
		TELEMETRY_PROVIDER_CONFIG: _telemetryProviderConfig,

@W-20976712: Add MCP OAuth scope support and enforcement #205

Are you sure you want to change the base?

@W-20976712: Add MCP OAuth scope support and enforcement #205

Uh oh!

Conversation

mattcfilbert commented Jan 21, 2026

Description

Motivation and Context

Type of Change

How Has This Been Tested?

Related Issues

Checklist

Contributor Agreement

Uh oh!

salesforce-cla bot commented Jan 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anyoung-tableau Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anyoung-tableau Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

anyoung-tableau Jan 22, 2026 •

edited

Loading

anyoung-tableau Jan 22, 2026 •

edited

Loading