How do you authenticate with the Notion MCP server?

Two options: 1) Internal Integration Token (simplest for agents): Create an integration at notion.so/my-integrations, copy the token starting with 'ntn_' or 'secret_', and set Authorization and Notion-Version headers. Supports headless automation. 2) OAuth 2.0: Required for the hosted MCP server and multi-user public integrations. Requires user interaction for authorization, so it is not suitable for fully automated headless workflows.

Can the Notion MCP server perform block-level operations?

The hosted Notion MCP server does NOT expose block-level operations (get, update, delete, or append individual blocks). It operates at the page level only — fetching and replacing full page content. For block-level manipulation, use the local npx server (@notionhq/notion-mcp-server) or call the Notion REST API directly. Note: block tools in the local server are soft-deprecated by Notion.

What is Notion's API rate limit?

Notion's API rate limit is an average of 3 requests per second (180 requests per minute) per integration. Rate-limited requests return HTTP 429 with a Retry-After header. The 2026 Bulk Operations endpoint (POST /v1/bulk/pages) lets you process up to 100 pages per request, dramatically reducing rate limit pressure for write-heavy workflows.

How do you retrieve page content from Notion?

Page content is returned as blocks via GET /v1/blocks/{page_id}/children. Each paragraph, heading, and list item is a separate block object — not raw text. Agents must parse block types to extract content. For large pages, use cursor-based pagination with has_more and next_cursor parameters. page_size maximum is 100.

Service Deep-Dive 2026-04-20 14 min read

Notion MCP Complete Guide — 6 Pitfalls of the Official Server & 2026 New API Features

Notion earns an AAA grade in KanseiLink's AEO ratings, making it one of the top-ranked groupware-category services for agent readiness. Its official MCP server (npx @notionhq/notion-mcp-server) ships 18 tools with native support for Claude Code, Cursor, and VS Code. Yet Notion's API has six distinct pitfalls that trip up agent developers. This guide covers the rationale behind the AAA grade, the two auth methods, all six pitfalls, and the two 2026 API additions — Webhooks and Bulk Operations — that change how agents should interact with Notion.

1. Why Notion Earns an AAA AEO Grade

AAA

Notion MCP — AEO Rating Official MCP: ✅ (Hosted + Local npx)
Auth: Integration Token / OAuth 2.0
Last updated: 2026-04-19 (KanseiLink DB)

Dimension	Notion's Profile	Rating
Official MCP Server	Notion-official (github.com/makenotion/notion-mcp-server); hosted + local npx formats	✅ Top tier
Auth Methods	Integration Token (internal/simple) + OAuth 2.0 (public integrations)	✅ Strong
API Maturity	REST API v1 (stable 2022-06-28), cursor pagination, bulk ops, webhooks	✅ Strong
2026 Investment	Bulk Ops API (2026-02-01), Webhooks (2026-03-01), API version 2025-09-03	✅ Active

The trust score of 0.7 (moderate) reflects not API quality itself, but the high incidence of configuration errors — specifically the "connection sharing" pitfall described below. Developers who understand all six pitfalls in advance see dramatically better outcomes.

2. Authentication: Choosing Between Two Methods

Recommended / Agent & Automation

① Internal Integration Token

The simplest auth method. Tokens start with ntn_ or secret_. Supports fully headless automation (cron jobs, background agents, CI/CD). First choice for agent development.

1 Go to notion.so/my-integrations and create a new integration
2 Copy the "Internal Integration Secret" (starts with ntn_ or secret_)
3 Set Authorization: Bearer {token} and Notion-Version: 2022-06-28 headers on every request
4 Critical: For each target page/database, open Notion UI → "…" → "Connections" → add your integration (without this step, the API returns 404)

Advanced / Public Integrations

② OAuth 2.0

Required for public integrations used by multiple users. The hosted MCP server only supports OAuth 2.0, meaning users must go through a browser-based authorization flow. This makes it unsuitable for fully automated headless pipelines.

