How to connect to the Notion MCP with Claude Code (4 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.                                                                                                                   

How it works

Merge Agent Handler acts as the layer between Claude Code and Notion's API. You install the Merge CLI, authenticate once, and register the connection with a single command. Agent Handler manages your Notion OAuth credentials and routes every API call so you don't store tokens locally or handle credential state yourself.

Here's the command that registers the connection:

merge setup claude-code

Related: A guide to connecting to a Notion MCP with Codex

Prerequisites

Before getting started, you'll need the following:

• A Merge Agent Handler account
• Claude Code installed (run claude --version to confirm)
• pipx installed (run pipx --version to confirm, or install via pip install pipx)
• A Notion account with appropriate workspace permissions

If you want to connect Merge Agent Handler's Notion MCP with internal or customer-facing agentic products, you can follow the steps in our docs.

1. Install the Merge CLI

Install with pipx: pipx install merge-api

Verify your installation: merge --version

2. Configure the CLI and log in

Authenticate the CLI with your Merge Agent Handler account: merge login

Once complete, the CLI can make authorized API requests on your behalf.

3. Add Agent Handler to Claude Code

To add Agent Handler to Claude Code, run:

merge setup claude-code

Or register manually with:

claude mcp add 
--transport http agent-handler https://ah-api.merge.dev/mcp

Verify the connection registered. Open Claude Code and run: /mcp

agent-handler should appear under Local MCPs with a connected status.

Related: The steps for integrating a Notion MCP with Cursor

4. Authenticate Notion

Select agent-handler from the MCP list. This opens a browser window where you select which integrations to authenticate. Choose Notion and complete the OAuth flow, granting your agent access to the pages and databases you specify.

The first time you use a Notion tool in a Claude Code session, a Magic Link may appear to complete connector authentication. Once authenticated, Merge stores and manages the token. You won't need to re-authenticate unless you revoke access.

You can now 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.