MCP Spotlight: Notion MCP Server — The Markdown-First Knowledge Bridge With Database API v2, OAuth 2.0, and the Documentation/Project Hub Default for Agents

Server: Notion MCP Server by Notion License: MIT (open source) · Status: GA, official Notion-maintained Auth: Internal Integration Token · OAuth 2.0 (with Notion-hosted flow) Tools: ~17 (search, fetch, create, update, archive, comments, data sources) Coverage: Pages · Databases · Data Sources · Blocks · Comments · Users · Search API: Notion API version 2025-09-03 (with Data Sources — the v2 database abstraction) Docs: developers.notion.com/docs/mcp-server MCP Tracker: glama.ai/mcp/servers?query=notion

Every useful agent eventually needs persistent knowledge. Conversation history is volatile. Filesystem storage is unstructured. Custom databases require schema work. The right default for most teams: Notion. Pages for prose, databases for structure, blocks for flexibility, comments for collaboration, search for discovery. The official Notion MCP Server gives AI agents the full Notion surface — pages, databases, data sources, blocks, comments — through ~17 well-designed tools, with OAuth 2.0, the new Notion API Data Sources abstraction (v2), and Markdown-friendly inputs.

This is the documentation + project hub + knowledge base default for AI agents in 2026.

The Architecture: Tools for Knowledge Work

The Notion MCP Server's tool surface is organized around how knowledge work actually flows:

Category	Tools	Purpose
Search	search	Full-text + filter search across pages and databases
Fetch	fetch, get_block_children, get_database, get_data_source, get_page_property, get_user, get_self, get_comment	Read pages, blocks, databases, users
Create	create_page, create_database, create_data_source, create_comment	Add new entities
Update	update_page, update_block, update_data_source, append_block_children	Modify entities
Lifecycle	archive_page, move_page	Soft-delete and reorganize

The tools are focused. The agent gets the high-leverage primitives — search, fetch, create, update, archive — and composes them into knowledge workflows.

The New Notion API: Data Sources (v2)

The September 2025 release of the Notion API introduced Data Sources as a v2 abstraction over databases. This is a significant architectural change:

• A database is now a top-level container
• A data source is the schema + query interface within a database
• A database can have multiple data sources with different schemas (e.g., one database holding both "Tasks" and "Subtasks" data sources)

The MCP server exposes this natively:

get_database(database_id="...")
  → Returns the database with its list of data sources

get_data_source(data_source_id="...")
  → Returns the schema, properties, and current rows

query_data_source(data_source_id="...", filter={...}, sort=[...])
  → Returns matching rows with their properties

For teams that have complex Notion setups (one workspace holding multiple data sources per project), the v2 abstraction matches the mental model. For new users, the v2 model is the only model — they're starting with the cleaner architecture.

Search: The First Move

The search tool is the agent's entry point for everything:

search(query="Q3 roadmap", filter={property: "object", value: "page"})
  → Returns matching pages with title, last edited time, parent

search(query="", filter={property: "object", value: "data_source"}, sort="last_edited_time:desc")
  → Returns all data sources, most recently edited first

search(query="API", filter={
  property: "object",
  value: "page"
}, sort="last_edited_time:desc", limit=10)
  → Top 10 pages matching "API", most recently edited first

The search supports filters by object type (page, database, data_source), filters by parent (specific page or database), and full-text query against titles and content. Combined with the agent's iterative search → fetch → update loop, this is the standard knowledge-workflow primitive.

Fetch: Pages, Blocks, Properties

The fetch tool is the universal read:

fetch(page_id="...")
  → Returns the page with its full block content as Markdown-friendly output

fetch(block_id="...")
  → Returns the block (paragraph, heading, list, callout, code, etc.)

The MCP server is Markdown-first — outputs are Markdown-friendly, not raw Notion JSON. The agent reads clean Markdown; Facio logs the structured request and response; humans can review the agent's view of the workspace in a format they recognize.

For nested pages, the get_block_children tool walks the tree:

get_block_children(block_id="page_root_id")
  → Returns the page's top-level blocks

