# Notion setup for PopMCP

A single Notion internal connection token that starts with ntn_ (older ones start with secret_), pasted into PopMCP's Internal Integration Secret field.

- Auth: API credentials
- Setup time: 6 min
- API base URL: https://api.notion.com/v1
- Credentials screen: https://www.notion.so/developers/connections
- Provider docs: https://developers.notion.com/docs/create-a-notion-integration

## 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

### 1. Open the Notion Developer portal

Go to notion.so/developers/connections. In the sidebar, under Build, select Internal connections.

Screen: https://www.notion.so/developers/connections

### 2. Create the internal connection

Click Create a new connection. Enter a Name such as `PopMCP`, choose the Associated workspace, then click Save.

### 3. 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.

### 4. 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.

### 5. 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.

## Fields PopMCP asks for

- Internal Integration Secret (apiToken) [required]: 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.

## Verify

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"

Cause: 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_

Cause: 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

Cause: 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

Cause: 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

Cause: 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

Cause: 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.

---

Source: https://www.docs.popmcp.com/docs/integrations/notion/