Setting up the Notion MCP Server

The Notion MCP Server can be connected in two ways: as a Notion-hosted remote service with OAuth sign-in, or as a locally run self-hosted server with an integration token. Notion now recommends the hosted option.

Which option fits

The hosted option is the quickest to set up, needs no local process, and handles access through an OAuth dialog. The self-hosting option makes sense when traffic should not leave your own network or when an existing internal integration should be reused. Per the project README, the self-hosting repository is only maintained as a lower priority.

Connecting the hosted option

Register the remote server in your MCP client. In Claude Code:

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

In Cursor or VS Code, create a server entry with the URL https://mcp.notion.com/mcp instead (in VS Code with "type": "http"). On the first call the client opens a browser window for OAuth authorization — select the workspace there and confirm. If the primary path fails, https://mcp.notion.com/sse is available as a fallback.

Connecting the self-hosting option

Create an internal integration at notion.so/profile/integrations and copy its token. Then, in the integration's Access tab, grant exactly the pages and databases the agent should see — or choose "Connect to integration" from the three-dot menu on the target page. Start the server via npx with NOTION_TOKEN set as an environment variable, or use the Docker image mcp/notion.

Keeping access tight

The agent can read and change anything reachable within the chosen OAuth scope or via the connected integration. For automated workflows, use a dedicated integration with as few granted pages as possible and treat the token like a password. Workspace owners can view and remove connected MCP clients in Notion settings under "Connections".

Verifying the setup

After connecting, test with a harmless task such as "Find the page with the onboarding notes and summarize it." Check that only the expected pages appear, and tighten the granted scope if needed.

Common connection issues

If the OAuth login doesn't open in the browser, check whether the client is blocking pop-ups or new windows — some terminal environments without a graphical interface can't launch a browser at all and instead need a manual sign-in via a displayed URL. With the self-hosting option, an expired or revoked integration token causes authentication errors; a fresh token from the account settings usually fixes this immediately.

For teams with multiple workspaces

Anyone using several Notion workspaces in parallel, for example one for their own company and one for a client project, should register the server under different names in the client configuration and explicitly select the correct workspace during each OAuth sign-in. This helps prevent an agent from accidentally making changes in the wrong workspace.

Source: developers.notion.com/docs/mcp and developers.notion.com/docs/get-started-with-mcp, plus github.com/makenotion/notion-mcp-server, checked on 2026-09-05.