# Recipe: connect Notion

The Notion preset connects a board to your own Notion workspace through your own public Notion connection (Notion now calls integrations "connections"). Agents, column steps and people on a card can then query a data source and read a page, and, if you allow it, add a page to a data source or add a paragraph to a page. Read [Connect a service that signs in with OAuth](/docs/recipes/connections-oauth) first: this page covers only what is different for Notion.

How it works:

- **Notion has no OAuth scopes.** What the connection can do is set by the **capabilities** you turn on for it in Notion, and by the pages you share when you sign in. Every Notion operation in BakedBrie declares no scopes, and asking for a scope is refused.
- A person signs in once in the browser and picks which pages BakedBrie can see. BakedBrie reads the workspace ID and name from Notion's answer, so the connection says "Signed in to" your workspace by name.
- Notion may give no refresh token. Then the sign-in lasts until it is revoked, and if Notion ever refuses the token, the connection asks a person to sign in again.
- Every request carries the Notion API version BakedBrie pins, `Notion-Version: 2026-03-11`, including the sign-in, refresh and revoke calls. Changing it in the connection's JSON is refused.
- Writes run inside limits a person sets in the web app, are sent at most once, and are never retried by themselves. They write plain text only, never a mention, so a BakedBrie write never notifies a person by mention.

## Before you run it

1. In Notion's developer portal, create a **public** connection.
2. Add this exact redirect URI. It must match character for character:

   ```text
   https://app.bakedbrie.com/settings/destinations/oauth/callback
   ```

3. Choose the installation scope, then turn on only the capabilities your operations need (table below). Leave Update content, the comment capabilities and user information off.
4. Note the connection's client id. Put its client secret in an environment variable in your own shell, for example `export NOTION_CLIENT_SECRET=...`. Never paste it into the chat.
5. `whoami` must show `connections` and `connections_oauth` on.

## Operations and capabilities

| Operation | What it does | Reads or writes | Notion capability |
|---|---|---|---|
| `data_source_query` | Up to 25 pages of one data source | reads | Read content |
| `page_get` | One page's title, dates and parent data source (not its text) | reads | Read content |
| `page_create` | Adds a page with a title to a data source | writes | Insert content |
| `blocks_append` | Adds one paragraph of plain text at the end of a page | writes | Insert content |

The two reads are ticked when the create form opens; writes never are. Ids are UUIDs with dashes. A data source id is listed on the database (its `data_sources`); it is not the database id. BakedBrie queries data sources, not the older database query. The preset reads the title from the property named `Name`, Notion's default; if your data source's title property has another name, edit the path in the connection's JSON.

## The prompt

```text
In BakedBrie, connect Notion to the board "{{BOARD_NAME}}" with the Notion preset. Use only the BakedBrie MCP tools. Start with whoami and stop if connections or connections_oauth is off. First read /docs/recipes/connections-oauth and /docs/recipes/notion with read_docs.

My Notion connection's client id is {{CLIENT_ID}}. The client secret is in my environment variable {{ENV_VAR}}.
Operations to allow: {{OPERATIONS, for example data_source_query, page_get, page_create}}.

1. Call manage_connection with action presets and show me the Notion operations and the capabilities they need.
2. Create the connection with manage_connection create: preset notion, the operations above, my client id, and no scopes. Give the client secret with prepare_secret, never in the chat.
3. Tell me which capabilities to turn on in Notion for these operations.
4. Call connect_oauth and give me the sign-in link. Only a person can finish signing in and choose the pages.
5. Attach the connection to the board with a short handle, such as notes, and the operations above.
6. Stop and tell me what a person must do in the web app: finish signing in, then set limits for each operation.
```

## Limits, taint and triggers

- Notion does not charge per call. Notion allows about 180 calls a minute per connection (600 on Business and Enterprise), and a limit shared by the whole workspace can also answer busy. When Notion answers busy, it has not accepted the call, so BakedBrie waits as long as Notion says and tries again, up to three times.
- Page titles and text are free text. When a read on a card brings free text back, that card accepts only reads for the rest of that round of work, so text inside Notion can never steer a write.
- Notion documents no idempotency key. BakedBrie still sends each write at most once. If it cannot tell whether Notion saved a write, it says so and never sends it again by itself: check Notion for the page or paragraph before you send it again.
- Each Notion text value holds at most 2,000 characters.
- There is no Notion trigger yet. Use a scheduled card instead.
- Disconnecting revokes the sign-in at Notion.