Notion access for agents¶
Preferred connection for all agents (Cursor, VPS, OpenClaw, CI): official Notion CLI ntn.
Cursor Notion MCP is optional convenience only — not the shared default.
Canonical Gate A target: state-model.md Target workspace table.
Why ntn over MCP¶
| Concern | ntn + API token |
Cursor Notion MCP |
|---|---|---|
| Works outside Cursor | Yes | No |
| Shared secret store | Bitwarden → env | Per-user OAuth session |
| Scriptable / CI | Yes | No |
| Same path for every agent | Yes | Cursor-only |
Install¶
powershell
npm install -g ntn
ntn --version # expect 0.21+ (or current)
ntn doctor
Docs: https://developers.notion.com/cli/get-started/overview
Authenticate¶
A — Interactive (humans / local agents)¶
powershell
ntn login
Opens a browser OAuth flow. Credentials go to the OS keychain (or ~/.config/notion/auth.json if NOTION_KEYRING=0).
Headless / no browser:
powershell
ntn login --no-browser
Follow the printed two-step instructions.
Verify:
powershell
$env:NOTION_WORKSPACE_ID = "867ec393-2263-8154-bd17-000319357256"
ntn whoami
ntn doctor
B — Automation (preferred for VPS / other agents)¶
- Create a Notion internal integration (or use dedicated read/write integrations per Gate C).
- Share Conductor State (and later the nine DBs) with that integration.
- Store the token in Bitwarden Secrets Manager (never in git/chat).
- Export into the agent shell:
```powershell
After secret-gate unlock — names are bindings; values from Bitwarden only¶
$env:NOTION_API_TOKEN = "
NOTION_API_TOKEN overrides keychain login. Use read tokens for estate reads; write tokens only for executing agents after Gate C/D.
Conductor service env names (same values, different consumers):
| Bitwarden / env name | Use |
|---|---|
CONDUCTOR_NOTION_READ_TOKEN |
Conductor read adapters (Gate C+) |
CONDUCTOR_NOTION_TOKEN |
Legacy writes — disabled by default |
NOTION_API_TOKEN |
ntn CLI override for any agent |
NOTION_WORKSPACE_ID |
867ec393-2263-8154-bd17-000319357256 (sdhector workspace) |
Smoke test (safe)¶
powershell
$env:NOTION_WORKSPACE_ID = "867ec393-2263-8154-bd17-000319357256"
ntn whoami
ntn api v1/pages/3a7ec3932263818bbce3daa9a46b9220
Parent page: Conductor State.
Do not create the nine databases until Gate D approval on issue #3.
Policy¶
- Default agent Notion access =
ntn+ Bitwarden token + workspace ID. - Cursor Notion MCP may be used interactively but must not be the only documented path.
- Secret values stay in Bitwarden; docs carry names and locators only.
- Conductor itself remains read-only on routine Notion state; executing agents write via API/
ntnafter authorization.