start here

start using Notion with your agents

sign up, open a project, and authorise Notion from its connectors settings.

Start 7-day trial with Notion
integrationsconnectorupdated
schematic diagram of the work aldena agents do through Notion
Notion

ai agent for notion: start a run when a page, a database or a comment changes

connect notion to a project and its agents wake on page, data source and comment events for the pages shared with the integration, with the comment text in hand.

events
17
resource types
3
access grants
2

notion holds the spec, the decision log and the table someone maintains by hand, and a change to one of them is often the moment an agent should look. connecting notion to a project turns those changes into runs: an agent subscribes to a page, a data source or a comment thread from a chat, and the next matching event starts a run in that chat, or in a new chat in the same project when the routine opens one per event. writing back into notion goes through notion's own mcp server.

subscribing from a chat

notion_subscribe takes a resource, the events to watch, and what the agent should do when one arrives. the resource is a notion id or any notion url of the object. a page routine covers the page and the pages nested directly under it. a data source routine fires for the data source and for the row pages inside it, so page events are available there too. a comment routine follows the discussions on a page or a single comment thread. notion_unsubscribe takes an event routine off again, and the project's Settings → Routines lists every routine the agents hold.

each notification carries the event routine, the actor, a one-line summary and a link. a created or updated comment also carries the comment's plain text, fetched with the project's notion connection when the event arrives, and a failed fetch sends the notification without it. the text is fenced off as untrusted data and capped at 4,000 characters, so a comment can inform the agent but cannot instruct it.

sharing decides what reaches the project

notion only sends events for pages and data sources shared with the integration. you choose them on notion's consent screen when the project connects, and you can share more later from each page's connections menu. a page that was never shared produces no events, however the agent subscribed to it.

a notion workspace can be connected in one project at a time. notion only reveals the workspace after you approve, so connecting one that another project already holds fails at the end, and that project has to disconnect it first.

going beyond triggers with notion's mcp server

for searching, reading, creating and updating pages and databases, and for commenting, add notion's mcp server to the same project. it acts as the person who signs in to it.

  1. open the project's Settings → Connectors, and under MCP servers press Marketplace.
  2. install Notion. it installs as notion-mcp, so it does not clash with the connector.
  3. open the sign-in link it gives you and approve access in the browser.

once it is connected, agents reach its tools through mcp_search and mcp_call, each tool gets its own row in the project's permissions, and every action runs as the person who signed in, not as aldena. the mcp servers page covers the rest.

example tasks

  • 01

    when someone comments on the roadmap page, answer if it is a question about the api.

    each comment starts a run in this chat with the comment's text. the agent checks the code in the conversation's sandbox and replies on the page through notion's mcp server, or here when the project has none.

    notion_subscribebashmcp_call
  • 02

    when a row in the bug database moves to ready, start on it.

    the data source routine starts a run when a row's properties change. the agent reads the row through notion's mcp server, does the work in the conversation's sandbox, and pushes a branch.

    notion_subscribemcp_callgithub_git_syncbashgithub_git_push
  • 03

    stop watching the spec page.

    the agent lists its routines, finds the event routine on the spec page, and removes it, so edits there no longer start runs.

    list_routinesnotion_unsubscribe

what it will not do

the connector does not search, read, create, edit, move or delete pages, and it does not post comments. anything not shared with the integration in notion is invisible to it, and no event starts a run while the connection waits for a reconnect.

what starts a run

every Notion event an agent can subscribe to, grouped by resource. an agent subscribes from a chat with notion_subscribe, and each matching event starts a run in that chat, or in a new chat in the same project when the routine opens one per event.

page8 events
  • page.created
  • page.content_updated
  • page.properties_updated
  • page.moved
  • page.deleted
  • page.undeleted
  • page.locked
  • page.unlocked
data source14 events
  • data_source.created
  • data_source.content_updated
  • data_source.schema_updated
  • data_source.moved
  • data_source.deleted
  • data_source.undeleted
  • page.created
  • page.content_updated
  • page.properties_updated
  • page.moved
  • page.deleted
  • page.undeleted
  • page.locked
  • page.unlocked
comment3 events
  • comment.created
  • comment.updated
  • comment.deleted

what you grant

aldena's Notion app is configured for this access, and Notion shows it on its own consent screen. every project gets the same set, and there is nothing to pick.

  • Read content

    Receive page and data source events for the pages shared with the integration.

  • Read comments

    Receive comment events on the pages shared with the integration.

how to connect Notion

connecting Notion takes one authorisation round trip, started from inside the project that needs it.

  1. open the project's connectors settings

    connections belong to a project, not to your account or the team. open the project that needs Notion, go to settings → connectors, and press connect. other projects stay untouched.

  2. authorise with a real account

    any member of the project can start the connection, and they authorise as themselves. Notion asks only for the fixed access listed above, with no scopes to choose.

  3. an agent subscribes from a chat

    ask an agent in a project chat to watch something in Notion. it calls notion_subscribe with the resource, events and intent, and settings → routines lists each routine it holds.

  4. a matching event starts a run

    each matching event starts a run with the event and its content in hand, in the chat where the agent subscribed or in a new chat in the same project when the routine opens one per event. disconnecting Notion stops every subscription to it.

data handling and security

a connector holds one credential and turns Notion events into runs. the credential stays inside the project that connected it, and event text is data, never instructions.

  • one connection, one project

    the Notion credential is stored against the project it was authorised in. no agent in another project can use it, and there is no team-wide connection to inherit by accident.

  • tokens encrypted at rest

    the Notion token is encrypted before it is stored, and it never appears in a chat or in an agent's prompt. agents get the events, not the credential.

  • events only where a routine watches

    aldena verifies each delivery came from Notion. an event starts a run only for a routine it matches, in the chat that set the routine up or in a new chat in the same project when the routine opens one per event. nothing starts while the connection needs a reconnect.

  • event content is untrusted

    event text may come from a stranger. it reaches the agent as fenced data capped at 4,000 characters, and the agent is told never to follow instructions in it.

  • revocation is one click

    disconnect Notion and the project's event routines on it stop at once, along with the stored credential.

the permissions tab in project settings with reads on allow, edits on ask, and write file and bash on deny

each Notion tool agents hold has its own allow, ask or deny row in the project's permissions. see human in the loop for approvals and isolated projects for isolation.

faq

can an ai agent write pages in notion?

yes, through notion's own mcp server rather than the connector. install notion from the project's mcp marketplace with a browser sign-in, and agents search, read, create and update pages and comment through mcp_call, acting as the person who signed in. the connector itself only starts runs from notion events.

which notion events can start a run?

page events such as created, content updated, properties updated, moved, deleted and locked, data source events such as created, schema updated and moved along with the page events of its rows, and comment created, updated and deleted. notion batches quick edits, so a burst of typing arrives as one event a few seconds later.

why does an agent get no events for some pages?

notion only sends events for pages and data sources shared with the integration. that sharing is set in notion, not in aldena, when you approve the connection and later from each page's connections menu. share a page with the integration and its events start reaching the project.

what does a notion comment notification contain?

a created or updated comment carries the comment's plain text, which aldena fetches with the project's notion connection when the event arrives. if that fetch fails, the notification still arrives without the text. other events carry the event routine, the actor, a summary and a link only.

can two projects connect the same notion workspace?

no. a notion workspace can be connected in one project at a time. notion only tells aldena which workspace you picked after you approve, so connecting a workspace another project already holds fails at the end, and that project has to disconnect it first.

ready when you are

spin up your first project.

one project per client, product, or piece of work, staffed with intake, requirements, build and code review agents.