Notion

01

Setup

1. 01Start the install. In the superagnt app open Integrations, pick Notion and click Connect with Notion.
2. 02Share your pages. In the window Notion opens, choose the pages and databases to share with the connection and allow access.
3. 03Call Notion. Notion moves to Enabled: its REST route answers and its tools appear on your MCP server.

There are no scopes to pick: the connection sees exactly what you share with it. To share more later, click Reconnect on the Notion connection page in the superagnt app and pick the pages.

02

Things to know

• Access is share-scoped: a search or query that returns nothing usually means the content is not shared with the connection yet.
• superagnt_ sends Notion-Version: 2026-03-11 on every call, so requests and responses follow that version of Notion's API.
• Search's filter value is page or data_source; a database shows up through its data source. Search and data source queries page with page_size (up to 100) and start_cursor.
• connection_notion_pages_write action update_markdown edits a page body by type: insert_content appends to the end, update_content replaces matching text, and replace_content overwrites the whole body.
• To delete a page, set in_trash: true with connection_notion_pages_write action update. That moves it to Notion's trash, where it can be recovered for a while, but treat it as a delete. archived: true archives the page in place instead.
• When Notion rate-limits the connection, calls come back as RATE_LIMITED (HTTP 429): back off and retry.
• By default every Notion call runs without asking, writes included: creating and updating pages and databases, editing page bodies, appending blocks, commenting and moving a page to the trash. To have a person approve some of them, set those tools to ask (Permissions).

03

Examples

Search for a page

curl -X POST "https://api.superagnt.com/v1/connections/notion/v1/search" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Roadmap","filter":{"value":"page","property":"object"}}'

Read a page as markdown

curl "https://api.superagnt.com/v1/connections/notion/v1/pages/$PAGE_ID/markdown" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY"

Create a page and write its body

# 1. create the page under a parent page
curl -X POST "https://api.superagnt.com/v1/connections/notion/v1/pages" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parent":{"page_id":"'"$PARENT_PAGE_ID"'"},"properties":{"title":[{"text":{"content":"Weekly update"}}]}}'

# 2. append its body as markdown, with the page id the first call returned
curl -X PATCH "https://api.superagnt.com/v1/connections/notion/v1/pages/$PAGE_ID/markdown" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"insert_content","insert_content":{"content":"## This week\n\n- Shipped the Notion connection\n- Next: calendar"}}'

Query rows in a database

# 1. get the database to find its data source ids
curl "https://api.superagnt.com/v1/connections/notion/v1/databases/$DATABASE_ID" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY"

# 2. query the rows of one data source
curl -X POST "https://api.superagnt.com/v1/connections/notion/v1/data_sources/$DATA_SOURCE_ID/query" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filter":{"property":"Status","select":{"equals":"Done"}},"page_size":25}'

12 tools, one per resource and risk

MCP servers and agents on the grouped surface list Notion as these tools. Each takes an action, and the ones that work across record types an object. Every operation also keeps its own per-operation name, in the next table, which works on every server. How grouping works: Grouped tools.

All 21 operations

Each operation is a REST path under https://api.superagnt.com/v1/connections/notion and an MCP tool. The per-operation tool name is the one permissions, approvals and usage records use.

Related