Skip to content

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

Merged
Kitenite merged 1 commit into
mainfrom
fix/mcp-session-token-org
Oct 12, 2026
Merged

Kitenite merged 1 commit into
mainfrom
fix/mcp-session-token-org

Conversation

@Kitenite

@Kitenite Kitenite commented Oct 12, 2026 •

Copy link
Copy Markdown
Member

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:

    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 header
    header = 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-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.

Written for commit d9abe38. Summary will update on new commits.

View guided diff Turn on auto-fix

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.

`superset mcp tools/call-tool --plugin …` failed from every Superset
terminal with "OAuth token missing organizationId claim". In a Superset
terminal the CLI sends the host-service's session JWT, which carries an
`organizationIds` list, not the single `organizationId` claim that
resolveMcpContext required. The tRPC API already accepts the same token
by picking the org from the x-superset-organization-id header.

The MCP auth now does the same: a token's own organizationId still wins;
otherwise the header picks one of the token's organizationIds (or the
only one), and the existing membership check still runs. The CLI sends
the header for plugin MCP calls.
@coderabbitai

coderabbitai Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: f9695dad-3787-4e75-b3d6-eeb6ea39206c

📥 Commits

Reviewing files that changed from the base of the PR and between fe77642 and d9abe38.


📒 Files selected for processing (6)
  • packages/cli/src/commands/mcp/call-tool/command.ts
  • packages/cli/src/commands/mcp/tools/command.ts
  • packages/cli/src/lib/plugins/mcp-client.ts
  • packages/mcp/src/auth.ts
  • packages/mcp/src/token-organization.test.ts
  • packages/mcp/src/token-organization.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 8 remain after this review.



📝 Walkthrough

Walkthrough

The CLI now passes its configured organization ID to MCP connections. The MCP server uses the organization header and token claims to select an organization for OAuth authentication, returning unauthorized errors for organization selection failures.

Changes

MCP organization selection

Layer / File(s) Summary
Resolve organization from OAuth claims
packages/mcp/src/token-organization.ts, packages/mcp/src/auth.ts, packages/mcp/src/token-organization.test.ts
The new resolver prefers a nonempty organizationId claim. Otherwise, it validates the requested organization against organizationIds, or selects the only available organization. It throws for missing, uncovered, or ambiguous organizations. OAuth authentication maps resolver errors to unauthorized errors. Tests cover selection and error cases.
Pass organization context through MCP requests
packages/cli/src/commands/mcp/call-tool/command.ts, packages/cli/src/commands/mcp/tools/command.ts, packages/cli/src/lib/plugins/mcp-client.ts
Both CLI commands pass the configured organization ID and bearer token to connectPluginMcp. The MCP client adds Authorization and organization headers when their values are present.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant CLICommand
  participant connectPluginMcp
  participant resolveMcpContext
  participant tokenOrganizationId
  CLICommand->>connectPluginMcp: bearer and configured organization ID
  connectPluginMcp->>resolveMcpContext: Authorization and organization headers
  resolveMcpContext->>tokenOrganizationId: token payload and requested organization ID
  tokenOrganizationId-->>resolveMcpContext: resolved organization ID or selection error
Loading

Suggested reviewers: harshithmullapudi


Merge Risk: ⚪ Minimal · up to d9abe

The change appears mergeable after normal checks. Deployed CLI-to-server behavior has not been validated.

Pre-merge checks · Passed 4 · Failed 1

Failed Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 6 files. Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks (4 passed)
Check name Status Explanation
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Title check Passed The title uses conventional commit format and clearly summarizes the main MCP authentication change for multi-organization session tokens.
Description check Passed The description clearly explains the problem, implementation, backward-compatibility impact, and validation results. It does not include the template's Checklist section, but the required technical co…

  • Fix all pre-merge checks with AI
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Commit to this branch
  • Create a new PR

🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

🧹 Preview Cleanup Complete

The following preview resources have been cleaned up:

  • ✅ Neon database branch

Thank you for your contribution! 🎉

@greptile-apps

greptile-apps Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 4/5

[High impact] Changes how session tokens are validated for organization access.

