Notion Multi Workspace

A distributable Codex plugin backed by one OAuth-protected remote MCP server. It connects any number of Notion workspaces while exposing only six tools:

• notion_connect_workspace
• notion_list_workspaces
• notion_search
• notion_fetch
• notion_query
• notion_mutate

The number of tools is constant. Adding workspaces adds encrypted connection rows, not MCP servers or duplicate tools.

Why one MCP instead of one MCP per workspace?

A separate MCP server for every workspace multiplies the exposed tool surface. With N workspaces and M Notion tools, the client can end up seeing roughly N × M tools. That increases tool-selection ambiguity, configuration work, and the chance of querying the wrong workspace.

This plugin keeps one remote MCP server and stores workspace authorizations as data:

Codex
  └─ one Notion Multi Workspace MCP
       ├─ connection A → workspace A
       ├─ connection B → workspace B
       └─ connection N → workspace N

The MCP surface therefore stays at six tools regardless of how many workspaces are connected. Search fans out across selected connections; all other content operations require one explicit connectionId.

notion_query exposes an allowlist of 21 public Notion read operations and notion_mutate exposes 21 write operations. This covers pages and Markdown, blocks, databases, data sources, users, comments, meeting notes, async tasks, views, and file-upload lifecycle operations without multiplying tools per workspace. See the operation reference.

Install in Codex

Add this repository as a Codex marketplace, then install the plugin:

codex plugin marketplace add psh4607/notion-multi-workspace
codex plugin add notion-multi-workspace@notion-multi-workspace

Restart Codex if prompted. The first use opens OAuth for both the MCP service and the first Notion workspace. No Notion developer account or integration token is required for installers.

What installers do

1. Install the plugin from the marketplace.
2. Complete the Notion OAuth screen and choose the first workspace.
3. Ask Codex to connect another workspace. Open the one-time URL returned by notion_connect_workspace and choose that workspace in Notion.

Installers do not create integration tokens, use macOS Keychain, or maintain workspaces.json. The plugin publisher operates one Notion public integration and the remote MCP service.

Architecture and security boundary

• Codex authenticates to /mcp using OAuth 2.1 with PKCE.
• Notion authorization is a separate upstream OAuth flow.
• D1 rows are scoped by (user_id, bot_id). bot_id preserves multiple authorizations even when they target the same workspace.
• Notion access and refresh tokens are encrypted with AES-256-GCM before D1 storage.
• The encryption key and Notion client secret are Cloudflare Worker secrets.
• Additional-workspace links are random, one-use states in KV with a 10-minute TTL.
• Search is the only operation that can fan out. Fetch, query, and mutation require one explicit connection ID.
• Write calls are user-invoked, single-workspace, allowlisted, and marked destructive for conservative client confirmation.
• OAuth tokens are never returned in tool results or accepted as tool arguments.
• Binary upload transfer is intentionally not accepted through the generic JSON mutation tool; create, inspect, and complete upload records are supported.

Troubleshooting

Symptom	Likely cause	Resolution
Marketplace says the connection cannot be found	Creator dashboard is using a different Notion account	Switch to the account that owns the public developer connection and reload the listing form
Plugin installs but tools are not visible	Codex has not reloaded the new plugin	Restart Codex, then confirm the plugin is enabled
First OAuth succeeds but another workspace is missing	The additional one-time URL expired or the wrong Notion workspace was selected	Run notion_connect_workspace again and complete the new URL within 10 minutes
Search returns no pages from a connected workspace	The integration was not granted the relevant pages	Reopen the connection in Notion and grant the required pages; the connector only sees authorized content

Development and self-hosting

• Contributing guide
• Self-hosting and publisher setup
• Notion operation reference
• Architecture decisions and lessons learned

Contributions are licensed under the Apache License 2.0. Please review the contributing and security guidelines before opening a pull request or reporting a vulnerability.

Service documents

• Privacy Policy
• Terms of Use

For bugs and support requests, use this repository's GitHub Issues or email [email protected]. Do not include Notion page content, OAuth tokens, or other secrets in a public issue.