MCP Spotlight: Notion MCP Server — The Official Knowledge-Base Bridge With Markdown-Native Retrieval, Two-Tool Minimalism, and the Workspace-Context Default for Agents

Server: @notionhq/notion-mcp-server by Notion License: MIT (open source SDK) · Tools: 2 (notion-search, notion-fetch) in the minimal profile; full surface in the standard profile Coverage: The Notion workspace — pages, blocks, databases, data sources, comments, users, search Transport: stdio (NPX) or HTTP · Auth: OAuth 2.0 (recommended) · Internal Integration Token (self-hosted) GitHub: github.com/makenotion/notion-mcp-server Docs: developers.notion.com/guides/mcp/mcp-supported-tools NPM: @notionhq/notion-mcp-server

Every agent that does knowledge work eventually needs Notion. The naive "wrap Notion's API as 200+ MCP tools" approach bloats the context window past usability and changes the tool surface on every Notion product release. The "give the agent raw Notion API access" approach dumps JSON block structures on the model. The "give the agent nothing" approach blocks every workflow that benefits from the team's shared knowledge — engineering docs, product specs, OKRs, project plans, customer profiles.

The official Notion MCP Server by Notion is the bridge that resolves this. 2 tools in the minimal profile (notion-search, notion-fetch), built around Markdown-native retrieval — Notion's content is returned as clean Markdown, not raw JSON block structures. MIT-licensed, official Notion-maintained. For teams that want the full surface, Notion also ships a standard profile with the full block CRUD.

This is the knowledge-base default for AI agents in 2026. Two-tool minimalism, Markdown-native output, ubiquitous use.

The Architecture: Two-Tool Minimalism

The Notion MCP Server's boldest design choice: the minimal profile exposes just 2 tools. That's it. The genius is in what those two tools enable.

notion-search: Find the right page

notion-search(
  query="Q3 OKRs",
  filter={
    "property": "object",
    "value": "page"
  },
  sort={
    "direction": "descending",
    "timestamp": "last_edited_time"
  }
)
  → Returns:
    [
      {
        "id": "page_abc123",
        "title": "Q3 OKRs — Engineering",
        "url": "https://notion.so/...",
        "last_edited_time": "2026-07-15T14:32:00Z",
        "snippet": "Increase deploy frequency by 50%..."
      },
      ...
    ]

The agent searches the entire Notion workspace using natural language. The result is a ranked list of matching pages with title, URL, last-edited time, and a snippet. The agent doesn't memorize Notion's URL structure or page IDs; it queries for what it needs.

notion-fetch: Read the page as Markdown

notion-fetch(id="page_abc123")
  → Returns:
    # Q3 OKRs — Engineering

    ## Objective 1: Increase deploy frequency by 50%

    **Owner:** Alice · **Target:** 50% increase by Sept 30

    ### Key Results
    - KR1: Reduce CI pipeline time from 25min to 12min
    - KR2: Adopt trunk-based development for the platform team
    - KR3: Implement blue-green deploys for production services

    ## Objective 2: Reduce customer-reported bugs by 30%

    **Owner:** Bob · **Target:** 30% reduction by Sept 30
    ...

The page content is returned as clean Markdown, not raw Notion JSON blocks. Headings, lists, tables, code blocks, callouts — all converted. No JSON noise, no nested block IDs, no _def_id clutter. The agent reads clean Markdown and reasons over it.

The contract:

1. notion-search — discover the right page
2. notion-fetch — read its content

This is the same pattern Cloudflare uses for its 2,500-endpoint API. Minimal surface, composable capability, always-current semantics. Notion's API evolves; the search index reflects it instantly.

The Markdown-Native Advantage

Notion's native format is JSON blocks — a nested structure of paragraph, heading_1, bulleted_list_item, callout, etc. blocks, each with IDs, colors, child blocks, and metadata. This is great for Notion's UI (it needs the structure to render) but terrible for LLM consumption:

{
  "type": "block",
  "id": "block_abc",
  "has_children": false,
  "paragraph": {
    "rich_text": [
      {
        "type": "text",
        "text": {"content": "Increase deploy frequency by 50%"},
        "annotations": {"bold": false, "italic": false, ...}
      }
    ]
  }
}

That's ~120 tokens of JSON for ~8 tokens of useful content. 15x token inefficiency. Across a typical Notion workspace read, this would blow out every context window.

The Notion MCP server converts this to:

Increase deploy frequency by 50%

~10 tokens for the same content. 12x token efficiency. The same pattern Anthropic's Fetch MCP uses for HTML → Markdown.

