Notion MCP is Notion’s hosted Model Context Protocol server at https://mcp.notion.com/mcp. It lets compatible AI clients such as Claude Code, Cursor, VS Code, ChatGPT, and Codex search, fetch, create, and update content in a Notion workspace through user-based OAuth. It is useful for interactive, permission-scoped work, but its current hosted service does not support bearer-token authentication for fully headless agents or file uploads through MCP.
The short answer
Use Notion MCP when an AI client needs to work with Notion pages and databases as the signed-in user. Prefer the hosted Streamable HTTP endpoint, complete OAuth, review the granted workspace access, and keep human confirmation around consequential writes.
Do not confuse this with MCP connections for Notion Custom Agents. The directions are different:
Pattern | MCP client | MCP server | Purpose |
|---|---|---|---|
External AI → Notion | Claude Code, Cursor, ChatGPT, Codex, or another client | Notion’s hosted MCP | Let an external AI read and write Notion |
Notion Custom Agent → external system | Notion Custom Agent | Partner, custom, or internal MCP server | Give a Notion agent tools outside Notion |
Both use MCP, but the security boundary, identity, and failure modes are not the same.
What is the official Notion MCP endpoint?
Notion documents two endpoints:
Streamable HTTP:
https://mcp.notion.com/mcp— recommended;SSE:
https://mcp.notion.com/sse— legacy fallback for older clients.
For most installations, use Streamable HTTP. Verify the exact mcp.notion.com host before authorizing. Notion warns that marketplace listings and third-party installers can create domain-confusion risk.
How do you connect an AI client?
The client must support a remote MCP server or use a bridge.
Generic remote configuration
{
"mcpServers": {
"notion": {
"url": "https://mcp.notion.com/mcp"
}
}
}The exact configuration key varies by client. After the server is added, the first tool call normally begins the OAuth flow.
Claude Code
Notion documents:
claude mcp add --transport http notion https://mcp.notion.com/mcpThen run /mcp and complete OAuth.
Cursor
Add a global or project MCP configuration using the hosted URL. Project-level configuration shares the server location, not another person’s OAuth credentials.
VS Code
Add the server to .vscode/mcp.json, start it through the MCP command surface, and authenticate.
Clients without remote HTTP support
Notion suggests an mcp-remote bridge as a compatibility option. A bridge adds another dependency and execution boundary, so teams should review the package and pin how it is invoked.
How does Notion MCP authenticate?
The hosted service uses user-based OAuth. A person authorizes the client, and the connected AI operates with access based on that user and the Notion resources available to them.
For custom MCP clients, Notion documents OAuth 2.0 Authorization Code with PKCE, protected-resource and authorization-server discovery, dynamic client registration or supported client metadata, token refresh, and secure credential storage.
This is a strength for interactive use: the user can inspect the authorization and does not paste a long-lived integration token into every client.
It is also a limitation for headless use. Notion says the hosted MCP does not currently support bearer-token authentication. A fully automated cloud agent cannot rely on a person completing OAuth every time a new execution environment starts.
Can Notion MCP run without a human?
Not always.
A long-lived client can refresh an existing OAuth grant, but the initial authorization is user-driven. For a truly headless workflow, Notion points to its older open-source MCP server with a Notion API token. That package is no longer actively maintained, and self-hosters own deployment, token storage, upgrades, and exposure.
The decision is therefore:
interactive assistant: hosted Notion MCP is the default;
managed long-lived client with an existing grant: hosted MCP may work if refresh and secure storage are reliable;
unattended automation with service identity requirements: evaluate the public API or a maintained internal MCP layer rather than assuming hosted OAuth fits.
What tools does Notion MCP provide?
The current tool catalog includes operations for several resource types. Important examples include:
Search
notion-search searches the Notion workspace and, when the required Notion AI access exists, connected sources such as Slack, Google Drive, and Jira.
Without Notion AI access, connected-source search is restricted and workspace search remains the relevant scope.
Fetch
notion-fetch retrieves a page, database, or data source by URL or ID. Database responses can expose data-source schema and available templates for later create or update operations.
Create pages
notion-create-pages creates one or more pages with content and properties. It can apply database templates and set supported icons or external cover URLs.
Update pages and data
The catalog includes page and database operations for changing content, properties, schemas, and status fields where supported.
Comments and other operations
The tool set also covers comments and workspace-specific utilities. Tool names can be adapted by a client; Notion notes that OpenAI clients may expose fetch and search without the notion- prefix.
Always inspect the actual tool list presented by the connected server rather than relying on a copied list.
What are the main limitations?
No MCP file upload
Notion’s hosted MCP does not currently support image or file upload. An AI can create a page with an external cover URL, but uploading a local binary requires the separate file upload API or another integration path.
User OAuth, not bearer tokens
Hosted MCP is not a drop-in service account. This affects unattended agents, centralized automation, and infrastructure that cannot present an interactive authorization flow.
Source permissions still matter
Connecting the server does not create new Notion access. Search and fetch behavior depend on the authorizing user and plan. Connected-source search also depends on Notion AI access and configured connections.
Rate limits
Notion documents a general average of 180 requests per minute per user across MCP tool calls and a search-specific limit of 30 requests per minute. These values may change.
Large fan-out prompts can hit the search limit even when the total request limit has capacity. Reduce parallel searches, batch work, cache fetched context inside the client session, and retry with backoff.
MCP cannot fix weak workspace structure
Search access does not make obsolete pages current, define authoritative sources, or resolve conflicting ownership. AI can amplify whatever governance already exists.
What is the security model?
A useful mental model is:
AI client → OAuth user identity → Notion MCP → resources visible to that user
This creates five checks.
1. Trust the client
The AI client receives content and can request writes. Use a client your organization has reviewed. Treat plugins, bridges, and marketplace installers as software supply-chain dependencies.
2. Verify the endpoint
Use https://mcp.notion.com/mcp or the documented SSE fallback. Lookalike domains can capture an authorization attempt.
3. Minimize the user’s access
If a client needs one project, authorizing a workspace owner with broad access creates unnecessary exposure. Use a dedicated human account or scoped workspace role when the operating model permits it.
4. Review writes
Searching a document and changing a roadmap are different risk classes. Configure the client to show tool arguments and require approval for destructive, externally visible, or high-impact changes.
5. Audit and revoke
Know where to disconnect the client, revoke access, inspect changes, and respond to a compromised device or token.
What threats should teams test?
Threat | Example | Control |
|---|---|---|
Prompt injection | A page tells the AI to ignore the user and alter another database | Treat retrieved content as untrusted; isolate tool decisions |
Over-broad identity | A workspace owner authorizes a casual coding experiment | Use least privilege and separate environments |
Unreviewed write | A generated task update changes status across many records | Preview scope and require confirmation |
Endpoint spoofing | A marketplace points to a lookalike server | Verify the official hostname |
Token exposure | OAuth credentials leak through logs or project files | Use client credential storage; never commit tokens |
Rate-limit cascade | Parallel searches trigger repeated retries | Bound concurrency and use backoff |
Stale authority | AI finds an obsolete but popular page | Preserve verification, owner, and freshness signals |
MCP standardizes tool exchange. It does not eliminate prompt injection, authorization design, or operational review.
Notion MCP versus the Notion API
Question | Hosted Notion MCP | Notion API |
|---|---|---|
Primary consumer | AI client | Application or integration |
Authentication | User OAuth through MCP flow | OAuth or integration token depending on design |
Tool shape | Agent-oriented tools | Endpoint and SDK operations |
Interactive setup | Easy in supported clients | Integration development required |
Headless automation | Limited by user-based OAuth | Better fit for service integrations |
File upload | Not through hosted MCP | File upload API available |
Control over orchestration | Client prompt and MCP tools | Application code |
Maintenance | Hosted by Notion | Your application and integration |
Choose MCP for assisted work inside an AI client. Choose the API when you need deterministic application behavior, service identities, webhooks, custom retries, or deeper integration control.
Notion MCP versus the old open-source server
Notion’s hosted server is actively maintained, uses OAuth, requires no server deployment, and provides AI-optimized tools.
The open-source notion-mcp-server is no longer actively maintained. It can still be relevant when bearer-token authentication or legacy JSON v1 API behavior is mandatory, but users accept:
self-hosting;
token management;
dependency and security maintenance;
compatibility work;
lack of active upstream issue handling.
“Open source” is not automatically the safer choice if nobody owns updates.
What can teams build with Notion MCP?
Turn research into a PRD
The AI searches project context, fetches current decisions, creates a draft PRD, and links the evidence. A reviewer confirms assumptions before the document becomes authoritative.
Update tasks from code context
A coding assistant fetches a task, performs work in the repository, then proposes a status and implementation note. The user reviews the write.
Build a release report
The client searches release notes, fetches relevant project pages, reconciles changes, and creates a report. The workflow should distinguish current release evidence from stale planning pages.
Prepare a campaign brief
The AI retrieves goals, research, audience notes, and prior results, then creates a structured brief and task pages.
Answer a workspace question
Search finds relevant pages, fetch retrieves the evidence, and the client answers with URLs. This is safer than relying on a free-form summary without source links.
A safe implementation pattern
Add the official Streamable HTTP endpoint.
Complete OAuth with an appropriately scoped user.
Inspect the available tools and client approval settings.
Start with read-only search and fetch prompts.
Test pages the user can and cannot access.
Add one bounded create workflow.
Require confirmation for updates and multi-page operations.
Test prompt injection inside a retrieved page.
Test rate-limit and partial-failure behavior.
Document revocation, incident ownership, and token storage.
Review the integration after Notion or the client changes.
Expand only when evidence and permission checks pass.
How do MCP connections for Custom Agents differ?
A Notion Custom Agent can connect outward to Slack, Mail, Calendar, partner MCP integrations, or a custom MCP server. The agent has its own resource access and can run on schedules or triggers.
This changes the identity model:
trigger or user → Custom Agent identity → external MCP server → external resource
The external server must authorize the agent’s operations. The fact that someone can interact with the Custom Agent does not automatically mean they should receive every result its external access can retrieve.
Review:
who can configure the agent;
who can interact with it;
which Notion resources it sees;
which external tools and scopes it receives;
which writes require approval;
how activity and external audit logs correlate;
how credit limits affect the workflow.
How does Dokki fit?
Dokki also exposes workspace resources through MCP so authorized AI clients can search, read, create, and edit shared documents, tables, files, and other resource types. The relevant comparison is not “has MCP” versus “does not have MCP.” Both products support MCP.
Compare the operating model:
how a client chooses and scopes the workspace;
how structured resources such as tables are exposed;
how people and agents share the same resource;
which operations are explicit and typed;
how resource metadata supports publishing and workflow state;
how authentication works for interactive and long-lived clients;
how public publishing is separated from internal editing.
The winning system is the one whose identity, resource, review, and publishing model matches the workflow.
Frequently asked questions
What is the Notion MCP URL?
Use https://mcp.notion.com/mcp for Streamable HTTP. The legacy SSE endpoint is https://mcp.notion.com/sse.
Is Notion MCP official?
Yes. The hosted server and documentation are provided by Notion. Verify the exact hostname.
Does Notion MCP support read and write?
Yes. It provides tools to search, fetch, create, and update supported Notion content according to the authorized user’s access.
Can Notion MCP upload images?
Not through the hosted MCP at the time of verification. Use Notion’s file upload API for binary uploads.
Can I use a Notion integration token with the hosted MCP?
Notion says the hosted server requires user OAuth and does not support bearer-token authentication. The older self-hosted server can use a token but is no longer actively maintained.
Does Notion MCP search Slack or Google Drive?
The search tool can search connected sources when the workspace has the required Notion AI access and those connections are configured.
What are the rate limits?
Notion currently documents an average general limit of 180 requests per minute per user and 30 searches per minute, subject to change.
Is MCP safe for autonomous writes?
It can be operated safely only with trusted clients, least privilege, bounded tools, approval rules, prompt-injection defenses, audit, and tested recovery. The protocol itself does not supply those controls automatically.
_Last verified: July 21, 2026._