Setup Notion

Setup Notion

Purpose

Configure Notion's official hosted MCP for this project, help the user complete browser OAuth, and verify the intended workspace before any content is created.

Current supported path

• Official endpoint: https://mcp.notion.com/mcp
• Transport: remote HTTP
• Authentication: OAuth in the browser
• Project configuration: .mcp.json

Notion's hosted MCP does not currently support file uploads. Do not promise that a local chart or other file can be uploaded through this server. Create the text page first. If the user needs an attachment, they can add it manually or use a separately approved API workflow.

Instructions

1. Inspect before changing configuration

1. Read .mcp.json if it exists.
2. Preserve every existing MCP server.
3. Check whether a Notion server already points to the official endpoint.
4. If Notion tools are already available, skip configuration and verify the connection.
5. Before editing anything, show the user the exact non-secret change and ask for approval.

Never replace the entire MCP configuration merely to add Notion.

2. Add the official server

After approval, add this project-local server entry while preserving the rest of .mcp.json:

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

An equivalent supported Claude Code command is:

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

Do not put tokens or credentials in the configuration.

3. Authenticate

If this session did not load the new server, tell the user to restart Claude Code. Then have the user run /mcp, select Notion, and complete OAuth in the browser.

Before the user authorizes access, remind them to confirm:

• the Notion account;
• the workspace;
• whether that workspace is approved for the intended work; and
• that the connected client can act with the access granted to that user.

Do not claim that OAuth proves the destination or makes every future action safe.

4. Verify with a read

Ask the user for the title of a page they expect in the approved workspace. Use the available Notion search tool to find it without changing anything.

Show the workspace and matching page titles. If the expected page is missing, the workspace is wrong, or the tool call fails, stop and report the exact blocked step. Do not create a page.

5. Report the result

Report only what was verified:

Notion connection
Server: official hosted MCP
Endpoint: https://mcp.notion.com/mcp
Workspace: [verified workspace, if exposed]
Read test: [page title found, or exact blocked step]
Ready for an approved write: [yes or no]

Rules

1. Use only Notion's official hosted endpoint unless the user explicitly requests another server.
2. Preserve existing MCP servers.
3. Stop for approval before editing MCP configuration.
4. Never request or store a Notion API key for this OAuth path.
5. Verify the workspace with a read before any write.
6. Preview the destination and content before any later write.
7. Never claim that hosted Notion MCP can upload files.
8. If access is wrong, disconnect or revoke it rather than continuing with a nearby workspace.