Pencil / docs← Back to app

Notion Ideas Connector

The Notion Ideas connector is for teams that think in Notion but want Pencil to remain the system that agents and execution tools can trust. Notion stays the external workspace. Pencil owns the OAuth connection, the sync engine, and the org-scoped credential boundary.

That distinction matters for agent and MCP workflows. An MCP client should not hold a Notion token just to help with Ideas. It should ask Pencil to operate on the org's connector, because Pencil already knows which Notion workspace, database, fields, and permissions belong to that org.

The model

Each synced Pencil Idea maps to one Notion page in one Notion database. Mapped properties move between the two systems. Unmapped Notion fields are ignored, so teams can keep extra Notion columns for views, formulas, owners, or notes without Pencil trying to interpret them.

Pencil owns promotion and execution state. Notion can mirror and edit Ideas, but the work of turning an Idea into features, tasks, agents, approvals, or shipped work stays in Pencil.

Setup

Open Settings -> Notion as an org admin and connect Notion. After OAuth, choose the database that should represent Ideas. Pencil will show property mapping controls for the fields it knows how to sync:

  • Title
  • Summary
  • Status
  • Tags
  • Pencil URL
  • Pencil Idea ID
  • Archived flag
  • Project or product display text, when available

Turn on Pencil to Notion when Pencil should create and update Notion pages. Turn on Notion to Pencil when edits in mapped Notion properties should update the Pencil Idea. Turn on Import new Notion rows only if a page without a Pencil Idea ID should become a new Pencil Idea.

Use Sync now after first setup or after changing a mapping. Webhooks are the live path; scheduled polling is the fallback for missed or batched Notion events.

Sync behavior

Pencil does not delete Notion pages when an Idea is deleted or archived. It sets the mapped status or archived property instead. If both sides edit mapped fields around the same time, the later edit wins and Pencil records the decision in sync diagnostics.

The connector prevents loops by remembering the last source, the last Pencil update time, the last Notion edit time, and the sync time. A write caused by a recent inbound or outbound sync is skipped instead of bouncing back and forth.

Agent and MCP usage

The connector is designed to become an agent control surface. The local Pencil MCP server is available through pencil-gateway mcp, but Notion-specific tools are planned connector tools rather than part of the current v1 MCP surface. Pencil does not currently provide a hosted remote MCP or Claude Custom Connector URL for Notion sync.

When implemented, the MCP layer should call Pencil-owned tools such as:

  • list_notion_idea_sync_status
  • sync_pencil_idea_to_notion
  • sync_notion_page_to_pencil_idea
  • link_pencil_idea_to_notion_page
  • create_pencil_idea_from_notion_page

Those tools should operate through Pencil's org-scoped APIs and actions. They should not store Notion credentials in MCP environment variables or MCP client connector settings.

What to try next

Read Working with your AI team to see how agents fit into the rest of Pencil, or open Settings -> Notion to connect the first Ideas database.