fix(connectors): read Notion identity from the token response
Summary
Notion needs two connectors, not one. This PR splits them and fixes the identity probe that kept the MCP one from ever connecting.
notion_mcp(new) is what the Notion plugin binds to: theclient: "dynamic"method againstmcp.notion.com, with identity read from the OAuth token response instead of a second HTTP request.notionkeeps its name and every row it already has, and is now described as what those rows actually hold — a staticoauth2app onapi.notion.com, which is what/integrations/notionmints and what Notion triggers run on.identity.urlbecomes optional; a url-less probe reads its$.paths out of the token payload.- First-party installs resolve their connector from the published manifest rather than the copy stored at install time, so existing Notion plugin installs actually move to
notion_mcp.
Why / Context
The probe was pointed at the wrong audience
Connecting Notion sent you through consent and back to /connect/notion with the button still reading Connect. That looked like a token problem — the callback maps every exception to ?error=token_exchange_failed — but the token exchange succeeds. Production logs show the real failure, reproduced across three separate attempts:
[connectors/notion] callback failed: Error: Connector "notion" identity probe failed: 401
connectors.json probed https://api.notion.com/v1/users/me, but the access token is issued by the MCP authorization server at mcp.notion.com for resource https://mcp.notion.com/mcp. Notion's REST API rejects that audience.
Confirmed with a live token obtained by hand against mcp.notion.com — same token, same moment:
| Request | Result |
|---|---|
GET api.notion.com/v1/users/me | 401 {"code":"unauthorized","message":"API token is invalid."} |
POST mcp.notion.com/mcp (control) | 200 MCP initialize succeeds |
The probe was also reading $.bot.workspace_id, which is absent from this response shape, so it would have failed at the accountId guard even if the audience had matched.
This has never worked. The connector was added in 55390500e and untouched since; it is also the only client: "dynamic" connector, so nothing else exercises this path.
Fixing that alone would have broken Notion triggers
Raised in review, and the reason this PR grew. Two different Notion token types were sharing one connections row:
/integrations/notionstores anapi.notion.comtoken. Every existingnotionrow is one of these, including the ones #7675 backfilled./connect/notionstores anmcp.notion.comtoken.
Both upsert the same row, because the user-scope conflict target is (org, connector, user, externalAccountId) and externalAccountId is workspace_id in both. The moment the MCP connect starts succeeding, onConflictDoUpdate replaces the trigger's token — and the webhook fetches (normalizeNotionDelivery.ts) and trigger-options.ts start getting 401s. Worse, isPermanentNotionError classifies a 401 as permanent, so those deliveries are skipped, not retried.
One token cannot serve both audiences: mcp.notion.com returns 403 restricted_resource for a Notion API token, and api.notion.com returns 401 for an MCP token. Linear avoids this because mcp.linear.app accepts ordinary Linear tokens.
Two things were already broken today, independent of the probe fix, and the split fixes both:
- a user connected only for triggers shows as connected in the Notion plugin, and every tool call ships their API token to
mcp.notion.com; - uninstalling the Notion plugin disconnects every
notionconnection, including the one triggers use.
How It Works
Identity from the token response
mcp.notion.com exposes no userinfo endpoint (/userinfo, /oauth/userinfo, /v1/userinfo, /me all 404). Its only identity source is /introspect, which is unusable from probeIdentity for two independent reasons:
- It requires
application/x-www-form-urlencoded, butindex.tsalways sendsJSON.stringify(probe.body). Verified: a JSON body returns400 "Content-Type must be application/x-www-form-urlencoded". - It needs the token in the body, and
probe.bodyis never templated — onlyurlandheaderspass throughresolveConnectorTemplate. Putting the token in the query string does not work either; Notion ignores query params entirely (401 "Client ID is required"even withclient_idpresent).
No second request is needed, because the token response already carries everything:
access_token, bot_id, email_domain, expires_in, refresh_token, resource,
scope, token_type, user_id, workspace_icon, workspace_id, workspace_name
So the identity probe is now a union: either a probe with a url (unchanged, every other connector) or a url-less one that reads the same $. paths out of ConnectorTokens.raw. A union rather than an optional url because a url-less probe that still declared method/headers/body used to parse fine and silently ignore them.
Two connectors, one slug that never changes meaning
A slug is a connector's only identifier — stored as text in connections.connector, named by connector.slug in plugin manifests, hardcoded in trigger code. So nothing is renamed:
notionkeeps meaning theapi.notion.comtoken, which is what every saved row already holds. It gainsrequires_env,token_url, and identity paths matching that response shape ($.workspace_id,$.workspace_name,$.owner.user.id,$.owner.user.name).notion_mcpis new and has no rows yet, because that flow never completed.- No data migration, and
connections.connectoristext(), so no enum change either.
Existing installs follow the published manifest
plugin_installs.manifest is a copy taken at install time and rewritten only on reinstall, so repointing plugin.json would leave every existing install resolving notion. installConnector() resolves a first-party install against firstPartyManifest(pluginName) and falls back to the stored copy for everything else. It is used everywhere the routing decision is made:
resolve-target.ts— which connection a tool call runs under;plugins.uninstall— which rows get disconnected, so the trigger'snotionrow survives;plugins.list/plugins.connections.list— which connection the UI calls this plugin's.
Third-party installs are unaffected: their manifest copy is still the only thing that decides.
Testing
bun run typecheck, bun run lint, bun run check:i18n, bunx sherif, bun run check:plugins and the @superset/trpc (347) and @superset/shared (1108) suites all pass locally.
New tests:
connectors.test.ts— a url-less probe reads the token response withglobalThis.fetchstubbed to throw, and fails loudly when no token payload is passed.manifest.test.ts—installConnectorfollows the published manifest for a first-party install, keeps the stored copy for a third-party one, and falls back when the name is not published.plugins.test.ts(new) —plugins.uninstalldisconnects thenotion_mcprow and leaves the trigger'snotionrow alone; it also leaves the connector alone while another install still claims it, and never touches another member's connection.
Manual QA Checklist
Not yet run — needs preview or prod, since both flows need real Notion credentials.
The split
- Connecting from
/connect/notion_mcpand from/integrations/notionproduces two separateconnectionsrows - A Notion trigger still fires after the MCP connection exists
- A Notion plugin tool call works under the
notion_mcpcredential - Uninstalling the Notion plugin disconnects only the
notion_mcprow
Happy path
- Connect completes and the button flips to connected
- The connection shows the Notion workspace name as its account label
Regression (other connectors take the unchanged path)
- Linear connect still completes (static client,
requires_env) - Slack connect still completes (static client,
requires_env) - An api_key connector still completes (e.g. Sentry) — the probe path is untouched
Error handling
- Reconnecting an already-linked Notion workspace still surfaces
account_already_linked
Design Decisions
- Token-sourced identity instead of making
/introspectwork: the latter needs two changes (form encoding and body templating), adds a network round-trip per connect, and returns noworkspace_name. Both routes require a schema change, so this is strictly the smaller one. - A new slug rather than a
connectorstable: the slug stays the key and nothing ever has to be renamed, which is what keeps the migration empty. installConnectorrather than rewriting stored manifests: a backfill would have to run before the manifest ships and would still race new installs. Resolving at read time is correct from the first request.
Known Limitations
- No user label on the MCP connection — Notion's token response carries
user_idbut no user name field, souser.labelis null. - The api_key path (
router/connectors/index.ts) passes no token payload, so a url-less identity there throws a clear error. Unreachable today, but it fails loudly rather than silently if one is added.
Follow-ups
- Replace the bespoke
/api/integrations/notion/*routes with the generic connect flow, keeping theupsertIdentitycall formementions. Thenotionconnector is now described well enough for that to be a deletion rather than a rewrite. - The callback collapses every exception into
?error=token_exchange_failed(callback/[connector]/route.ts). A 401 identity probe reporting as a token-exchange failure is what disguised this bug; surfacing the real cause is a separate change. deploy-preview.ymlpasses noNOTION_*secrets and the Preview GitHub environment has none, so the older/api/integrations/notion/*routes are dead on preview deploys.
Risks / Rollout
- Risk: low. Other connectors take the identical pre-existing code path.
notionrows are untouched. The one broad failure mode — the registry failing zod at import — is loud and immediate, and CI parses it. - Rollout order matters: the API must ship before anyone reinstalls the plugin, which is automatic here since both land in the same commit.
- Rollback: revert. No data migration, no persisted state, no feature flag. A published plugin version is additive; reverting the manifest points installs back at
notion.
Summary by cubic
Fixes the Notion connector, which has never completed a connection: its identity probe hit Notion's REST API with an MCP-issued token (401) and read response fields absent from that response shape. Also splits Notion into two connectors so a working MCP connection can't overwrite the token Notion triggers run on.
- Makes
identity.urloptional; url-less probes read identity paths directly from the OAuth token response, which already carriesworkspace_id,workspace_name, anduser_id. - Adds
notion_mcpfor the dynamic client againstmcp.notion.com;notionkeeps its name and rows and is now described as the staticapi.notion.comoauth2 app it already held. No data migration. installConnectorresolves first-party installs against the published manifest rather than the copy stored at install time, so existing Notion installs move tonotion_mcp.- Uninstalling the plugin now disconnects only the
notion_mcprow and leaves the connection alone while another install or member still claims it. - All other connectors keep their
urland take the unchanged fetch path.
Summary by CodeRabbit
- Improvements
- Improved connector identity detection during sign-in and authorization.
- Connectors can now retrieve account details directly from authorization responses when a separate identity lookup is unavailable.
- Updated Notion connections to use workspace and user identifiers from the authorization response; they no longer make an additional user lookup or show the user’s name in identity details.
- Improved plugin connection matching, including for Notion. Uninstalling a plugin no longer disconnects a connection still used by another installation or member.