Notion

Purpose

Interact with Notion pages, databases, and workspace content via the hosted Notion MCP server (https://mcp.notion.com/mcp).

Tooling

Use exec to run:

notion-cli <subcommand> [options]

Connection management

notion-cli status
notion-cli authorize-url
notion-cli exchange-code --code <code> [--redirect-uri <url>]
notion-cli refresh
notion-cli disconnect

MCP operations

notion-cli list-tools
notion-cli call-tool --name <tool> --arguments-json '<json-object>'

--arguments-json must be a JSON object; arrays or scalars are rejected. Use list-tools first to discover the tool catalogue and each tool's input_schema.

Auth

OAuth is handled by authd via Dynamic Client Registration + PKCE (S256). The access token is stored at $JARVIS_HOME/user/auth/notion.json. Do not hand-edit this file.

First-use setup flow

1. Run notion-cli status.
2. If status is not_connected, run notion-cli authorize-url. When connect_url is present, replace <connect_url> with the returned URL and share exactly this Markdown link: [Connect Notion](<connect_url>); do not paste the raw URL separately. Wait for the user to complete authorization.
3. After the user authorizes, the browser is redirected via the Muse relay back to this VM, and authd completes the code exchange automatically. The agent resumes once the token lands.
4. Re-run notion-cli status. When status flips to connected the output also includes the discovered MCP tool catalogue.

For manual environments where the relay is not wired up, call notion-cli exchange-code --code <auth-code> after receiving the code.

Operating Rules

1. Run notion-cli status before any MCP work. If not connected, complete the setup flow first.
2. Call list-tools before call-tool unless you already know the tool name and its argument shape. Never guess tool names.
3. arguments-json must be a JSON object; wrap every argument appropriately.
4. Confirm user intent before tool calls that mutate Notion pages, databases, or blocks.
5. Token refresh happens automatically on 401. If call-tool keeps failing with unauthorized, run notion-cli refresh explicitly or ask the user to re-authorize.
6. Read results preserve Notion's raw date fields and add semantic UTC and user-local forms for record creation/edit times and timed date properties. Date-only properties remain dates.