@agentforge-io/connectors-notion

Notion connector for AgentForge. Adds a 14-tool belt (search, pages, blocks, databases, comments) that any agent can use after the end user has authorized via OAuth2.

Companion design doc: NOTION_CONNECTOR_SDD.md at the repo root.

Quickstart

1. Create a Notion public integration at https://www.notion.so/profile/integrations → New integration → Public (NOT Internal — Internal integrations are workspace-bound and don't speak OAuth).

   • Type: Public integration
   • Redirect URI: https://<your-agentforge-host>/connectors/oauth/callback
   • Copy OAuth client ID + OAuth client secret from the OAuth Domain & URIs tab.

2. Register the connector in your host's bootstrap (or rely on the platform's vault-driven wiring — connectors.module.ts already does this if you set NOTION_OAUTH_CLIENT_ID / NOTION_OAUTH_CLIENT_SECRET in Settings → Secrets):

   import { notionConnector } from '@agentforge-io/connectors-notion';
   
   connectorRegistry.register(notionConnector({
     clientId: env.NOTION_OAUTH_CLIENT_ID,
     clientSecret: env.NOTION_OAUTH_CLIENT_SECRET,
   }));

3. End-user authorizes. Each operator's user clicks Connect on the Notion card. Notion's consent screen is page-pick — the user explicitly chooses which pages and databases to expose. The token only sees those + descendants.

Tools

| Name | Purpose | |---|---| | Discovery | | | notion_search | THE entry point — find pages / databases. No /pages endpoint exists in Notion. | | notion_get_self | Bot user id + workspace name (debug + intro responses) | | notion_list_users | Workspace member list — resolves name → user.id for assignments | | Page reads | | | notion_get_page | Metadata + properties (NOT body) | | notion_get_page_content | Block tree (body) — paginated, recursive | | Page writes | | | notion_create_page | Create page under a DB (row) or another page (child) | | notion_update_page | Patch properties OR archive/restore | | Block edits | | | notion_append_blocks | Add notes / paragraphs / code to end of page or block | | notion_update_block | Edit one block (rename bullet, toggle to_do, fix typo) | | notion_delete_block | Soft-delete (~30 day restore window) | | Databases | | | notion_get_database | Schema — REQUIRED before create_page on a DB | | notion_query_database | Filter + sort rows; the equivalent of "list_issues" for Notion | | notion_create_database | Scaffold a new tracker DB from chat | | Audit | | | notion_create_comment | New page-thread OR reply to existing thread |

Consent model — important

Unlike Slack / ClickUp / GitHub which grant account-wide access, Notion makes the user pick specific pages at consent time. The token only sees those + descendants. Consequences:

• notion_search returns 0 hits for pages the user didn't include — the pages exist, just not in the token's scope. Have the user Disconnect → Connect and pick a wider selection.
• object_not_found errors on get_page / get_database / etc. mean the same thing — surface verbatim to the model so it can ask the user.
• There is no "expand consent" API — every widening requires a full reconnect.

Tokens

OAuth grants long-lived workspace tokens. No refresh_token, no expires_in. Tokens invalidate when the user removes the integration from their workspace settings or rotates the OAuth App's secret.

On 401 the registry surfaces auth_required and the user reconnects.

Common gotchas

• Card shows "Needs admin setup". Either NOTION_OAUTH_CLIENT_ID or NOTION_OAUTH_CLIENT_SECRET is missing — check /settings/secrets.
• redirect_uri does not match. The Redirect URI on the Notion integration must match /connectors/oauth/callback byte-for-byte (https, no trailing slash, correct host).
• property does not exist on create_page. The properties payload doesn't match the database schema. Call notion_get_database first to learn the exact property names.
• Notion-Version mismatch in logs. We pin 2022-06-28. Notion deprecates versions gradually; bumps come in package patch releases.
• "This integration shows a warning during consent". Public integrations start in Beta — Notion gates "Verified Public" behind a manual review. Submit once a few tenants have authorized.