For agents that need to read multiple pages (e.g., a research workflow that synthesizes 10 Notion docs), the token savings are the difference between a productive session and context exhaustion.

The Database Support

Notion's most powerful feature is databases — typed records with properties, relations, filters, and views. The Notion MCP server supports databases via notion-fetch:

notion-fetch(id="database_xyz")
  → Returns:
    # Engineering Projects (Database)

    ## Schema
    - Name (title)
    - Status (select: Not Started, In Progress, Blocked, Done)
    - Owner (person)
    - Due Date (date)
    - Priority (select: P0, P1, P2, P3)
    - Tags (multi-select)

    ## Records (latest 10)
    | Name | Status | Owner | Due | Priority |
    | --- | --- | --- | --- | --- |
    | Auth Migration | In Progress | Alice | 2026-09-30 | P1 |
    | Multi-region Deploy | Not Started | Bob | 2026-10-15 | P2 |
    | Rate Limiting | In Progress | Carol | 2026-08-15 | P1 |
    ...

For agents that need to query the database (e.g., "show me all P0 projects in progress"), the search interface supports filtering:

notion-search(
  query="",
  filter={
    "property": "object",
    "value": "database",
    "database_property": {
      "Priority": {"select": {"equals": "P0"}},
      "Status": {"select": {"equals": "In Progress"}}
    }
  }
)
  → Returns matching database entries

The agent gets the database content in Markdown table form, filterable on any property.

The Standard Profile: Full CRUD

For teams that need to write to Notion (not just read), Notion ships a standard profile that exposes the full block CRUD:

Tool	Purpose
notion-search, notion-fetch	Read (same as minimal)
notion-create-page	Create a new page
notion-update-page	Update page properties / archive
notion-create-block	Append blocks to a page
notion-update-block	Modify block content
notion-delete-block	Remove blocks
notion-create-database	Create a new database
notion-update-database	Update schema / properties
notion-create-comment	Add comments
notion-list-users, notion-get-user	Workspace navigation
notion-list-data-sources, notion-query-data-source	Data source access (Notion 2026 API)
notion-move-page	Reorganize

The full surface is ~25 tools covering the entire Notion CRUD lifecycle.

For most agents, the minimal 2-tool profile is the right default. Read-only access eliminates the destructive surface, OAuth scopes are minimal, the agent can search and fetch without write permissions. When the agent needs to write, the standard profile unlocks the full surface — but the operator must opt in.

The OAuth 2.0 Flow

For SaaS-embedded agents (or any multi-user setup), the OAuth 2.0 flow is the right primitive:

1. User initiates — "Connect Notion" button in the SaaS
2. OAuth redirect — user authorizes on notion.com, sees the requested scopes
3. Token storage — the SaaS receives a refresh token, stores it per-user
4. Agent acts — every Notion MCP call uses the user's access token
5. Refresh flow — the SaaS refreshes the token automatically

The scopes are principle-of-least-privilege:

Scope	Read	Write
read_content	✓	—
update_content	✓	✓
insert_content	✓	✓
read_user	✓	—
read_comments	✓	—
insert_comments	✓	✓

For an agent that just reads docs, only read_content is requested. The user sees the scope on the OAuth screen and approves. The agent can never write without explicit permission.

For self-hosted setups (Notion internal integrations), the Internal Integration Token is the alternative. Less user-friendly but simpler operationally.

The Knowledge-Workflow Pattern

The canonical agent-driven Notion workflow:

User: "What's our Q3 OKR for engineering, and what's the current status?"

Agent:
  1. notion-search(query="Q3 OKR engineering")
     → Returns "Q3 OKRs — Engineering" page
  2. notion-fetch(id="page_abc123")
     → Returns the OKR content as Markdown
  3. // Cross-reference with Linear MCP for current status
     linear-search(query="cycle Q3")
     → Returns active cycles
  4. // Synthesize the answer
     Returns: "Q3 OKR is to increase deploy frequency by 50%. Current status:
       - CI pipeline time reduced from 25min to 18min (32% reduction)
       - Trunk-based dev adopted in platform team
       - Blue-green deploys in progress (60% complete)"

The agent reads Notion for the what (OKR), reads Linear for the how (active work), synthesizes the answer. Notion is the context; Linear is the execution; the agent bridges them.

The Specs-and-Design-Docs Pattern

For product teams that keep specs in Notion:

User: "Generate a Jira ticket for the feature described in the 'Auth Migration' spec."

Agent:
  1. notion-search(query="Auth Migration spec")
     → Returns the spec page
  2. notion-fetch(id)
     → Returns the spec content
  3. // Extract the acceptance criteria, scope, dependencies
  4. // Create the Jira ticket (or Linear issue, or GitHub issue)
     create_jira_ticket(
       title="Auth Migration — Phase 1",
       description=extracted_requirements,
       acceptance_criteria=extracted_criteria,
       dependencies=extracted_deps
     )

