Notion
Connect Notion to create and update pages, query and build databases, edit block content, and search your workspace.
A single Notion internal connection token that starts with ntn_ (older ones start with secret_), pasted into PopMCP's Internal Integration Secret field.
- Setup time
- 6 min
- Auth
- API credentials
- API base URL
- https://api.notion.com/v1
- Rate limits
- About three requests per second per connection on average with short bursts allowed. Over that Notion returns HTTP 429 with a rate_limited code, and payloads are capped at 1000 blocks or 500KB.
Before you begin
- Notion account on any plan, including Free
- Workspace owner role, because only owners can create internal connections
- At least one page or database you are willing to share with the connection
Get your credentials
Open the Notion Developer portal
Go to notion.so/developers/connections. In the sidebar, under Build, select Internal connections.
Internal connections
Connections that can only be installed in the workspace you choose.
| Name | Associated workspace | Type | Created |
|---|---|---|---|
| Acme reporting botInternal integration | Acme HQ | Internal | Mar 4, 2026 |
| Roadmap syncInternal integration | Acme HQ | Internal | Jan 22, 2026 |
An internal connection is locked to one workspace. Reaching a second workspace means creating a second connection.
Create the internal connection
Click Create a new connection. Enter a Name such as PopMCP, choose the Associated workspace, then click Save.
Create a new connection
Name it and pick the workspace it can be installed in.
Turn on the capabilities you need
Open the connection's Configuration tab and tick Read content, Update content and Insert content under Content Capabilities. Under User Capabilities, pick a read option only if you need people properties or comment authors.
PopMCP
Internal connection in Acme HQ.
A capability left off makes the matching PopMCP tools fail at call time, not at connect time.
Copy the internal integration secret
Stay on Configuration and find the token field, labelled Internal Integration Secret in the classic view and Installation access token in the new portal. Click Show, then Copy.
PopMCP
Internal connection in Acme HQ.
- Associated workspace
- Acme HQ
- Type
- Internal
- Token prefix
- ntn_
- Created
- Mar 4, 2026
Notion lets you re-open this token later, so losing it is recoverable.
Share the pages the connection may read
Open the Content access tab and click Edit access, then pick the pages to share. You can also do it from Notion itself: open a page, click ••• at the top right, choose Connections, then Add connections and select your connection.
PopMCP
Internal connection in Acme HQ.
| Page | Access | Added |
|---|---|---|
| Acme WikiIncludes every nested page | Full access | Mar 4, 2026 |
| Product RoadmapDatabase | Full access | Mar 4, 2026 |
Sharing a parent page shares everything nested under it, so share one top-level page rather than fifty.
Connect in PopMCP
Open your workspace, choose Notion in the marketplace, and fill in the connect dialog:
| Field | What to enter |
|---|---|
| Internal Integration Secretsecret | In Notion open notion.so/my-integrations → New integration (give it a name and pick your workspace) → on the Configuration tab copy the Internal Integration Secret (starts with ntn_, or secret_ for older integrations). Then SHARE pages with it: open a page → ••• → Connections → add your integration. The secret is sent as Authorization: Bearer, stored encrypted, and used server-side only.Encrypted with AES-256-GCM on save and never shown again. |
PopMCP verifies the credential against Notion immediately. On success the connection flips to Verified and its MCP tools are provisioned.
Verify it worked
PopMCP marks the Notion connector Connected, and a search tool call returns the pages you shared with the connection rather than an empty list.
Troubleshooting
401 unauthorized, "API token is invalid"
Why: The token was retyped, truncated, or pasted with the word Bearer in front of it.
Fix: Re-open Configuration, click Show then Copy, and paste only the ntn_ string into PopMCP.
The token starts with secret_ instead of ntn_
Why: Connections created before 25 September 2024 were issued secret_ tokens.
Fix: Nothing to do. Older secret_ tokens still authenticate and PopMCP accepts both prefixes.
object_not_found on a page you can clearly see in Notion
Why: The page was never shared with the connection. Notion hides unshared content rather than returning 403.
Fix: Open the page, click ••• then Connections then Add connections, select your connection, and retry.
Writes fail while reads work
Why: Update content and Insert content are switched off in Content Capabilities.
Fix: Open the Configuration tab, tick the missing capability, and click Save changes. The token does not change.
No Internal connections item in the developer sidebar
Why: You are a member or admin, not a workspace owner.
Fix: Ask a workspace owner to create the connection and send you the token.
429 rate_limited
Why: More than roughly three requests per second on that connection.
Fix: Let PopMCP back off and retry. Batch large reads rather than looping page by page.