Authenticate the Notion MCP server for ZCode — including access to pages, databases, comments, page versions, and Notion chat session history — despite ZCode not being on Notion's client whitelist.
Same approach as DarkGenius/zcode-figma-mcp
(built for Figma), with one improvement: this script bootstraps the
discovery_state entry itself, so you don't need a preliminary ZCode restart
just to seed the server id.
ZCode connects to remote MCP servers over HTTP and runs the standard MCP OAuth
flow (RFC 9700 / StreamableHTTPClientTransport). Notion's MCP server
(https://mcp.notion.com/mcp) only accepts a fixed list of client names, and
"ZCode" isn't on it — so the out-of-the-box flow fails at client registration.
This script performs the OAuth flow under the client name Codex (which is
accepted — verified against Notion's dynamic client registration endpoint),
captures the resulting tokens, and injects them into ZCode's encrypted
credential store so ZCode can use them directly on subsequent connections.
- Ensures a
mcp:oauth:<id>:discovery_stateentry exists for the Notion server — finds an existing one, or performs OAuth discovery itself (RFC 9728/.well-known/oauth-protected-resource+ RFC 8414/.well-known/oauth-authorization-server) and creates the entry in the exact format ZCode expects. - Registers a new OAuth client named
Codexagainst the Notion MCP server. - Opens a browser for you to log in to Notion, pick the pages to share, and authorize the request.
- Catches the
localhost:3000/callbackredirect and exchanges the authorization code for access + refresh tokens (PKCE, S256). - Encrypts the tokens with the same AES-256-GCM scheme ZCode uses for
~/.zcode/v2/credentials.json, and writes them under the Notion server's id. - Backs up
credentials.jsonfirst and verifies the round-trip after writing. - Verifies the connection by calling
listTools()before exiting.
A successful run reports the tools the Notion MCP server exposes (72 at the time of writing), grouped roughly as:
| Area | Tools (examples) |
|---|---|
| Pages & documents | notion-search, notion-fetch, notion-create-pages, notion-update-page, notion-move-pages, notion-duplicate-page |
| Databases | notion-create-database, notion-query-data-sources, notion-query-multiple-data-sources, notion-update-data-source |
| Comments & discussions | notion-create-comment, notion-get-comments, notion-set-discussion-resolved, notion-set-comment-reaction |
| Chat session history | notion-search-sessions, notion-query-sessions, notion-read-session-event, notion-list-session-events, notion-spawn-session, notion-send-message-to-session |
| Page version history | notion-get-version-changes, notion-view-version, notion-restore-version |
| Calendar & meetings | notion-calendar-*, notion-create-meeting-note, notion-link-meeting-note-to-calendar-event |
| Files & attachments | notion-create-file-upload, notion-download-attachment, notion-get-file-download-urls |
-
Node.js ≥ 20
-
ZCode installed and run at least once, with the Notion MCP server declared in
~/.zcode/cli/config.json:{ "mcp": { "servers": { "notion": { "type": "http", "url": "https://mcp.notion.com/mcp" } } } }
Unlike the Figma script, a prior connection attempt is not required: if no
discovery_state entry for the Notion URL exists yet, the script creates one.
git clone https://github.com/Jommmain/zcode-notion-mcp
cd zcode-notion-mcp
npm install# Default flow — opens the browser, waits for you to authorize in Notion.
node notion-mcp-auth.mjs
# Verbose mode — prints decrypted values for debugging.
node notion-mcp-auth.mjs --verbose
# Different client name (default "Codex").
node notion-mcp-auth.mjs --client-name "Claude Desktop"
# Custom MCP server URL (defaults to https://mcp.notion.com/mcp).
node notion-mcp-auth.mjs https://mcp.notion.com/mcpAfter a successful run:
- Restart ZCode so it re-reads
credentials.json. - Verify in Settings → MCP that the
notionserver shows as connected and lists its tools.
| Path | Purpose |
|---|---|
~/.zcode/v2/credentials.json |
The script adds/overwrites up to three keys here:mcp:oauth:<server-id>:discovery_state (only if it didn't exist)mcp:oauth:<server-id>:tokensmcp:oauth:<server-id>:client_information |
~/.zcode/v2/credentials.json.backup |
Copy of credentials.json from just before the first write of this run. |
No other files are touched.
The <server-id> in the credential keys is not derived from the URL —
ZCode assigns it during OAuth metadata discovery and stores it inside the
encrypted discovery_state payload. The script:
- Scans all
mcp:oauth:*:discovery_statekeys incredentials.json. - Decrypts each one and matches
resourceMetadata.resourceagainst the target MCP URL. - If nothing matches, runs the discovery itself (401 probe → resource
metadata → authorization server metadata), generates a fresh id, and writes
a
discovery_stateentry in the same format ZCode produces.
If ZCode has already attempted the Notion flow, its own entry is found and reused — no duplicate is created.
ZCode wraps credential values as enc:v1:<iv>.<authTag>.<ciphertext>, where:
- algorithm:
aes-256-gcm - key:
sha256(ZCODE_CREDENTIAL_SECRET || fallback) - fallback:
zcode-credential-fallback:<platform>:<homedir>:<username> - iv: 12 random bytes, auth tag: 16 bytes, all base64url-encoded
Set the ZCODE_CREDENTIAL_SECRET environment variable to override the fallback
(e.g. on a shared/CI machine).
Access tokens expire (see the expires_in field). When ZCode starts getting
401s from Notion, re-run the script and restart ZCode. The refresh token may
extend the lifetime, but Notion eventually requires a fresh interactive
authorization — including re-selecting the pages shared with the connection.
Safari can't connect to the server "localhost" after clicking Allow.
The callback server binds to 0.0.0.0 so both IPv4 (127.0.0.1) and IPv6
(::1) work — the classic macOS fix, since Safari resolves localhost to
::1. If you still hit this, make sure nothing else is squatting on port 3000:
lsof -i :3000Authorization succeeds, but ZCode gets 401 after restart.
The machine profile (platform, homedir, username) used for key derivation
must match the one ZCode runs under. If you run ZCode under a different user,
set ZCODE_CREDENTIAL_SECRET consistently for both.
The script created a discovery_state but ZCode re-ran discovery itself.
If ZCode assigned its own id after a reconnect, simply re-run this script — it
will find ZCode's entry by URL and write the tokens under the correct id.
Notion shows fewer pages than expected.
The integration only sees the pages you shared during authorization. In
Notion: page → ··· → Connections → manage the MCP connection's page
access, then re-run the script.