get_block_children(block_id="child_block_id")
  → Returns the nested blocks

The agent can recursively walk a page to get the full content. For long pages, the server paginates with cursor-based navigation.

Create: Pages, Databases, Comments

The create_page tool creates a page under a parent (database, data source, or another page):

create_page(
  parent={database_id: "..."},
  properties={
    "Name": {"title": [{"text": {"content": "API redesign kickoff"}}]},
    "Status": {"select": {"name": "In Progress"}},
    "Owner": {"people": [{"id": "..."}]}
  },
  children=[
    {object: "block", type: "heading_1", heading_1: {rich_text: [{text: {content: "Goals"}}]}},
    {object: "block", type: "paragraph", paragraph: {rich_text: [{text: {content: "..."}}]}}
  ]
)

One tool call creates the page + sets properties + writes the initial block content. The page is immediately searchable, immediately linkable, immediately editable.

For comments:

create_comment(
  parent={page_id: "..."},
  rich_text=[{text: {content: "Reviewed. Looks good. One nit on the migration plan."}}]
)

The agent participates in human discussions without leaving the Notion context.

Update: Surgical and Bulk

The update tools cover both surgical edits and bulk operations:

Tool	Use Case
update_page	Change properties, archive, move to a different parent
update_block	Change a single block's content
append_block_children	Add blocks to an existing page (appends)
update_data_source	Change schema (add/remove properties)

The append_block_children tool is the right primitive for incrementally building a page:

# Build a weekly review page incrementally
append_block_children(parent={page_id: "weekly_review_..."}, children=[
  {type: "heading_2", heading_2: {rich_text: [{text: {content: "Wins"}}]}},
  {type: "bulleted_list_item", bulleted_list_item: {rich_text: [{text: {content: "Shipped v1.2"}}]}}
])

# Later, add the "Blockers" section
append_block_children(parent={page_id: "weekly_review_..."}, children=[
  {type: "heading_2", heading_2: {rich_text: [{text: {content: "Blockers"}}]}},
  {type: "paragraph", paragraph: {rich_text: [{text: {content: "Waiting on auth API."}}]}}
])

The page grows section by section as the agent gathers content. The user can watch the page evolve in real time.

OAuth 2.0 and Internal Integration Tokens

Notion supports two auth modes for the MCP server:

Internal Integration Token (recommended for personal agents)

# Create at https://www.notion.so/profile/integrations
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/mcp-server"],
      "env": {
        "NOTION_TOKEN": "${credentials.NOTION_TOKEN}"
      }
    }
  }
}

The integration is shared with specific pages/databases via Notion's UI. The agent's scope is exactly what the user explicitly shared. No implicit workspace access.

OAuth 2.0 (for multi-tenant SaaS agents)

For SaaS products that embed Notion on behalf of their users, Notion's OAuth flow lets the user authorize the SaaS to act on their Notion account. The user sees the scopes, the requesting app, and the access level. The SaaS never sees the user's Notion credentials.

Combined with Facio's destructive-operation gating, this creates the same defense-in-depth model as the other platform MCP servers.

Facio Integration

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

Facio's audit trail captures every Notion MCP call with the tool, the page/database/data-source ID, the action, the content, and the result. For a regulated team (SOC2, ISO 27001, GDPR), this is the complete knowledge-base record: "Agent created page 'Q3 OKRs' under database 'Goals' at 14:32 UTC, with 12 blocks of content, shared with team 'API'."

For HITL workflows, the tool annotations map to gate requirements:

Tool	Severity	Suggested Gate
search, fetch, get_*	Read	None — autonomous
create_comment	Write, low risk	Soft confirm
create_page (under personal parent)	Write, contextual	Soft confirm
create_page (under shared database)	Write, contextual	Hard confirm (visible to team)
update_page (properties)	Write, contextual	Soft confirm
update_block	Write, surgical	Soft confirm (review the diff)
append_block_children	Write, additive	Soft confirm (review content)
archive_page, move_page	Write, destructive in effect	Hard confirm + reason required
create_database, create_data_source	Write, structural	Hard confirm (schema change visible to team)
update_data_source (schema)	Write, structural	Hard confirm (schema migration)

