1

Notion Context

github-actions[bot] edited this page 2026-06-16 04:00:53 +00:00

Table of Contents

• Notion Context Source
• What it is
• Setup
• Configure via REST
• MCP tools (6)
• Input parameters
• Scopes
• Endpoints
• Use cases
• Related

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

🌍 View in other languages

Notion Context Source

Source of truth: src/lib/notion/api.ts (REST client), src/lib/db/notion.ts (token persistence), open-sse/mcp-server/tools/notionTools.ts (6 MCP tools), src/app/api/settings/notion/route.ts (settings API). Tool registration and scope wiring lives in open-sse/mcp-server/server.ts.

What it is

OmniRoute can connect to a Notion workspace as a context source — a read/write knowledge base that agents reach through the built-in MCP server. Once a Notion integration token is configured, the MCP tools let an LLM search pages and databases, read page content and block trees, query databases with filters/sorts, and append new blocks — all proxied through OmniRoute (with retry, timeout, and error classification) so the model never touches the Notion API directly.

The integration is a thin, hardened wrapper over the official Notion REST API (https://api.notion.com/v1, Notion-Version: 2026-03-11). The client (src/lib/notion/api.ts) adds:

• Retry with exponential backoff (up to 3 attempts) for 429 and 5xx.
• 55-second request timeout via AbortController.
• Typed error classification — NotionAuthError (401/403), NotionNotFoundError (404), NotionRateLimitError (429, honors retry after hints), NotionValidationError (400/409), NotionServerError (5xx), NotionTimeoutError.
• Message sanitization that strips stack-trace-like fragments before surfacing.

Setup

There is no environment variable for the Notion token — it is stored in the SQLite key_value table (namespace notion, key integration_token) via src/lib/db/notion.ts. Configure it from the Context Sources tab of the Endpoint dashboard (ObsidianSourceCard's sibling NotionSourceCard), or via the settings REST API.

Note

The token is a Notion internal integration token. Create an integration at https://www.notion.com/my-integrations, then share the pages/databases you want OmniRoute to access with that integration (Notion's permission model is share-based, not workspace-wide).

Configure via REST

# Save + validate the integration token (POST validates by issuing a test search)
curl -X POST http://localhost:20128/api/settings/notion \
  -H "Content-Type: application/json" \
  -d '{"token":"ntn_xxx"}'

# Check connection status
curl http://localhost:20128/api/settings/notion

# Disconnect (clears the stored token)
curl -X DELETE http://localhost:20128/api/settings/notion

All three methods require dashboard authentication (isAuthenticated). On POST, OmniRoute saves the token and immediately runs a 1-result test search; if Notion returns an error object the token is cleared and the call fails with 400.

MCP tools (6)

Defined in open-sse/mcp-server/tools/notionTools.ts. The token is resolved at call time via getNotionToken(); if none is configured the tool throws "Notion integration token not configured. Set it in Settings > Context Sources."

Tool	Scope	Description
notion_search	read:notion	Search pages and databases by text query (returns titles, IDs, URLs). Paginated.
notion_get_page	read:notion	Get content and metadata of a page by its ID.
notion_list_block_children	read:notion	List all block children of a block or page (the block tree). Paginated.
notion_query_database	read:notion	Query a database with optional filter + sorts (Notion API format). Paginated.
notion_get_database	read:notion	Get the schema/metadata of a database by ID.
notion_append_blocks	write:notion	Append block children to an existing block or page (max 100 blocks per request).

Input parameters

• notion_search — query (1–500 chars), pageSize (1–100, default 20), startCursor (optional).
• notion_get_page — pageId (32-char hex or UUID).
• notion_list_block_children — blockId, pageSize (1–100, default 50), startCursor (optional).
• notion_query_database — databaseId, filter (optional, Notion filter format), sorts (optional array), pageSize (1–100, default 50), startCursor (optional).
• notion_get_database — databaseId.
• notion_append_blocks — blockId, children (array of block objects), after (optional position).

Scopes

The read tools require read:notion and the write tool requires write:notion. Scopes are enforced by withScopeEnforcement() in open-sse/mcp-server/server.ts only when OMNIROUTE_MCP_ENFORCE_SCOPES=true; the caller's allowed scopes come from OMNIROUTE_MCP_SCOPES (comma-separated) or the authenticated API key's scope context. See MCP-SERVER.md for the full scope model.

Endpoints

Method	Path	Purpose
GET	/api/settings/notion	Return { connected, hasToken }.
POST	/api/settings/notion	Save + validate the integration token.
DELETE	/api/settings/notion	Disconnect (clear the stored token).

These are dashboard settings routes. There is no public /v1 Notion proxy endpoint — Notion is reached exclusively through the MCP tools above.

Use cases

• Knowledge-grounded answers — let an agent notion_search the workspace and notion_get_page the top hit before answering, so responses cite real internal docs.
• Database-backed workflows — notion_query_database a tasks/CRM database with filters + sorts, then summarize or triage the rows.
• Write-back / logging — notion_append_blocks to append meeting notes, run summaries, or agent output into an existing page (append-only; no destructive edits).
• Structure exploration — notion_list_block_children to walk a page's block tree, or notion_get_database to discover a database's property schema before querying it.

Related

• MCP Server — transports, scope enforcement, full tool inventory.
• Obsidian Context Source — the other built-in context source.
• Memory System — persistent conversational memory (complementary context layer, injected automatically rather than tool-fetched).

🏠 Home

🌍 Languages (40+)

---

🚀 Getting Started

• Setup Guide
• User Guide
• Features
• Quick Start (Docker)
• Electron Desktop App
• Termux (Android)
• PWA Guide

🌐 Providers

• Provider Reference
• All Providers
• Free Tiers
• Kiro Setup

🎯 Routing & Combos

• Auto-Combo
• Reasoning Replay

🗜️ Compression

• Compression Guide
• Compression Engines
• RTK Compression
• Language Packs
• Rules Format

🔌 Integrations

• MCP Server
• A2A Server
• Agent Protocols
• OpenCode Plugin
• Webhooks
• Cloud Agents
• Skills
• Memory
• Evals
• Gamification

🏗️ Architecture

• Architecture Overview
• Codebase Documentation
• Repository Map
• Authorization Guide
• Resilience Guide

🔒 Security

• Guardrails
• Compliance
• Error Sanitization
• Public Credentials
• Route Guard Tiers
• Stealth Guide
• CLI Token Auth

📋 Reference

• API Reference
• CLI Tools
• Environment Variables

🚀 Operations

• VM Deployment
• Fly.io Deployment
• Tunnels Guide
• Proxy Guide
• SQLite Runtime
• Coverage Plan
• Release Checklist

ℹ️ More

• Troubleshooting
• i18n / Translations
• Uninstall
• Contributing
• Comparison vs Alternatives

OmniRoute · Website · npm · Docker Hub