Notion

Connect Notion so agents can search your pages and databases, answer from your docs, and keep runbooks and postmortems current

Connect Notion and CloudThinker agents can search the pages and databases you share with them, answer questions from your runbooks and handbooks, and update content when you ask. The connection signs in with a Notion internal integration secret (a token that belongs to one Notion workspace), and it only sees the pages you explicitly share with that integration.

Prerequisites

• A Notion account with permission to create integrations in the workspace. In most workspaces that means a Workspace Owner.
• Full access or Can edit on the pages and databases agents should reach, so you can share them with the integration.
• Edit permission on connections in your CloudThinker workspace.

Setup

1. Create an internal integration in Notion

   Go to notion.so/profile/integrations and click New integration. Name it cloudthinker, pick the Notion workspace, keep the type Internal, and save.

   Copy the Internal Integration Secret. It starts with ntn_ (older secrets start with secret_).

2. Choose the integration's capabilities

   On the integration’s Configuration tab, under Capabilities, keep only what your workflow needs. See Required permissions for the read-only and read-write sets.

   If Resolve will publish postmortems, also enable Insert content. See Use Notion for postmortems.

3. Share pages and databases with the integration

   Open the integration’s Access tab and select the pages and databases agents should reach. Child pages inherit access from their parent, so sharing a top-level page such as Engineering covers everything under it.

   You can also share one page from the page itself: open the ••• menu, choose Connections, and add cloudthinker.

4. Add the connection in CloudThinker

   In the sidebar, click More → Workspace settings → Connections. On the Builtin Connections tab, search for Notion and click Connect.

   Paste the secret into NOTION_TOKEN and click Connect.

   Success state: the dialog closes and the Notion connection shows Connected.

Notion checks the secret when an agent first calls it. Run the verify prompt below before you rely on the connection, so a mistyped or revoked secret shows up now instead of in the middle of an incident.

Connection details

Field	Description	Example
Alias	A short name for this connection. Agents and Rules use it to tell connections apart	marketing-wiki
Description	What this Notion workspace holds. Agents read it to pick the right connection, so make it specific	Marketing team wiki and launch plans
NOTION_TOKEN	Internal Integration Secret from your integration’s Configuration tab in Notion	ntn_<your-secret>

One secret covers one Notion workspace. To reach a second Notion workspace, create an integration there and add it as a separate connection.

Required permissions

Two things in Notion set the ceiling on what agents can do: the integration’s Capabilities and the pages on its Access tab. CloudThinker can never reach a page the integration isn’t shared with.

Goal	Capabilities to enable
Search and summarize (read-only)	Read content
Read discussions on pages	Add Read comments
Edit pages, add blocks, create pages or database rows	Add Update content and Insert content
Leave comments for your team	Add Insert comments

Leave user information at No user information unless a workflow needs to resolve people by name. Without it, agents see people in Person properties as IDs, not names.

Start read-only with Read content, and share only the teamspaces or top-level pages agents need, such as your runbooks and postmortems. Add write capabilities later if a workflow calls for them.

Agent capabilities

CloudThinker runs Notion’s official MCP server (Model Context Protocol, a standard way for agents to call a tool).

Capability	What agents can do
Search	Find pages and databases by title and content across everything shared with the integration
Read pages	Read a page’s properties and its full block content, including nested blocks
Query databases	Filter and sort database rows, such as postmortems from the last quarter or open action items
Edit content	Update page properties, append blocks, and create pages or database rows
Comments	Read comments on a page and add new ones

Edits and comments are writes, so Approvals decides whether each one runs, waits for a person, or is refused. Searches and reads run without asking.

Use Notion for postmortems

Resolve can draft and publish a postmortem to Notion after an incident is resolved. In the sidebar, open Resolve → Triggers & Outcomes, select Notion, turn on Publish postmortems under What Resolve can do, and enter a Notion parent page ID, the page new postmortems go under. Share that parent page with the integration and enable Insert content. See Resolve Triggers & Outcomes for the full setup.

The page ID is the 32-character string at the end of the page’s URL. Drop the title before it and any ?v= or ?pvs= part after it. For https://www.notion.so/Postmortems-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d?pvs=4, the page ID is 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d.

Verify the connection

Search Notion for our on-call runbook and summarize the escalation steps

A working connection names the actual page it found and quotes its content. A reply that says no pages were found means the integration isn’t shared with that page. An authorization error means the secret is wrong.

Example prompts

Summarize the postmortems in our Notion Incidents database from the last 90 days and list repeat root causes
Which Notion pages under Engineering → Runbooks haven't been edited in 6 months?
Add a step to the Database failover runbook in Notion: confirm replica lag is under 5 seconds before promoting
Compare the deploy steps in our Notion release checklist with the Production deploy runbook and list the differences

Troubleshooting

Every request fails with 401 Unauthorized

Notion rejected the secret. It may be mistyped, revoked, or from an integration that was deleted. Copy the current Internal Integration Secret from the integration’s Configuration tab. In CloudThinker, open Notion in More → Workspace settings → Connections, click the pencil icon on the account’s row, click Replace… in Edit Instance, paste the secret, and click Save and test.

The agent can't find a page that exists

The page isn’t shared with the integration. Add it on the integration’s Access tab, or from the page’s ••• → Connections menu. Sharing a parent page also shares its children.

Reads work but edits fail

The integration lacks Update content or Insert content. Enable them under Capabilities in Notion. If you meant to keep the connection read-only, this failure is the expected result.

An edit is waiting and nothing happens

The write is waiting for a person. Look for the approval card in the chat and click Approve. If the card says “Waiting for an approver,” click Notify approvers. See Approvals to change who approves and when.

Postmortems aren't published to Notion

Check that the Notion parent page ID in Resolve matches a page shared with the integration, and that Insert content is enabled.

Security

• Least privilege — grant only the permissions the agents need for your use case; start read-only and widen later.
• Read-only by default — use read-only credentials unless you want agents to make changes through this connection.
• Rotate credentials — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
• Revoke on offboarding — remove the credential at the provider when you delete a connection or a teammate leaves.

• The Access tab is your scope. The integration sees only the pages shared with it. Review that list when teams reorganize content.
• Keep the secret out of chat. Paste it only into the connection dialog, never into a chat message or a repository.
• Rotate by refreshing the secret. Refreshing the secret in Notion stops the old one working at once, so replace it in CloudThinker straight away (pencil icon → Replace… → Save and test). See Rotate a credential.
• Edits appear under the integration’s name. Notion shows changes made through the connection as the cloudthinker integration, so your team can tell them apart from human edits.

Related

Knowledge

Upload documents agents can search inside CloudThinker

Atlassian Connection

Connect Jira and Confluence for tickets and team docs