Notion MCP Server
for AI Agents

Q: What AI frameworks and AI clients does the StackOne Notion MCP server support?

The StackOne Notion MCP server supports both. MCP clients (paste-and-go apps): Claude Desktop, Claude Code, Cursor, VS Code, Goose. Agent frameworks (code SDKs you build with): OpenAI Agents SDK, Anthropic, Vercel AI, Google ADK, CrewAI, Pydantic AI, LangChain, LangGraph, Azure AI Foundry.

Production-ready Notion MCP server with 35 extensible actions — plus built-in authentication, security, and optimized execution.

Start Free Book Demo Read Docs →

Notion MCP Server

Built by

StackOne

Coverage

35 Agent Actions

Create, read, update, and delete across Notion — and extend your agent's capabilities with custom actions.

MCP Actions → Create Actions →

Authentication

Agent Tool Authentication

Per-user OAuth in one call. Your Notion MCP server gets session-scoped tokens with zero credentials stored on your infra.

Agent Auth →

Security

Agent Protection

Every Notion tool response scanned for prompt injection in milliseconds — 88.7% accuracy, all running on CPU.

Prompt Injection Defense →

Performance

Max Agent Context. Min Cost.

Free up to 96% of your agent's context window to enhance reasoning and reduce cost, on every Notion call.

Tools Discovery →

What is the Notion MCP Server?

A Notion MCP server lets AI agents read and write Notion data through the Model Context Protocol — Anthropic's open standard for connecting LLMs to external tools. StackOne's Notion MCP server ships with 35 pre-built actions, fully extensible via the Connector Builder — plus managed authentication, prompt injection defense, and optimized agent context. Connect it from MCP clients like Claude Desktop, Claude Code, Cursor, Goose, and VS Code, or from agent frameworks like OpenAI Agents SDK, LangChain, and Vercel AI SDK.

How Your AI Agent Uses the Notion MCP Server

Prompt your Notion MCP Agent

Works with

Your AI Agent

Ask your agent...

Notion

Actions will appear here...

Untitled

Waiting for agent...

Interactive demo available on desktop.

All Notion MCP Tools and Actions

Every action from Notion's API, ready for your agent. Create, read, update, and delete — scoped to exactly what you need.

Block Children

Append Block Children
Append blocks to a parent block or page
Get Block Children
Retrieve children of a block

Blocks

Get Block
Retrieve a block by ID
Update Block
Update a block's content
Delete Block
Delete a block

Comments

Create Comment
Create a comment on a page, block, or discussion thread
List Comments
List comments from a page or block
Retrieve Comment
Retrieve a specific comment by ID

Databases

Create Database
Create a new database with initial data source
Get Database
Retrieve a database by ID
Update Database
Update database-level properties

Data Sources

Create Data Source
Create a new data source in an existing database
Retrieve Data Source
Retrieve a data source by ID
Query Data Source
Query a data source and retrieve pages
Update Data Source
Update a data source's properties and metadata

File Uploads

Create File Upload
Initiate a file upload session in the Notion workspace, returning a file upload object with an upload URL for sending file data via send_file_upload
Send File Upload
Upload file contents for a pending file upload
List File Uploads
List all file uploads for the bot integration
Retrieve File Upload
Get details of a specific file upload by ID

Users

List Users
List all users in the workspace
Get User
Retrieve a user by ID

Other (10)

List Data Source Templates
List all page templates for a data source
Get Current Credentials (Notion Identity)
Return the authenticated identity and auth type for the current Notion connection. Wraps Notion's GET /users/me endpoint which returns the bot user associated with the API token or OAuth access token. Maps to the StackOne IAM unified credentials schema (name, auth_type). auth_type is inferred from credentials shape (clientId present → oauth, otherwise api_key).
List IAM Organizations (Notion Workspace)
List the Notion workspace bound to this integration as a single IAM organization. Notion integrations are scoped to exactly one workspace; this action returns one entry derived from the bot user object on GET /users/me. id is the workspace_id (UUID), name is the workspace_name. Always returns 0 or 1 results.
Get IAM Organization (Notion Workspace)
Retrieve the Notion workspace bound to this integration as a single IAM organization. Re-fetches GET /users/me and returns the workspace entry IF the provided id matches the bound workspace_id (or workspace_name fallback). Notion has no per-workspace lookup endpoint on the public API; the connection is scoped to one workspace, so this action always resolves to that workspace or 404s.
List IAM Users (Notion Workspace Members And Bots)
List every Notion workspace user (people + bots) mapped to the IAM unified user schema, cursor-paginated. Wraps Notion GET /users. Each entry includes is_bot_user, primary_email_address (people only), and avatar. Notion does not expose status, login timestamps, or roles via the public API — those are unmapped.
Get IAM User (Notion Workspace Member Or Bot)
Retrieve a single Notion user by ID, mapped to the IAM unified user schema. Wraps GET /users/{id}. Returns the same field coverage as unified_list_users — id, name, is_bot_user, primary_email_address (people only), avatar.
Get Page Property
Retrieve a page property item
Search
Search all pages and data sources
Get Bot User
Retrieve information about the bot user
Complete File Upload
Finalize a multi-part file upload

