Skip to content
Build Perch
Browse documentation

Notion

Short answer: Notion support is an internal integration token connected to Notion’s official REST API, not an MCP server. The AI can only see the pages and databases you explicitly share with the integration inside Notion, and every write asks for your approval first.

How does the Notion integration work?

Build Perch connects to Notion’s official API using your integration token. The token is stored securely and can’t be read back once saved. Notion’s own sharing model is the access boundary: the integration can only reach pages and databases you’ve shared with it from inside Notion, and a share cascades to child pages.

How do I connect it?

  1. Create an internal integration at notion.so/my-integrations and copy its Internal Integration Token.
  2. In Build Perch, open Integrations → Notion, paste the token, and click Save & connect; it’s validated immediately and the workspace name is shown on success.
  3. In Notion, share each page or database you want reachable: open it, go to ••• → Connections, and add the integration. Sharing a parent page cascades to its children.
  4. Add the Notion skill to a mode so the AI can use it.

What can the AI do with a database?

  • Find and read: notion_search finds shared pages and databases; notion_get_page reads a page’s text.
  • Understand a database’s shape: notion_get_database returns its columns: names, types, and (for select/status fields) the valid options. Reading this first is how the AI learns the exact column names before filtering or writing.
  • Query rows: notion_query_database lists a database’s rows with their field values, with filtering, sorting, and pagination.
  • Write: notion_create_page (a new sub-page), notion_create_database_row (a new row), notion_append_blocks (append text to a page), and notion_update_page_properties (change a row’s or page’s field values, e.g. mark a task done).

Every write shows an approval banner in chat before it happens. For an unattended agent run, the destination page or database has to be pre-authorized in the agent’s settings, or the run pauses for review instead of writing.

Good to know

  • Updating properties overwrites, with no undo. Notion’s API keeps no version history, so an update replaces the named fields outright; the approval banner lists exactly which fields are changing.
  • Some columns can’t be written. Formulas, rollups, created/edited timestamps, and unique IDs are read-only; people and relation fields can be read but not set.
  • The AI never sees an unshared page. Sharing is entirely a Notion-side action; there’s nothing to configure in Build Perch beyond the integration token.