fix(mcp): accept multi-org session tokens when the request names the org

Merged
KI
1mo ago
+121-9

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: tokenOrganizationId picks the session org.
    • If the token has its own organizationId, that wins, as before.
    • Otherwise the x-superset-organization-id header picks one of the token's organizationIds.
    • 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.
  • packages/cli: plugin MCP calls send x-superset-organization-id, taken from resolveOrganizationId(config) (SUPERSET_ORGANIZATION_ID in 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/mcp has no test script, 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_events on 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: organizationIds only, iss/aud = API. Then I sent it in an MCP initialize to /mcp and /mcp/plugins/superset/google-calendar:

    RequestBefore (main's auth.ts)After
    header = an org in the token401 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 header401401 Token covers 2 organizations; name one in the x-superset-organization-id header
    header = org not in the token401401 Token does not cover organization …
  • The CLI sends the header. From a Superset terminal, pointed at a stub server, mcp tools --plugin google-calendar sent Authorization: Bearer <host JWT> plus x-superset-organization-id: <terminal org>.

  • Not verified against a deployed API.

  • typecheck in packages/mcp and packages/cli reports errors only in the untouched packages/trpc/src/trpc.ts (better-auth typings). A clean origin/main checkout 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 organizationId claim still takes precedence; otherwise the header picks one of the token's organizationIds.
  • 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.