1 Create a "Public integration" at notion.so/my-integrations
2 Token URL: https://api.notion.com/v1/oauth/token
3 Users must complete a browser authorization flow — human interaction required
4 Use this path if deploying the hosted MCP server (Notion's remote server)

3. Hosted vs. Local MCP Server

Dimension	Hosted (Notion's server)	Local (npx)
Launch	URL in Claude Desktop config	`npx @notionhq/notion-mcp-server`
Auth	OAuth 2.0 only (user interaction required)	Integration Token or OAuth 2.0
Tools	18 tools (page-level only)	Some block-level tools included
Block Operations	❌ Not available	⚠️ Partially available (soft-deprecated)
Headless	❌ Not supported	✅ Supported
Best for	Interactive Claude Desktop use	Automation, CI/CD, background agents

4. Six Pitfalls That Trip Up Agent Developers

⚠️ Pitfall 1: "Connection Sharing" — 404 Errors Even With a Valid Token

The #1 Notion API trap. A valid Integration Token will return 404 on any page or database that has not been explicitly shared with the integration in Notion's UI. Notion's architecture means integrations have zero visibility into pages they haven't been granted access to. Every page, database, and nested database the agent needs to access must be shared via Notion's "…" menu → "Connections." Pre-sharing all target resources before deployment is non-negotiable.

⚠️ Pitfall 2: The Hosted MCP Has No Block-Level Operations

The hosted Notion MCP is restricted to page-level operations. Individual block manipulation — GET, UPDATE, DELETE, or APPEND individual blocks (paragraphs, headings, list items, checkboxes) — is not exposed. AI Meeting Notes transcript access is also blocked. If your workflow requires fine-grained content editing, use the local npx server or call Notion's REST API directly (note: block tools in the local server are soft-deprecated by Notion).

⚠️ Pitfall 3: The Hosted Server Does Not Support Headless Automation

The hosted MCP server requires OAuth 2.0, which means a user must authorize access via a browser. Cron jobs, GitHub Actions, background agents — any workflow without a human present cannot use the hosted server. For true headless automation, the local npx server with an Integration Token is the only viable path.

⚠️ Pitfall 4: Property Values Are Deeply Nested

All Notion database properties use a deeply nested structure. Accessing a title field requires properties.Name.title[0].text.content — not a simple record.Name. The path varies by property type (title, rich_text, number, select, date). Always fetch and cache the database schema first so your agent knows the exact access path for each property type before querying records.

      Notion Property Access Patterns
// Notion DB query response example
{
  "results": [{
    "id": "page_abc123",
    "properties": {
      "Name": { "type": "title", "title": [{ "text": { "content": "Project Alpha" } }] },
      "Status": { "type": "select", "select": { "name": "In Progress" } },
      "Due": { "type": "date", "date": { "start": "2026-05-01" } }
    }
  }]
}

// ✅ Correct access patterns
const name   = page.properties.Name.title[0]?.text.content;
const status = page.properties.Status.select?.name;
const due    = page.properties.Due.date?.start;

// ❌ Wrong: page.properties.Name returns the entire property object
    

⚠️ Pitfall 5: Database Queries Use POST, Not GET

An unusual API design: querying a database for records uses POST /v1/databases/{id}/query with filter conditions in the request body — not GET with query parameters. Agents that attempt GET-based filtering will get errors. Also note: the newer API version (2025-09-03) renames this tool to query-data-source, so check the MCP version you're running and use the correct tool name.

⚠️ Pitfall 6: File Attachments and Specific Comment Retrieval Are Unsupported

Neither the hosted nor the local MCP server exposes file upload or attachment access. Comment listing (retrieving all comments) is supported, but retrieving a specific comment by ID is not. Workflows requiring file handling need an alternative approach (S3, Google Drive integration, or Notion's UI-based file management).

5. Two 2026 Game-Changers

New 2026-03-01 Webhooks — Real-Time Change Detection Without Rate Limit Cost

Webhooks (POST /v1/webhooks) eliminate polling. Notion pushes events — page updates, database changes, comment additions — to your endpoint. Webhooks do not count against the 3 req/s rate limit since Notion is pushing to you rather than you pulling from Notion. For any change-monitoring use case, migrate from polling to Webhooks immediately.

New 2026-02-01 Bulk Operations API — Up to 100 Pages Per Request

The bulk operations endpoint (POST /v1/bulk/pages) processes up to 100 pages in a single request — up to 100x fewer requests than individual PATCH calls. Against a 180 req/min rate limit, this is the most impactful optimization available for write-heavy workflows. Use it for batch inserts, data migrations, and any scenario involving multiple page writes.

6. Implementation Checklist

✅ Notion MCP Pre-Flight Checklist

① Connection sharing: All target pages and databases shared with your integration in Notion UI
② Notion-Version header: Set to 2022-06-28 (stable) or 2025-09-03 (new Data Sources model)
③ DB schema cache: Fetch and cache property names + types before querying records
④ Cursor pagination: Handle has_more + next_cursor for full result sets (page_size max 100)
⑤ Rate limit handling: Respect Retry-After on HTTP 429; prefer Bulk Ops for writes
⑥ Change detection via Webhooks: Replace polling with Webhooks to save rate limit budget

      DB Query with Cursor Pagination
// POST /v1/databases/{id}/query — with filter + cursor pagination
async function queryAllPages(dbId, token) {
  const pages = [];
  let cursor = null;
  do {
    const body = {
      filter: { property: "Status", select: { equals: "Done" } },
      page_size: 100,
      ...(cursor && { start_cursor: cursor })
    };
    const res = await fetch(`https://api.notion.com/v1/databases/${dbId}/query`, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${token}`,
        "Notion-Version": "2022-06-28",
        "Content-Type": "application/json"
      },
      body: JSON.stringify(body)
    });
    const data = await res.json();
    pages.push(...data.results);
    cursor = data.has_more ? data.next_cursor : null;
  } while (cursor);
  return pages;
}
    

Summary: AAA Grade — But Configuration Is Everything

Notion's AAA grade is well-earned. An official MCP server, flexible auth, a mature REST API, and two major 2026 additions (Webhooks + Bulk Ops) make it a powerful platform for agent developers.

The critical caveat: Notion has an unusually high configuration-error rate compared to other top-rated services. The "connection sharing" pitfall alone accounts for the majority of agent integration failures. Know all six pitfalls before you start building, and you will avoid the debugging tax that catches most developers off guard.

The 2026 features deserve particular attention. Webhooks eliminate the rate limit cost of change detection entirely. Bulk Operations reduce write-heavy workflows to a fraction of their previous request count. Together, they make Notion one of the most agent-friendly knowledge management platforms available in 2026.

Check Notion's Live AEO Score

Real-time success rate, latency, and Agent Voice data available in our consulting plan.

Request Data Access