Notion MCP Claude Code: what to check before you trust the connection

On this page#

• What the integration actually does
• The wiring
• The two things that break it
• Verifying it works
• Team considerations
• FAQ

What the integration actually does#

A Notion MCP connection gives Claude Code a controlled route to discover and call Notion capabilities. It does not “put Notion inside the model,” grant universal workspace access, or make generated content trustworthy. The connection is plumbing; authorization, tool selection, and result verification remain separate concerns.

MCP is a protocol through which an AI application can connect to an external server that exposes tools, resources, or prompts. In this setup:

| Component | Actual responsibility | |---|---| | Claude Code | Acts as the MCP client and decides when to request a tool call | | Notion MCP server | Advertises supported operations and handles requests | | Notion authorization | Determines which workspace content is reachable | | The model | Chooses arguments and interprets returned content | | You | Define acceptable access, mutations, and verification |

The common mental model is wrong: connecting Notion does not create a synchronized local copy, and MCP is not a database driver embedded in your repository. The server remains a boundary between the coding agent and Notion.

That distinction matters because a successful connection proves only that the client and server can communicate. It does not prove that Claude Code can find the right page, access the intended teamspace, preserve document structure, or safely perform writes.

The MCP architecture documentation describes this client-server separation. Treat it as a trust boundary, not a convenience abstraction.

Photo by cottonbro studio on Pexels.

The wiring#

The clean setup is a project-visible server definition with per-developer authentication. Put the transport configuration where the repository can declare it, but keep authorization outside version control. A teammate should inherit the server definition without inheriting your Notion identity.

1. Add the server from Claude Code#

Register the remote HTTP server:

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

Then open Claude Code and run:

/mcp

Select the notion server and complete the authorization flow. The browser step is not optional ceremony: it establishes the identity whose Notion permissions constrain everything the server can return.

Claude Code is the MCP client here. Its official documentation is available through the Claude Code docs, while the broader product model is covered in Anthropic’s Claude Code overview.

2. Make the server definition reproducible#

For a repository-level setup, use a .mcp.json definition:

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

This file describes where the server is and how Claude Code reaches it. It must not contain OAuth tokens, browser cookies, exported session state, or another developer’s credentials.

Commit the definition only after reviewing the repository’s trust model. Project-scoped MCP configuration is executable agent infrastructure: opening the repository may invite a developer to approve an external server connection.

If you are standardizing more than this single connection, PairFoundry’s Agent Operating Kit provides a stronger place for shared operating rules, acceptance checks, and handoff conventions than an unexplained configuration file.

3. Give the authenticated identity deliberate access#

Authorize with an identity that can reach the pages required for the workflow—and no more. “Use my normal account because it already sees everything” is the wrong default for a team rollout.

Start with a narrow surface:

• One known page for read verification.
• One disposable page for write verification, if writes are required.
• One restricted page that must remain inaccessible.
• No sensitive teamspace included merely for convenience.

Do not ask Claude Code to “find the relevant project docs” as the first test. That mixes connection health, search behavior, permissions, naming, and model judgment into one ambiguous result.

For broader agent setup patterns, use the Wiring It In hub rather than treating each MCP server as an isolated configuration trick.

The two things that break it#

Most failed setups fall into two categories: the transport is not authenticated, or authentication works but the identity cannot access the expected content. These failures can look similar in chat, so diagnose the connection layer before changing prompts, page titles, or repository instructions.

Error 1: 401 Unauthorized or an authorization loop#

A 401 Unauthorized response means the server did not accept the current authorization state. Repeated browser prompts, a connection that closes after login, or /mcp showing that the server still needs authentication belong to the same failure class.

Fix it in this order:

1. Confirm that the configured URL is exactly:

   https://mcp.notion.com/mcp

2. Run /mcp in Claude Code and reconnect the notion server.

3. Complete the browser flow using the intended Notion identity.

4. Return to the same Claude Code session and inspect /mcp again.

5. If the wrong server entry was registered, remove that entry and add the correct definition again.

Do not paste a token into .mcp.json to bypass the flow. That converts a local authentication problem into a repository secret and a team incident.

The official MCP specification explains the protocol boundary, but a healthy protocol session still depends on valid authorization at the connected service.

Error 2: connected, but the page is missing or the result is empty#