The agent reads the spec, extracts the structure, creates the corresponding work item. Notion is the source of truth; the agent propagates it to execution systems.

The Customer-Profile Pattern

For teams that keep customer profiles in Notion:

User: "For customer 'Acme', pull their profile and any meeting notes from the last quarter."

Agent:
  1. notion-search(query="Acme customer")
     → Returns the customer profile page
  2. notion-fetch(id)
     → Returns profile + linked meeting notes
  3. // Summarize the relationship, recent interactions, key contacts
  4. Returns the customer context

The agent reads the customer's profile, the recent meeting notes, the open issues, the action items. Notion becomes the CRM layer for the agent.

Facio Integration

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "${credentials.NOTION_OAUTH_TOKEN}"
      }
    }
  }
}

Or for the read-only minimal profile:

{
  "mcpServers": {
    "notion-readonly": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server", "--readonly"],
      "env": {
        "NOTION_TOKEN": "${credentials.NOTION_OAUTH_TOKEN_READONLY}"
      }
    }
  }
}

Facio's audit trail captures every Notion MCP call with the tool, the query, the page ID, the operation, the result. For a regulated team (SOC2, ISO 27001, GDPR), this is the complete knowledge-access record: "Agent at 14:32 UTC searched 'Q3 OKR engineering', fetched page_abc123, returned 2,400 tokens of Markdown."

For HITL workflows, the minimal profile's destructive surface is zero — search and fetch are read-only. The standard profile adds CRUD, which Facio can gate:

Tool	Severity	Suggested Gate
notion-search, notion-fetch	Read	None — autonomous
notion-create-page (in user's workspace)	Write, contextual	Soft confirm
notion-update-page	Write, contextual	Soft confirm
notion-archive-page (soft delete)	Write, contextual	Soft confirm
notion-delete-block (hard delete)	Write, destructive	Hard confirm
notion-create-database	Write, structural	Hard confirm (changes schema)
notion-update-database (schema change)	Write, structural	Hard confirm
notion-create-comment	Write, contextual	Soft confirm

The notion-delete-block tool deserves special attention — block deletions are typically not recoverable (Notion keeps a trash for ~30 days, but content can be lost). Facio should require hard confirmation before any block deletion proceeds.

For multi-workspace setups (one Notion workspace per team, per customer, per project), the pattern is one OAuth integration per workspace with per-user tokens. The agent switches context per workspace, the audit trail is per-workspace, the HITL gating is per-workspace.

For multi-tenant SaaS setups, per-user OAuth tokens are essential. Each user authorizes their own Notion workspace, the agent acts on their behalf, the audit trail records which user authorized which action.

Quickstart

# 1. Create a Notion OAuth integration
#    https://www.notion.so/profile/integrations
#    Scopes: read_content (and others as needed)
#    Redirect URI: <your-app>/oauth/notion/callback

# 2. Install the MCP server
npm install -g @notionhq/notion-mcp-server

# 3. Configure your MCP client (minimal/read-only profile)
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server", "--readonly"],
      "env": {
        "NOTION_TOKEN": "secret_..."
      }
    }
  }
}

# 4. First prompts
# "What's our Q3 OKR for engineering?"
# "Find the latest meeting notes from the platform team"
# "Summarize the customer profile for Acme"
# "Generate a Jira ticket for the feature described in the Auth Migration spec"

Use Cases

Knowledge synthesis: "Read these 10 Notion docs and synthesize the key themes." Multi-page read → structured synthesis.

Spec-to-ticket conversion: "For the feature in the Notion spec, create the corresponding Jira/Linear ticket." Spec extraction → ticket creation.

OKR tracking: "What's the status of each Q3 OKR? Cross-reference with Linear." Notion (goals) + Linear (execution) → status report.

Customer context: "Pull everything we know about customer Acme." Multi-page search + fetch → customer dossier.

Onboarding documentation: "Generate the new-engineer onboarding doc from our Notion knowledge base." Workspace scan → structured doc.

Meeting notes synthesis: "Summarize this week's meeting notes across all teams." Multi-page read → summary.

Project status aggregation: "For each active project in Notion, find the related Linear issues and report the status." Cross-tool correlation → status report.

Documentation drift detection: "Compare the API spec in Notion to the actual OpenAPI spec in our repo. Flag discrepancies." Notion + repo comparison → drift report.

Search-driven answers: "What's our policy on X? Search Notion, return the relevant docs and a summary." Search + fetch + summarize.

