How to set up the Notion MCP server

Notion is a collaborative workspace for pages, databases, and knowledge management. Use OAuth for per-user access, a workspace-owned MCP token for supported shared automation, or an enterprise IdP path where required.

This guide is the source of truth for preparing Notion's MCP server for any compatible MCP client. The Notion agent template is separate; it provisions the Dome workspace, agent, model, tools, and rules after the Notion authorization path is ready.

Notion's hosted MCP server is https://mcp.notion.com/mcp. It uses Streamable HTTP, which Notion recommends for new clients. https://mcp.notion.com/sse is the fallback for clients that cannot use Streamable HTTP.

Choose a connection method

Choose per-user OAuth for interactive access. Choose a workspace-owned MCP token for approved shared automation on a Business or Enterprise plan. Use the legacy self-hosted server or enterprise IdP flow only when the hosted OAuth/token paths cannot meet a documented requirement. Notion's MCP documentation describes these supported routes.

Recommended: Per-user OAuth

Use OAuth for an interactive, user-delegated connection. It is the recommended path because the user authorizes the Notion workspace they can already access; no Notion API key or manually created integration is needed.

1. Configure the MCP client with https://mcp.notion.com/mcp.
2. Start the client’s OAuth connection flow and sign in as a workspace member. Guests cannot connect Notion MCP.
3. Select the intended workspace and approve the connection.
4. Verify the tools against one known page or database that the test user can access.
5. Disconnect from the client or Notion when the connection should end.

Notion MCP OAuth uses authorization-code flow with PKCE, dynamic client registration, token refresh, and secure credential storage. A client should use OAuth metadata discovery rather than hard-code authorization endpoints. Notion’s MCP client guide is the reference implementation.

Recommended for shared automation: Workspace-owned MCP token

For a non-interactive shared connection, use an MCP token rather than a personal OAuth grant. This option is available on Notion Business and Enterprise plans, and only a workspace owner can create the token in the Developer portal.

1. Create the token as a workspace owner and assign it only to the intended automation.
2. Store it in the MCP connection as a secret; never put it in a prompt, repository, or runtime environment.
3. Send it as a bearer token to https://mcp.notion.com/mcp.
4. Verify a known, scoped workspace action and record the owner, workspace, intended use, and rotation date.

Use this only when a shared connection is necessary. Per-user OAuth is safer for ordinary interactive use because it preserves the user boundary.

Legacy alternative: Self-host the old open-source server

Notion’s old notion-mcp-server can authenticate with a Notion integration token. It requires you to host and operate the server yourself, and Notion says it is no longer actively maintained. Do not choose it for a new deployment when the hosted MCP server can meet the use case.

If a legacy client forces this route, create a dedicated Notion integration, share only the required pages and databases with it, store the integration token as a secret, and plan a migration to hosted Notion MCP. A Notion integration token is not an authentication alternative for the hosted mcp.notion.com server.

Enterprise alternative: IdP-managed authorization

Enterprise workspaces with SAML SSO can use Notion’s enterprise-managed authorization. In that model, the company identity provider issues a short-lived identity assertion for the user rather than presenting an interactive consent screen. Use it only when your identity team owns the IdP integration and has reviewed the mapping from company identity to Notion workspace access.

Verify Notion MCP

Use this checklist to confirm the MCP server is connected with the intended access.

• Confirm the client discovers Notion tools after authorization.
• Search a known test page or data source.
• Confirm access to an unrelated workspace or unshared content is denied.
• For OAuth, confirm the connected user and workspace are the intended ones; for a token, confirm the workspace owner and token purpose are recorded.
• Review available write tools before attaching the server to an agent with write authority.

For endpoint, transport, client setup, workspace-admin controls, and current plan limits, use Notion’s official MCP documentation.

Troubleshooting

If the setup does not work as expected, check these common causes.

• If OAuth cannot start, confirm that the person connecting is a Notion workspace member rather than a guest and that the client supports Streamable HTTP OAuth discovery.
• If the connection succeeds but expected content is missing, check the selected workspace and the user's page or database access before changing the authorization method.
• If a workspace-owned MCP token fails, verify the Business or Enterprise plan requirement, token ownership, and bearer-token handling.

Next steps

Deploy the Notion agent template to create a governed agent in Dome that can work with the authorized workspace content, with the template's included model, tools, and rules.