How to connect to the Notion MCP with Claude Code (5 steps)

With Merge Agent Handler's Notion MCP server connected to Claude Code, your agents can search pages, create and update content, and manage databases directly from the terminal.                                                                                                              

This guide walks through connecting Claude Code to Notion via Merge Agent Handler in five steps.                                                                                                                   

Prerequisites 

• Merge Agent Handler account
• Claude Code installed and configured
• Notion account with appropriate workspace permissions

Related: A guide to connecting to the Figma MCP with Claude Code

 How it works

Merge Agent Handler acts as a secure bridge between your agent and Notion's API. You'll configure a Tool Pack (a scoped collection of connectors) and a Registered User (your agent's identity), which together generate a unique MCP URL that Claude Code uses over HTTP.

This URL, coupled with an API key you’d generate in Agent Handler, lets you access the server with the following command:

 {
 "mcpServers": {
   "agent-handler": {
     "command": "npx",
     "args": [
       "-y",
       "mcp-remote@latest",
       "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
       "--header",
       "Authorization: Bearer ${AUTH_TOKEN}"
     ],
     "env": {
       "AUTH_TOKEN": "yMt*****"
     }
   }
 }
}

Steps for connecting to the Notion MCP via Claude Code

Take the following actions to get your MCP URL, API key, and connect to the server.

1. Create a Tool Pack

Log into the Merge Agent Handler dashboard, navigate to Tool Packs, and click Create Tool Pack. Give it a name like "Knowledge Agent," add a description. 

Then select Notion as your connector and pick the specific tools you want enabled (all tools are selected by default).  

2. Add a Registered User

Go to Registered Users and click Add Registered User. This creates the identity context for your agent's operations and generates the unique MCP URL Claude Code will use. 

3. Authenticate Notion

From the Registered User detail page, click Add Connector and complete the Notion OAuth flow. 

This grants your agent access to the pages and databases you specify.

4. Gather your credentials 

You'll need two things from Merge Agent Handler:     

• MCP URL (from the Tool Pack detail page): 

https://ah-api.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp

• API key (from Settings > API Keys > Create new key)

5. Add Notion MCP to Claude Code

Run the following command in your terminal, replacing the placeholders with your actual values:

 {
 "mcpServers": {
   "agent-handler": {
     "command": "npx",
     "args": [
       "-y",
       "mcp-remote@latest",
       "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
       "--header",
       "Authorization: Bearer ${AUTH_TOKEN}"
     ],
     "env": {
       "AUTH_TOKEN": "yMt*****"
     }
   }
 }
}

Verify the connection by running: <code class="blog_inline-code">claude mcp list</code>

You should see agent-handler listed with a connected status.

Once connected, you can prompt Claude Code to take action in Notion. For example: "Search the engineering wiki for any existing documentation on our authentication service before I start writing the new spec."

Or you can ask Claude Code for information in Notion: "What’s the top priority for our product roadmap next quarter?”

{{this-blog-only-cta}}

Notion MCP FAQ 

In case you have more questions on setting up and using the Notion MCP in Claude Code, we’ve addressed several more commonly-asked questions below.

What can agents do with a Notion MCP server? 

• Auto-provision access: When a new hire row is added in Notion, create accounts/groups in Okta/Google Workspace/GitHub and write back status and links

• Create/triage tickets from Notion requests: Turn a Notion form submission into a Linear/Jira issue with the right project, labels, and assignees

• Keep systems in sync: When a project status changes in Notion, update the matching record in Salesforce/HubSpot and flag mismatches

• Run operational playbooks: Press a “Launch” button in Notion to trigger a checklist that creates release artifacts, pings endpoints, and records outcomes

• Monitor and escalate: Pull metrics/incidents from tools like Datadog/Sentry via MCP, post a summary into Notion, and open follow-ups when thresholds are hit  

Why use Merge Agent Handler's Notion MCP server?

Merge Agent Handler's Notion connector includes enterprise-grade security controls, data loss prevention, and real-time observability over every tool call. 

You can scope exactly which pages and databases your agent can access, and set custom guardrails to make sure agents only read or write what they're supposed to.

Why connect Notion MCP to Claude Code? 

Developers constantly reference Notion docs while writing code, whether it’s architecture decisions, API specs, onboarding guides, etc. 

By connecting the Notion MCP to Claude Code, your agents can pull that context directly into the terminal for your engineers, enabling them to spend less time hunting through wikis and more time building.