Database CRUD: "Create a Notion database for tracking our Q4 initiatives with the right schema." Database creation with structured schema.

Workspace migration: "Move pages from our old workspace to the new one, preserving the structure." Cross-workspace page operations.

Compliance auditing: "Find every Notion page that mentions customer data and verify it has the right retention policy." Search + fetch + policy check.

Template generation: "Generate a new project page from our standard template, populated with the team's name and dates." Template instantiation + content.

Comment threads: "Pull the comment thread on the 'Auth Migration' page and summarize the discussion." Comment traversal + summary.

Cross-workspace search: "Find every Notion page across all workspaces that mentions 'GDPR'." Cross-workspace search.

Documentation generation: "Generate the API documentation by reading the spec pages and synthesizing." Spec synthesis → structured doc.

Release coordination: "Find every page related to the v2.0 release, summarize the status, list the blockers." Multi-page aggregation → release status.

Performance review prep: "Pull everything in Notion related to Alice's projects, last 6 months." Cross-page aggregation → review prep.

Knowledge graph building: "For the Memory MCP server, populate entities and relations from the team's Notion workspace." Notion → graph memory.

Team wiki maintenance: "Find stale pages (last edited > 6 months ago) in our team wiki. Flag for review." Workspace scan + age check → maintenance report.

The Two-Tool Minimalism Pattern

The Notion MCP server's defining innovation — 2 tools in the minimal profile, Markdown-native retrieval — is the design lesson every "knowledge-base-as-MCP" server should copy.

Why minimalism wins for knowledge bases:

• Context efficiency — 2 tool descriptions vs 25
• Markdown-native — 12x token savings vs raw JSON
• Always-current semantics — search index reflects current Notion API
• Composability — search + fetch compose into any read workflow
• Read-only default — minimal profile is zero destructive surface
• OAuth-friendly — small scope is easier to authorize

The tradeoff:

• More calls per workflow — search + fetch instead of direct page reads
• Less granular writes — minimal profile doesn't expose CRUD; standard profile does, but at the cost of more tools

For 95% of agent use cases (search docs, read pages, summarize, answer questions), the 2-tool minimal profile is the right default. For the 5% that need to write, the standard profile unlocks the full surface on operator opt-in.

The pattern applies to:

• Confluence — same minimal pattern (search + fetch as Markdown)
• Google Docs — same minimal pattern (search + fetch as Markdown)
• Quip — same minimal pattern
• Coda — same minimal pattern

Any wiki / doc-as-a-service that returns structured content can ship a 2-tool minimal MCP server with Markdown-native retrieval.

The Markdown-Native Pattern

The Notion MCP server's second defining innovation — convert Notion's JSON blocks to clean Markdown before returning — is the design lesson every "structured-content-as-MCP" server should copy.

Why Markdown-native wins:

• Token efficiency — 10-15x savings vs raw JSON
• Reasoning quality — the agent operates on meaning, not metadata
• Universal parsability — every agent, every system can read Markdown
• Diff-friendly — Markdown diffs are human-readable
• Round-trip safe — write back as Markdown when the operator wants edits

For any service that stores structured content (Notion, Confluence, Coda, GitHub issues, Linear comments, Sentry events), the MCP server should convert to Markdown by default. Raw JSON is for the API; Markdown is for the agent.

Bottom Line

The Notion MCP Server is the knowledge-base default for AI agents in 2026. 2 tools in the minimal profile (notion-search, notion-fetch), Markdown-native retrieval, OAuth 2.0 with principle-of-least-privilege scopes, MIT-licensed, official Notion-maintained. The bridge between any agent and the team's shared knowledge — engineering docs, product specs, OKRs, project plans, customer profiles.

For any agent that participates in knowledge work — spec-to-ticket conversion, OKR tracking, customer context, meeting synthesis, documentation generation — this is the bridge. The agent searches Notion, fetches the page as Markdown, reasons over the content. All with read-only defaults, all with OAuth-scoped access, all with full audit trail.

For the broader MCP ecosystem, the Notion pattern is the design lesson every "knowledge-base-as-MCP" server should copy. Two-tool minimalism + Markdown-native retrieval + OAuth with principle-of-least-privilege. When the knowledge-base interface is minimal, sanitized, and scope-scoped, the agent's access is safe.

npx -y @notionhq/notion-mcp-server --readonly with NOTION_TOKEN=secret_... and your agent has the team workspace.

---

MCP Spotlight is a series covering servers that give AI agents real capabilities. Every server is evaluated for design clarity, ecosystem impact, and integration fit with Facio's HITL-first agent runtime.