When /mcp reports a connected server but a known page cannot be retrieved, stop debugging transport. The likely fault is the authenticated identity’s Notion access, the requested object, or the assumption that search visibility equals workspace visibility.

Fix it mechanically:

1. Open the exact target page in Notion as the same authenticated user.
2. Confirm that the page is available to that identity.
3. Retry using a precise page name or direct reference instead of a broad semantic request.
4. Test a second known-accessible page.
5. Test a known-restricted page and confirm that it remains unavailable.

Do not broaden workspace access until the query “starts working.” That hides the original boundary failure and leaves the agent over-permissioned.

Teams still building their first acceptance checks should use PairFoundry’s free Foundations tutorials before turning MCP access into a default development dependency.

Photo by Daniil Komov on Pexels.

Verifying it works#

A real verification proves transport, identity, read accuracy, mutation behavior, and denial boundaries independently. “Claude summarized a page” is insufficient because a plausible answer can come from partial content, stale conversational context, or the wrong page with a similar title.

Use this acceptance sequence:

1. Connection check: /mcp shows the intended notion server as connected.
2. Identity check: name the Notion account used during authorization.
3. Exact read: request a known page containing a unique sentinel phrase.
4. Structure check: confirm the returned title, relevant section, and sentinel phrase.
5. Denied read: request a page the identity must not access.
6. Controlled write: if writes are required, change one disposable block with explicit replacement text.
7. Visual confirmation: open Notion and inspect the exact mutation.
8. Fresh-session check: restart the agent session and repeat the exact read.

The denial test is essential. If the restricted page is returned, the integration is not “working better”; its permission boundary is wrong.

Also separate read acceptance from write acceptance. A team may approve retrieval for documentation while prohibiting page creation, edits, comments, or bulk changes. Those are different operational capabilities even when one server exposes them.

The MCP architecture model is useful here: verify each boundary separately instead of judging the whole chain from one model response.

Team considerations#

The second developer will not inherit your authorization, your Notion permissions, or your understanding of the intended workflow. A team-ready integration therefore needs a committed server definition, a documented login step, explicit allowed actions, and acceptance tests that another engineer can repeat without asking who configured it.

Put these items beside the repository’s agent instructions:

• Why Notion access exists.
• Which pages or teamspaces are in scope.
• Whether writes are prohibited, conditional, or expected.
• The exact read, denial, and optional write checks.
• How to disconnect the server.
• Who owns failures in the Notion boundary.
• Which repository tasks must still work without Notion.

Never make Notion MCP the only source of build-critical facts. If the agent needs a schema, invariant, release procedure, or security constraint to change code safely, keep that information in the repository or another versioned system. Remote documentation access is useful context, not a replacement for reviewable project state.

Review the broader PairFoundry pack catalog if the connection is part of a larger team rollout involving agent instructions, repeatable workflows, and repository-level guardrails.

Photo by panumas nikhomkhai on Pexels.

Related reading#

• Claude Code VS Code, including the failure mode nobody documents
• Claude Code marketplace: the wiring, and the two things that break it

FAQ#

Should Claude Code have access to my entire Notion workspace?#

No. Start with the smallest set of pages that supports the repository workflow, plus one disposable write target if mutations are required. Workspace-wide access makes verification harder and increases the impact of a mistaken tool call. Broad access is not a prerequisite for a useful connection.

How is this different from pasting Notion content into Claude Code?#

Pasting creates a static snapshot inside one conversation. MCP lets the client request current resources or operations through a defined server boundary. That is more convenient, but it also introduces authorization, availability, tool-selection, and mutation risks that pasted text does not have.

What should be committed so another developer can use the setup?#

Commit the project-scoped server definition and the acceptance procedure. Do not commit tokens or session state. Each developer should authorize separately, verify a known readable page, confirm a restricted page remains unavailable, and understand whether the repository permits Notion writes.

How do I roll back when the connection causes problems?#

Disconnect or remove the notion MCP server from Claude Code, then continue with repository-local sources. Revoke or review the related Notion authorization if access should end completely. A sound workflow must degrade cleanly; MCP availability should not be required to build, test, or recover the repository.

When should a team not use Notion MCP?#

Do not use it when required facts must be versioned with code, when the permitted access surface cannot be narrowed, or when the team cannot define a repeatable denial test. If nobody owns authorization and mutation policy, adding the connection creates ambiguity rather than useful automation.