notion-page-link-syntax

name	notion-page-link-syntax
description	Fix Notion MCP URL validation errors when updating page content with links. Use when: (1) "Invalid agent URL - Failed to parse as URL" error with {{URL}} syntax, (2) need to link to existing page without moving it, (3) replacing plain text with page references. Covers difference between <page> vs <mention-page> tags and read vs write URL formats.
author	Claude Code
user-invocable	false

Notion Page Link Syntax for MCP Updates

Problem

When using the Notion MCP update-page tool to insert page links, the URL format shown in fetched content doesn't work for writes, causing validation errors.

Context / Trigger Conditions

• Error: "Invalid agent URL - Failed to parse as URL: {{https://www.notion.so/...}}"
• Using notion-update-page with replace_content_range or insert_content_after
• Trying to replace plain text with a link to another Notion page
• Content fetched from Notion shows URLs wrapped in {{...}}

Solution

1. URL Format Differs Between Read and Write

When reading/fetching - URLs appear wrapped:

<page url="{{https://www.notion.so/abc123}}">Page Title</page>

When writing/updating - Use plain URLs without braces:

<page url="https://www.notion.so/abc123">Page Title</page>

2. Choose the Right Tag for Your Intent

<page> - Creates a child page or MOVES an existing page:

<page url="https://www.notion.so/abc123">Page Title</page>

WARNING: Using <page> with an existing URL will MOVE that page to become a child of the current page.

<mention-page> - Creates an inline mention/link without moving:

<mention-page url="https://www.notion.so/abc123">Page Title</mention-page>

Use this when you just want to reference/link to a page.

3. Practical Example

To replace plain text "Cooking" with a link to an existing page:

Wrong (causes validation error):

{
  "new_str": "<page url=\"{{https://www.notion.so/abc123}}\">Cooking</page>"
}

Wrong (moves the page instead of linking):

{
  "new_str": "<page url=\"https://www.notion.so/abc123\">Cooking</page>"
}

Correct (creates a link without moving):

{
  "new_str": "<mention-page url=\"https://www.notion.so/abc123\">Cooking</mention-page>"
}

Verification

• No validation error on the API call
• Fetch the updated page to confirm the link appears correctly
• Verify the linked page wasn't moved (check its parent is unchanged)

Notes

• The <mention-page> inner text (page title) is optional; Notion displays the actual title
• Self-closing format also works: <mention-page url="https://www.notion.so/abc123"/>
• Same principle applies to <mention-database> and <mention-user> tags
• Always fetch pages before editing to understand their current structure