Merge Unified's Notion integration Merge Agent Handler's Notion MCP server

Connect your AI Agents to Notion in minutes

Merge lets you securely connect your agents to Notion and thousands of tools instantly

Start building for free

Read docs

Notion

Learn more about Merge Agent Handler

Available tools

append_block_children

Append child blocks to a page or block. position accepts only type afterblock, start or end. Use search or getblock_children to find a valid parent block or page ID. Text is capped at 2000 UTF-16 units per rich text object (emoji count as 2).

get_block

Retrieve a block by ID

get_block_children

Retrieve children of a block with pagination

update_block

Update a block's content or archive status. Set only the field matching the block's own type, e.g. paragraph {"richtext": [...]}; use getblock to confirm the type.

delete_block

Delete a block

create_comment

Create a comment on a page or block, or reply to an existing thread by passing discussionid from listcomments. Provide exactly one of parent or discussionid. Each richtext item looks like {"type": "text", "text": {"content": "Nice work"}}.

list_comments

List comments for a block or get ALL comments from an entire page

create_database

Create a database under a page. properties defines the initial data source schema; title and description are rich text arrays. Use search for a parent page ID. Returns the database ID and its datasources; pass a data source ID to querydatabase or getdatasource.

query_database

Query the pages in a database or data source, with filtering, sorting and pagination. Pass databaseid (resolved automatically) or datasourceid from getdatabase. filter takes one condition, e.g. {"property": "Status", "select": {"equals": "Active"}}; sorts is an array of objects. Call getdatasource first for the property names and types the filter references.

get_database

Retrieve a database container by ID: title, parent, and the datasources it holds. The property schema is NOT here; pass a data source ID from the returned datasources array to getdatasource to read it. Use search to find database IDs.

get_data_source

Retrieve a data source and its property schema. This is where a database's properties live from API version 2025-09-03. Accepts a datasourceid (from getdatabase's datasources array) or a databaseid, which is resolved for you when the database holds exactly one data source. Call this before building a querydatabase filter or a create_page properties payload.

update_database

Update a database's title, description, icon, cover, or property schema. title and description are rich text arrays. Schema edits route to the data source automatically; read the current schema with getdatasource first. Notion ignores property removal via null, so verify against the returned schema.

create_page

Create a page under an existing page or database; workspace-level pages are not supported. Send properties and children as objects (a valid JSON string is also accepted; malformed JSON is rejected). Use search for a parent ID and getdatasource (not get_database) for the property schema.

get_page

Retrieve a page by ID

get_page_property

Retrieve a specific page property. Paginated types (title, richtext, relation, people) return a list: use pagesize (1-100) and pass the returned nextcursor back as startcursor for the next page. Use get_page to find property IDs.

update_page

Update a page's properties, icon, cover, or archive status, e.g. properties {"Status": {"select": {"name": "Done"}}}. Use getpage for the current values and getdata_source for the property schema.

archive_page

Archive a page (move to trash)

search

Search pages and data sources by title or body content. Returns only objects shared with this integration. Use filter, e.g. {"property": "object", "value": "page"}, to restrict to pages or data sources, and sort to order by lasteditedtime. Data source results carry no url.

list_users

List all users in the workspace

get_user

Retrieve a user by ID

get_bot_user

Retrieve the current integration's bot user

validate_credential

Validate Notion credentials by fetching the bot user. Returns {success, message}.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's Notion MCP server

How can I use the Notion MCP server?

Here are just a few popular use cases:

Knowledge base queries: Your agent can search across your Notion workspace to find relevant information and surface it to users in an app like Slack. For example, it can retrieve company policies, project documentation, or meeting notes when asked

Automated documentation: Your agent can create and update Notion pages based on activities in other systems. For instance, it can automatically generate meeting notes from calendar events or create project pages when new initiatives are started in Jira

Content generation and updates: Your agent can draft content directly in Notion pages and present it for review. For instance, it can generate weekly reports, compile research findings into structured pages, or create onboarding documentation based on conversations in Slack

Onboarding automation: Your agent can personalize onboarding experiences by creating custom Notion pages for new hires. For example, it can generate role-specific onboarding checklists, link to relevant documentation, and set up their personal workspace based on their department and position

What are popular tools for Notion’s MCP server?

Here are some popular tools broken down by data types.

Pages:

<code class="blog_inline-code">get_page</code>
<code class="blog_inline-code">update_page</code>
<code class="blog_inline-code">archive_page</code>
<code class="blog_inline-code">get_page_property</code>

Databases:

<code class="blog_inline-code">create_database</code>
<code class="blog_inline-code">query_database</code>
<code class="blog_inline-code">update_database</code>

Users:

<code class="blog_inline-code">list_users</code>
<code class="blog_inline-code">get_user</code>
<code class="blog_inline-code">get_bot_user</code>

What makes Merge Agent Handler’s Notion MCP server better than alternative Notion MCP servers?

Here are just a few reasons:

Enterprise-grade authentication and credential management: Merge Agent Handler supports dynamic authorization flows, guided user authentication, and both individual and shared authentication modes across connectors, reducing implementation overhead while maintaining control over access

Built-in security and data loss protection (DLP): All tool inputs and outputs are scanned by a security gateway that can block, redact, or mask sensitive data based on default or custom rules you configure

Real-time observability and auditability: Every tool call is logged with a complete audit trail. Logs are fully-searchable, enabling teams to monitor, debug, and audit agent behavior in real time

Evaluation before production deployment: The Evaluation Suite allows you to validate that tools behave as expected before going live, helping improve success rates and reduce unexpected failures in production

Can I set custom security rules for Notion tool calls in Merge Agent Handler?

Yes, you can set a wide range of custom security rules for Notion tool calls in Merge Agent Handler.⁠

⁠For example, you can:

Block credit card numbers in page content. Prevent your agents from adding credit card numbers to Notion pages or database entries

Redact social security numbers. Automatically redact SSNs before they're written to Notion properties or page bodies

Log when agents share email addresses. Track whenever your agents add email addresses to Notion databases or pages for audit purposes

Redact API keys and tokens: Automatically strip API keys, passwords, or authentication tokens before they're added to Notion documentation

Block salary information: Prevent your agents from writing compensation data, revenue figures, or other financial information to Notion

Log access to executive content: Monitor when agents read from or write to Notion pages owned by or mentioning C-level executives

How can I start using Merge Agent Handler’s Notion MCP server?

Here are the steps to get started with Merge Agent Handler's Notion MCP server:

1. Sign up for Agent Handler. Visit Merge Agent Handler's sign up page to create your free account and gain access to the dashboard.

2. Build a Tool Pack. Tool Packs control what connectors and tools are available to your agent. Navigate to the Tool Packs section, select Create Tool Pack, add Notion as a connector, and select either Individual or Shared authentication based on your use case.

3. Add a Registered User. Head to the Registered Users section; this represents an identity (human or system) that executes actions on behalf of your agent. When authentication with Notion is needed, Agent Handler automatically presents a guided flow—eliminating the need for custom OAuth implementation.

4. Validate with the Playground. Test your configuration before deploying to production. Open your Tool Pack's Sandbox environment and try out Notion tool calls such as retrieving pages, adding database records, or modifying workspace content.

5. Connect to your application. Link your agent to Agent Handler using one of two methods:

MCP configuration: Grab the MCP server config from your Tool Pack settings and insert it into your agent's MCP client configuration. Your agent will then have access to all Notion tools via the Model Context Protocol‍

REST API: Call Agent Handler's API directly to enumerate tools and execute them. This requires your API key, Tool Pack ID, and Registered User ID for authentication