Blog

Notion MCP: connect Notion to Claude and agents

T. Krause ·

Notion MCP is Notion's own hosted MCP server at https://mcp.notion.com/mcp. You add that URL to an MCP client such as Claude Code, Cursor or Codex, sign in to Notion in the browser, and pick a workspace. From then on the agent can search, read and edit what your Notion account can see. For your own workspace in Claude, that is the whole setup.

An agent you build for other people is a different job. Each of your users has to connect their own workspace, the tokens have to live somewhere and be refreshed, and the agent may need GitHub or Slack as well as Notion. This guide sets up Notion's server first. Then it covers what an MCP client of your own has to handle, and connects Notion to Prompt TM for that case. The Notion details below come from developers.notion.com and Notion's GitHub as of November 2026.

What Notion's MCP server does

Notion describes it as a hosted server that "lets MCP clients work with Notion workspaces". The transport is Streamable HTTP. The older SSE endpoint, https://mcp.notion.com/sse, retires on February 23, 2027, so a client still set up for SSE needs the new URL before then.

You connect with OAuth. Per Notion's connection guide, once you authorize, "your AI assistant can read and update content that you can access in the selected workspace". There is no integration to create and no pages to share first.

The tool list is long. It covers search (notion-search, plus notion-connector-search for connected apps such as Slack and Google Drive), opening content (notion-fetch), pages (notion-create-pages, notion-update-page, notion-move-pages), databases and views (notion-query-data-sources, notion-create-view), comments, files, calendars and Notion's Custom Agents. Notion adds that "the tools available to you depend on your connection, permissions, and workspace plan".

Notion MCP "works on every plan". Some parts need Business or Enterprise: MCP tokens, search across connected apps (with Notion AI), and higher request limits. Every tool call counts toward Notion's standard API request limits.

Set up Notion MCP in Claude Code, Cursor and other clients

Claude Code. One command adds the server:

claude mcp add --transport http notion https://mcp.notion.com/mcp

Then run /mcp inside Claude Code and follow the OAuth flow. Add --scope user to have Notion in every project, or --scope project to share it with your team through .mcp.json. More on scopes and common errors is in Claude Code MCP server setup.

Cursor. Put this in .cursor/mcp.json in the project, or in ~/.cursor/mcp.json for all projects, then enable Notion under Customize and sign in:

{
  "mcpServers": {
    "notion": { "url": "https://mcp.notion.com/mcp" }
  }
}

Other clients. Notion's guide has steps for Codex, VS Code, Devin and several more. For any other client, add a remote server with the Streamable HTTP transport and the same URL. A client that only runs local stdio servers can reach it through the mcp-remote bridge (npx -y mcp-remote https://mcp.notion.com/mcp).

Without a browser. On Business and Enterprise plans, a workspace owner can create an MCP token in Notion's Developer portal. The client sends it as a bearer token, "with no browser sign-in".

The open-source notion-mcp-server

Older guides set up makenotion/notion-mcp-server, a local server run with npx and an integration token. Its README now says it is "no longer actively maintained or supported" and asks you to "use Remote Notion MCP instead". Notion also says "We may sunset this local MCP server repository in the future", and its connection guide calls the package deprecated. For a new setup, use the hosted server.

When the agent is yours and the workspaces are your users'

Notion's server suits a person connecting their own workspace to a client that already speaks MCP and OAuth. If you're building the agent, your code is that client. Notion's guide for building one lists what it must support: "OAuth 2.0 Authorization Code flow with PKCE", Streamable HTTP, "token refresh handling" and "secure credential storage". The token rules are strict:

  • Access tokens "currently last about eight hours", and refresh tokens "have a maximum lifetime of 180 days from authorization".
  • Every refresh returns a new refresh token, and the one you sent is retired. Notion warns that reusing a rotated one "can revoke the entire connection", so you must save each new token before the next request and never refresh one grant from two processes at once.
  • "An MCP access token works only with Notion MCP." Notion says not to send it to the REST API.

That's manageable for one app. An agent that also works in GitHub, Slack or Stripe needs the same storage, refresh and connect flow for each of them.

You wantUse
Your own workspace in Claude Code, Cursor, Codex or ClaudeNotion's hosted server, one command and a sign-in
A headless agent on your own Business or Enterprise workspaceNotion's hosted server with an MCP token
An agent you build that acts in your users' workspaces, next to other appsNotion's REST API behind a server that keeps the tokens (below)

Connect Notion to Prompt TM

Prompt TM serves Notion tools at one MCP URL, alongside any other toolkits you add. It calls Notion's REST API, not Notion MCP, with a credential it stores encrypted. The agent calls a tool such as NOTION_QUERY_DATABASE, Prompt TM adds the credential to the request, and the agent gets the result without ever seeing the credential.

The Notion toolkit takes two kinds of credential.

An internal connection fits your own workspace or a shared team tool. Per Notion's guide, a workspace owner creates one in the Developer portal, copies its API token from the Configuration tab, and grants it access to the pages and databases the agent should reach. Sharing a parent page also shares its child pages.

