# 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:

```text
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](./docs/operations.md).

## Install in Codex

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

```bash
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](./CONTRIBUTING.md)
- [Self-hosting and publisher setup](./docs/self-hosting.md)
- [Notion operation reference](./docs/operations.md)
- [Architecture decisions and lessons learned](./docs/lessons-learned.md)

Contributions are licensed under the [Apache License 2.0](./LICENSE). Please review the contributing and security guidelines before opening a pull request or reporting a vulnerability.

## Service documents

- [Privacy Policy](./PRIVACY.md)
- [Terms of Use](./TERMS.md)

For bugs and support requests, use this repository's GitHub Issues or email [psh30095@gmail.com](mailto:psh30095@gmail.com). Do not include Notion page content, OAuth tokens, or other secrets in a public issue.