The archive_page tool deserves special attention — Notion's archive is a soft-delete (the page is recoverable), but in practice it's the "I want this gone" operation. Facio should require hard confirmation with a stated reason before archiving anything that's shared with other humans.

For multi-workspace setups (one Notion workspace per team, per product, per region), the pattern is one MCP server per workspace, each with its own integration token. The agent switches context per workspace, the audit trail is per-workspace, and the HITL gating is per-workspace.

Quickstart

# 1. Create a Notion internal integration
#    https://www.notion.so/profile/integrations
#    Share specific pages/databases with the integration

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

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

# 4. First prompts
# "Find all pages related to 'Q3 roadmap'"
# "Create a weekly review page under 'Team Reviews' database"
# "Update the status of 'API redesign' page to Done"
# "Summarize the last 10 edits to our 'Engineering Practices' page"
# "Create a new task in 'Q3 Tasks' database, assign to Kevin, due next Friday"

Use Cases

Documentation generation: "Generate API documentation from the source code and create a page in our 'Docs' database." Agent reads code via Filesystem MCP → drafts docs → creates Notion page with code blocks.

Weekly standup automation: "For each team member, pull their closed tasks this week and create a standup summary page." Aggregate data from Linear/Jira MCP → format → create page.

Meeting notes: "After a meeting, create a structured meeting notes page with attendees, decisions, action items. Link the action items to our task database." Templated page creation.

Project hub setup: "Create a new project hub page with sections for Goals, Timeline, Team, and Risks. Link the related tasks and docs." Multi-block page creation.

Database queries: "Show me all open bugs assigned to the API team, sorted by priority." Query data source → format → respond.

Knowledge base search: "Find all pages that mention 'OAuth' and summarize the key patterns we use." Search → fetch → summarize → respond.

Onboarding documentation: "Generate a new-hire onboarding page from our team practices docs." Aggregate → structure → create.

Cross-tool linking: "For each Sentry issue from last week, find the related Linear task and link them in our 'Incidents' database." Multi-source correlation.

Status reports: "Generate a weekly status report from our projects, with progress, blockers, and next steps." Multi-data-source aggregation.

Roadmap updates: "Pull all closed tasks from last quarter, group by initiative, and draft a roadmap update page." Cross-database query → synthesis → structured page.

Customer feedback synthesis: "Read all customer feedback from the last 30 days, group by feature request, and create a feature request page in our 'Product' database." Cross-source aggregation.

Content publishing: "Take this blog post draft and publish it to our 'Marketing' Notion database with proper SEO metadata and tags." Create page with structured properties.

Personal note-taking: "Save this research note to my 'Reading List' database, tagged with 'AI Agents' and 'Architecture'." Single-page creation with metadata.

Internal wiki maintenance: "Find pages in our wiki that haven't been updated in over a year and flag them for review." Search → filter → report.

Bottom Line

The Notion MCP Server is the knowledge + project hub + documentation default for AI agents in 2026. ~17 tools, OAuth 2.0 + Internal Integration Token support, native Notion API v2 Data Sources, Markdown-friendly output, MIT-licensed, official Notion-maintained.

For any agent that participates in human knowledge work — documentation, project tracking, weekly reviews, meeting notes, research synthesis, status reports — this is the bridge. The agent reads pages, searches the workspace, creates new entries, updates existing records, and links across databases. All through Notion's UI, all with the user's explicit sharing scope, all with full audit trail.

For the broader MCP ecosystem, Notion's pattern is the design lesson every "knowledge-as-API" MCP server should copy. The right primitive for an agent's knowledge is the same primitive humans use: pages for prose, databases for structure, blocks for flexibility, comments for collaboration, search for discovery. When the agent's knowledge substrate matches the human's, the collaboration feels natural.

npx -y @notionhq/mcp-server with NOTION_TOKEN=secret_... and your agent has Notion.

---

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