OAuth fits your users' workspaces. Register a Notion public integration, add https://www.prompt-tm.com/api/v3/auth/callback as its redirect URI, and put its client ID and secret on the auth config. Each user then signs in on Notion and, per Notion's docs, "selects pages in the OAuth page picker when authorizing the app".

1. Add an auth config for Notion. In the dashboard, open Auth configs → New, choose Notion and Access token for an internal connection or OAuth 2.0 for your own OAuth app. Or with the API:

curl -X POST https://www.prompt-tm.com/api/v3/auth_configs \
  -H "x-api-key: $PROMPT_TM_KEY" -H "content-type: application/json" \
  -d '{ "toolkit": { "slug": "notion" }, "auth_config": { "auth_scheme": "BEARER_TOKEN" } }'

For OAuth, send "type": "use_custom_auth", "auth_scheme": "OAUTH2" and "credentials": { "client_id": "...", "client_secret": "..." } instead.

2. Connect an account. With an internal connection's API token:

curl -X POST https://www.prompt-tm.com/api/v3/connected_accounts \
  -H "x-api-key: $PROMPT_TM_KEY" -H "content-type: application/json" \
  -d '{ "auth_config": { "id": "ac_..." }, "user_id": "me",
        "connection": { "data": { "token": "ntn_..." } } }'

Prompt TM checks the token with Notion before saving it. A rejected token answers 400 and the account is FAILED. For OAuth, POST /api/v3/connected_accounts/link returns a connect link on prompt-tm.com that sends the user to Notion's sign-in. Send that link to your user and they connect their own workspace. The link expires after one hour.

3. Create an MCP server. In MCP servers → New, choose Custom, tick Notion, and under Only some tools pick the tools the agent should see. Copy the server URL.

4. Add it to Claude Code.

claude mcp add --transport http prompt-tm-notion \
  "https://www.prompt-tm.com/mcp/mcp_...?user_id=me" \
  --header "x-api-key: $PROMPT_TM_KEY"

The name prompt-tm-notion keeps this server apart from Notion's own notion server if you added that earlier.

Claude Desktop, claude.ai, Cursor, VS Code, Windsurf and the agent SDKs are in the MCP client docs. claude.ai signs in with OAuth on prompt-tm.com, so no key goes into the URL. Then ask something the tools can answer, such as "Which tasks in the Roadmap database are due this week?"

What the agent can do once it's connected

The Notion toolkit has 14 tools. Seven only read:

ToolWhat it does
NOTION_SEARCHSearches page and database titles in everything shared with the integration
NOTION_GET_PAGEReturns a page's properties and metadata
NOTION_GET_BLOCK_CHILDRENLists the content blocks inside a page or block, which is how the agent reads a page body
NOTION_GET_DATABASEReturns a database's title and property schema
NOTION_QUERY_DATABASEReturns a database's rows, filtered and sorted with Notion's filter syntax
NOTION_LIST_USERSLists the people and bots in the workspace
NOTION_GET_COMMENTSLists the open comments on a page or block

Seven change the workspace:

ToolWhat it does
NOTION_CREATE_PAGECreates a page under a page, or a row in a database
NOTION_UPDATE_PAGEChanges a page's properties, icon or cover
NOTION_ARCHIVE_PAGEMoves a page to the trash
NOTION_APPEND_BLOCK_CHILDRENAdds content blocks to a page or block
NOTION_DELETE_BLOCKMoves a block to the trash
NOTION_CREATE_DATABASECreates an inline database inside a page
NOTION_CREATE_COMMENTComments on a page or replies in a discussion

These are the REST API's operations, a smaller set than Notion's hosted server offers. Search matches titles only, and the agent reads a page as blocks rather than Markdown. The Notion toolkit page lists every input. For an endpoint these tools don't cover, the REST proxy, POST /api/v3/tools/execute/proxy, sends the request to Notion with the same credential.

Limit what the agent can touch

The pages. With an internal connection, the agent reaches only the pages and databases you shared with the connection. With OAuth, it reaches the pages the user picked. In Notion you can also set the integration's capabilities, such as reading, updating or inserting content.

The tool list. A custom MCP server shows only the tools you ticked. To block the rest everywhere, set restrict_to_following_tools on the auth config. Accounts connected through it can then call only those tools, and the proxy answers 403 for them.

Approvals. Set the MCP server's approvals to Ask a person before destructive calls to hold NOTION_UPDATE_PAGE, NOTION_ARCHIVE_PAGE and NOTION_DELETE_BLOCK, or to Ask a person before any call that changes something to hold every write. A held call returns approval_required: true and does nothing yet. The approval link goes to your webhook and to the server's page in the dashboard, never to the agent, so the agent can't approve its own call.

The log. Each call appears under Logs with the tool, the user and the outcome.

To put Notion in a router with the rest of the catalogue instead of a fixed tool list, see tool router vs fixed tools. How OAuth for MCP clients works on both sides is in MCP OAuth for AI agents. Prompt TM is free during early access, with 20,000 tool calls per project per month. To try it, create a free project and connect a test page with an integration secret.