Set Up Your Notion MCP Server in Minutes

One endpoint. Any framework. Your agent is talking to Notion in under 10 lines of code.

MCP Clients

Agent Frameworks

Claude Desktop-

JSON

Browse Claude Desktop MCP Docs

{
  "mcpServers": {
    "stackone": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://api.stackone.com/mcp?x-account-id=<account_id>",
        "--header",
        "Authorization: Basic <YOUR_BASE64_TOKEN>"
      ]
    }
  }
}

Notion MCP Server Resources

Notion MCP Server: Capabilities, Limitations, and Alternatives

The official Notion MCP server handles search and retrieval well. This post covers what it can't do and when the StackOne MCP server is the right alternative.

9 min

MCP Code Mode: Keeping Tool Responses Out of Agent Context

Anthropic's code_execution processes data already in context. Custom MCP code mode keeps raw tool responses in a sandbox. 14K tokens vs 500.

11 min

Comparing BM25, TF-IDF, and Hybrid Search for MCP Tool Discovery

Benchmarking BM25, TF-IDF, and hybrid search for MCP tool discovery across 916 tools. The 80/20 TF-IDF/BM25 hybrid hits 21% Top-1 accuracy in under 1ms.

10 min

Indirect Prompt Injection Defense for MCP Tools: A Technical Guide

MCP tools that read emails, CRM records, and tickets are indirect prompt injection vectors. Here's how we built a two-tier defense that scans tool results in ~11ms.

12 min

Notion MCP Server FAQ

Notion MCP server vs direct API integration — what's the difference?

A Notion MCP server and direct API integration serve different use cases. Direct API integration is for software-to-software — backend code calling Notion. A Notion MCP server is for AI agents — MCP clients like Claude and Cursor, plus framework agents built with OpenAI, LangChain, or Vercel AI — discovering and calling Notion at runtime. StackOne provides both.

How does Notion authentication work for AI agents?

Notion authentication for AI agents works through a StackOne Connect Session. Create one via the dashboard or the SDK — you get an auth link and ready-to-paste config for Claude Desktop, Cursor, and other MCP clients. Your user authenticates their own Notion account; StackOne handles token exchange, storage, and refresh. Credentials never reach the LLM, and each user is isolated via origin_owner_id.

Are Notion MCP tools vulnerable to prompt injection?

Yes — Notion MCP tools can be vulnerable to indirect prompt injection. Any tool that reads user-written content — documents, messages, tickets, records, or free-text fields — is a potential vector. StackOne Defender scans every tool response before it enters the agent's context — regex patterns in ~1ms, then a MiniLM classifier in ~4ms. 88.7% accuracy, CPU-only.

What is the context bloat of a Notion agent and how do I avoid it?

Context bloat happens when Notion tool schemas and API responses eat your Notion agent's memory, preventing it from reasoning effectively. A single Notion query can return a massive JSON response, and connecting multiple tools compounds the problem. Tools Discovery and Code Mode reduce context bloat — loading only relevant tools per query and keeping raw responses out of the agent's context.

Can I limit which actions my Notion agent can access?

Yes — you can limit which actions your Notion agent can access directly from the StackOne dashboard. Toggle actions on or off, or restrict them to specific accounts, with no code changes to your agent. Session tokens can be scoped to exact actions so if one leaks, exposure stays contained.

Can I create custom agent actions for my Notion MCP server?

Yes — you can create custom agent actions for your Notion MCP server using Connector Builder. It's an integration agent your coding assistant (Claude Code, Cursor, or Copilot) can invoke to research Notion's API, generate production-ready connector YAML, test against the live API, and validate before you ship.

When should I NOT use a Notion MCP server?

Skip a Notion MCP server if your integration is purely software-to-software — direct Notion API integration is simpler when no AI agent is involved. For deterministic, compliance-critical operations (financial transactions, regulatory reporting), direct API gives you predictable behavior without agent-driven decision-making. MCP shines when AI agents need to dynamically discover and call Notion actions at runtime.

What AI frameworks and AI clients does the StackOne Notion MCP server support?

The StackOne Notion MCP server supports both. MCP clients (paste-and-go apps): Claude Desktop, Claude Code, Cursor, VS Code, Goose. Agent frameworks (code SDKs you build with): OpenAI Agents SDK, Anthropic, Vercel AI, Google ADK, CrewAI, Pydantic AI, LangChain, LangGraph, Azure AI Foundry.

Put your AI agents to work

All the tools you need to build and scale AI agent integrations, with best-in-class connectivity, execution, and security.

Start Free Book Demo