The PR appears safe to merge, with non-blocking feedback to test the CLI’s outgoing organization header.

Findings

  1. P2 Dropped headers would escape tests ▶
Fix with agent prompt
### Issue 1
packages/cli/src/lib/plugins/mcp-client.ts:50-52
The new tests call `tokenOrganizationId` directly, so they would still pass if `connectPluginMcp` stopped sending `ORGANIZATION_HEADER`. That could break plugin commands in Superset terminals without a test failure.

Add a test that captures requests from `connectPluginMcp` and checks both `Authorization` and `ORGANIZATION_HEADER` during connection and a tool call.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

This PR lets MCP requests select an organization from a session token’s organizationIds.

  • MCP requests can choose an organization from a session token.
  • Plugin MCP commands send the CLI's selected organization.

Acknowledged behavior:

  • Kitenite explicitly preserves the token’s own organizationId over a different organization header, “as before.”
  • Kitenite states that released CLIs without the header still receive a 401 for multi-org session tokens.
  • Kitenite acknowledges that packages/mcp has no test script, so turbo CI does not run its tests.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  CLI[Plugin CLI command] --> Headers[Send bearer and organization header]
  Headers --> Verify[Verify token]
  Verify --> Single{Token has organizationId?}
  Single -->|Yes| Own[Use token organization]
  Single -->|No| Select[Select covered organization from header or sole entry]
  Own --> Membership[Check current database membership]
  Select --> Membership
  Membership --> Scoped[Mint relay token for selected organization]
  Scoped --> Plugin[Run plugin request]
Loading

Reviews (1) · Last reviewed commit: "fix(mcp): accept multi-org session token..." · Reviewed by Greptile

Comment on lines +50 to +52
requestInit: {
headers: pluginMcpHeaders(auth.bearer, auth.organizationId),
},

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Dropped headers would escape tests

The new tests call tokenOrganizationId directly, so they would still pass if connectPluginMcp stopped sending ORGANIZATION_HEADER. That could break plugin commands in Superset terminals without a test failure.

Add a test that captures requests from connectPluginMcp and checks both Authorization and ORGANIZATION_HEADER during connection and a tool call.

Prompt To Fix With AI
This is a comment left during a code review.
Path: packages/cli/src/lib/plugins/mcp-client.ts
Line: 50-52

Comment:
**Dropped headers would escape tests**

The new tests call `tokenOrganizationId` directly, so they would still pass if `connectPluginMcp` stopped sending `ORGANIZATION_HEADER`. That could break plugin commands in Superset terminals without a test failure.

Add a test that captures requests from `connectPluginMcp` and checks both `Authorization` and `ORGANIZATION_HEADER` during connection and a tool call.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

@Kitenite
Kitenite merged commit 41ac9cc into main Oct 12, 2026
17 checks passed
harshithmullapudi added a commit that referenced this pull request Oct 13, 2026
…s for multi-org users (#8450)

Every Superset MCP server an agent loads (Linear, PostHog, Neon, Slack, ...)
gets its auth from `superset auth mcp-headers`. Since #8274 (Oct 10) the CLI in
a Superset terminal sends the host-service session JWT, which carries an
`organizationIds` list instead of one `organizationId` claim. From then on
every agent MCP connection failed with "OAuth token missing organizationId
claim".

#8414 (Oct 12) taught the MCP auth to accept that token when the request names
the org in x-superset-organization-id, and made `superset mcp` send it. The
headers helper was left out, so single-org users recovered and anyone in two
or more orgs still gets "Token covers 2 organizations; name one in the
x-superset-organization-id header".

The helper now builds its headers with the same pluginMcpHeaders as the
`superset mcp` commands, naming the terminal's organization
(SUPERSET_ORGANIZATION_ID) or the active one from config. Checked against
api.superset.sh with a two-org session token: Authorization alone is rejected,
and with the org header the PostHog plugin lists its tools.

This branch was previously deployed

1 inactive deployment
preview — d9abe38d Deployed Oct 12, 2026 by Kitenite via Deploy Database (Neon) #11737
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant