fix(mcp): accept multi-org session tokens when the request names the org
Problem
superset mcp tools --plugin <name> and superset mcp call-tool --plugin <name> fail from every Superset terminal, for every plugin:
UNAUTHORIZED: OAuth token missing organizationId claim
In a Superset terminal the CLI sends the host-service's token instead of its own login (resolveAuth → readHostApiToken). That token is a better-auth session JWT, and it lists every org the user belongs to:
iss/aud: https://api.superset.sh
organizationIds: [org1, org2, org3]
organizationId: (absent)
resolveMcpContext → resolveOAuth only accepted a single organizationId claim. The tRPC API accepts the same token because jwtProcedure picks the org from the x-superset-organization-id header. The same command works from a plain terminal, where the CLI uses its own single-org OAuth token.
Fix
packages/mcp:tokenOrganizationIdpicks the session org.- If the token has its own
organizationId, that wins, as before. - Otherwise the
x-superset-organization-idheader picks one of the token'sorganizationIds. - With no header, a token that lists exactly one org uses it.
- Anything else is a 401 with a clear message.
- The existing membership check against the DB still runs afterwards, and the minted relay token is still scoped to that one org.
- If the token has its own
packages/cli: plugin MCP calls sendx-superset-organization-id, taken fromresolveOrganizationId(config)(SUPERSET_ORGANIZATION_IDin a Superset terminal).
The header is optional, so this is backward compatible. OAuth clients and API keys behave as before. Released CLIs that don't send the header still get a 401 for multi-org tokens, now with a message that says what to send.
Validation
-
Added
packages/mcp/src/token-organization.test.ts(6 cases) and ran it locally: 6 pass. Note:packages/mcphas notestscript, so turbo CI does not run this package's tests. -
Decoded the claims of a live host-service token to confirm the shape above.
-
Confirmed the failure from a Superset terminal, and the same call succeeding with the CLI's own login (
list_eventson google-calendar). -
End to end against a local API (this branch, worktree Neon branch, not production). I minted a session JWT through the local better-auth for a dev user in 2 orgs. It has the same shape as the prod host token:
organizationIdsonly, iss/aud = API. Then I sent it in an MCPinitializeto/mcpand/mcp/plugins/superset/google-calendar:Request Before (main's auth.ts)After header = an org in the token 401 OAuth token missing organizationId claim/mcp: 200 initialize result; plugin route: gets past auth to the plugin lookup (404, because the dev user hasn't installed the plugin)no header 401 401 Token covers 2 organizations; name one in the x-superset-organization-id headerheader = org not in the token 401 401 Token does not cover organization … -
The CLI sends the header. From a Superset terminal, pointed at a stub server,
mcp tools --plugin google-calendarsentAuthorization: Bearer <host JWT>plusx-superset-organization-id: <terminal org>. -
Not verified against a deployed API.
-
typecheckinpackages/mcpandpackages/clireports errors only in the untouchedpackages/trpc/src/trpc.ts(better-auth typings). A cleanorigin/maincheckout fails the same way in this environment.
Summary by cubic
Fixes superset mcp tools --plugin and superset mcp call-tool --plugin failing from Superset terminals with "OAuth token missing organizationId claim". The CLI now sends the x-superset-organization-id header for plugin calls, and the MCP server accepts session tokens that carry an organizationIds array by resolving the org from that header (or the single org when no header is sent).
Details
- A token's own
organizationIdclaim still takes precedence; otherwise the header picks one of the token'sorganizationIds. - Multi-org tokens without a header still return 401, now with a clearer error message.
- OAuth clients and API keys are unaffected; behavior is backward compatible.
Summary by CodeRabbit
- Bug Fixes
- MCP requests now select the organization covered by the authentication token, including when a token grants access to multiple organizations.
- Requests with a missing, invalid, or ambiguous organization selection are rejected with an authorization error.