mcp-notion Skill
Notion workspace operations via the official Notion MCP (@notionhq/notion-mcp-server, 24 tools) over Code Mode, plus direct Notion API calls for the five capabilities the MCP does not expose. It knows Notion's data model at the schema layer — data sources, 22 property types, relations, rollups, Formulas 2.0 — so an agent can create, query, and extend a workspace without guessing.
1. MARKDOWN + DATA-SOURCE CONTRACT: READ BEFORE ANY NOTION WRITE
Two shape rules cause most Notion write failures:
- Page bodies vs page properties are different surfaces. A page's content is a tree of blocks (append/update via block tools, or the markdown round-trip tools). A page's metadata is properties typed by its parent data source's schema. Writing prose into a property, or a property value into a block, fails or silently truncates.
- API 2.0 replaced "databases" with "data sources" (API version
2025-09-03). A database is now a container of one or more data sources; queries, schema, relations, and rollups all target a data source id, not a database id. Using a database id where a data-source id is required is the most common 400.
Markdown round-trip tools (retrieve-page-markdown / update-page-markdown) require API version 2026-03-11 and are the token-efficient path for AI. Full detail: references/database-model.md and references/mcp-tools.md.
Failure symptom: a validation_error naming data_source_id, or property writes that vanish, means a database id was used where a data-source id was required, or content was routed to the wrong surface.
2. WHEN TO USE
Activation Triggers (explicit user phrases)
- "notion", "notion mcp", "notion api", "mcp-notion"
- "notion page", "notion database", "notion data source", "query notion"
- "create a notion page", "add a row", "notion property", "notion relation", "notion rollup", "notion formula"
- "notion token", "notion integration", "ntn_", "notion search"
- "upload a file to notion", "notion view", "notion async task"
Automatic Triggers (keyword patterns)
notion + any action verb (create, read, update, query, search, append, archive)
- "data source" / "property" / "rollup" / "relation" in a Notion context
- MCP tool names:
create-a-page, query-data-source, retrieve-a-page (namespaced notion.notion_<name>)
When NOT to Use
- Community Notion MCP servers (suekou/mcp-notion-server, awkoy/notion-mcp-server) — this mode uses the official
@notionhq/notion-mcp-server only.
- Notion→Obsidian migration mechanics (running the importer itself) — the importer runs inside the Obsidian desktop app, not here; this mode is the read-side inventory enabler (
references/migration-inventory.md), not the importer.
- Generic markdown authoring with no Notion workspace — use
@markdown / sk-doc.
- Non-Notion knowledge apps (Obsidian, ClickUp docs) — wrong surface (
mcp-obsidian, mcp-click-up).
3. SMART ROUTING
The mcp-tooling hub routes a Notion request here when the prompt names Notion or one of its surfaces (a page, a database or data source, a property, a relation, a token) and the hub's mcp-notion signal selects this packet.
The router makes two decisions: the official 24-tool MCP carries page, block, data-source, comment, user and search work while direct Notion API calls fill the five gaps, and the backend is the headless local stdio server, with the remote OAuth server only for an interactive session.
references/mcp-tools.md is the default reference and the fallback suggestion, references/database-model.md and references/property-types.md load for schema intent, references/api-gap-tools.md for a gap, references/troubleshooting.md for install or an error, and references/migration-inventory.md for a migration inventory.
A request that scores no intent returns UNKNOWN_FALLBACK with its disambiguation checklist, never a silent default.
Read ROUTER.md before selecting skill-local resources; open only the matched files.
4. HOW IT WORKS
Backend Comparison
| Dimension |
Local stdio (default, headless) |
Remote MCP (interactive) |
| Transport |
stdio via npx -y @notionhq/notion-mcp-server |
Streamable HTTP at https://mcp.notion.com/mcp |
| Auth |
NOTION_TOKEN (ntn_… internal-integration token) |
OAuth (browser) |
| Headless? |
Yes — the only Code-Mode-capable backend |
No — interactive only |
| Tool names |
create-a-page, retrieve-a-page, … |
notion-create-pages, … + async tasks |
| Status |
Deprecated by Notion, still functional |
Recommended by Notion |
| Used by |
Code Mode / automation |
Human-in-the-loop clients |
Deprecation note. Notion is deprecating the open-source local server in favor of the remote OAuth server. Code Mode is headless, so the local stdio server is the correct (and only) choice here today; references/troubleshooting.md carries the local→remote migration path for when the operator moves to an interactive workflow.
Official Notion MCP — via Code Mode (default path)
The registered notion manual launches @notionhq/notion-mcp-server over stdio with npx -y. It talks to Notion's REST API with the integration's NOTION_TOKEN.
Prerequisites:
- Code Mode MCP configured, with the
notion manual in .utcp_config.json (already registered — see INSTALL-GUIDE).
notion_NOTION_TOKEN (an ntn_… internal-integration token) available to Code Mode, and the integration granted content access to the target pages/data sources.
Configuration (.utcp_config.json, manual_call_templates) — already applied:
{
"name": "notion",
"call_template_type": "mcp",
"config": {
"mcpServers": {
"notion": {
"transport": "stdio",
"command": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": { "NOTION_TOKEN": "${notion_NOTION_TOKEN}" }
}
}
}
}
The notion_ env prefix matches the manual name notion, so ${notion_NOTION_TOKEN} resolves. This mode documents that registration; it does not rewrite config files.
Tools: the server exposes 24 notion_* tools across 6 domains — pages (7), blocks (5), data sources (6), comments (2), users (3), search (1). Confirm every name with tool_info() / list_tools() before calling; the full catalog with per-tool inputs is in references/mcp-tools.md.
Invocation via Code Mode (call_tool_chain takes a single code string):
// Code Mode namespaces each tool as notion.notion_<tool_name>. Notion tool names are
// HYPHENATED (create-a-page, retrieve-a-page), so notion.notion_retrieve-a-page is invalid
// JS (it parses as subtraction) — use hyphen-safe BRACKET access. VERIFY once the manual is
// registered: run list_tools() to read the exact callable; Code Mode MAY instead sanitize
// hyphens to underscores (notion.notion_retrieve_a_page). Bracket form is the safe default.
const result = await call_tool_chain({
code: `
const hit = await notion["notion_search"]({ query: "Roadmap" });
const page = await notion["notion_retrieve-a-page"]({ page_id: hit.results[0].id });
return page;
`,
});
The Five API Gaps (direct API)
File uploads, views, non-truncated page property items, and async-task polling exist in the Notion REST API but not in the MCP tool surface; daily notes are a convention with no endpoint. Fill them with direct calls (Authorization: Bearer $notion_NOTION_TOKEN, Notion-Version: 2025-09-03, or 2026-03-11 for markdown/async). Recipes: references/api-gap-tools.md.
When to prefer the remote MCP: interactive sessions where OAuth is available and async-task tools are needed. Otherwise stay on the local stdio backend.
Limitations: search is title-only (no full-text content search); pages archive rather than hard-delete; the workspace is cloud-only (no headless filesystem); rate limit ≈ 3 req/s per integration with Retry-After.
5. RULES
✅ ALWAYS
- Resolve the backend before acting — Code Mode uses the local stdio backend with
NOTION_TOKEN; only route to the remote OAuth backend when an interactive session is genuinely available. Probe, do not assume.
- Target a data-source id, not a database id — API 2.0 made data sources the primary abstraction; queries, schema, relations, and rollups all take a
data_source_id.
- Route content to the right surface — page prose → blocks (or markdown round-trip tools); metadata → typed properties. Never cross them.
- Confirm MCP tool names with
list_tools() / tool_info() before calling — Notion tool names are hyphenated (create-a-page), so the hyphen-safe callable is bracket-access notion["notion_create-a-page"] unless list_tools() shows Code Mode sanitized them to underscores.
- Read a data source's schema before writing rows — property types and select options are schema-defined; writing an undefined option or wrong-typed value fails.
- Handle the rate limit — ≈3 req/s per integration; on
429 back off with jitter and honor Retry-After. Batch reads where possible.
- Pin the API version per operation —
2025-09-03 for most tools, 2026-03-11 for markdown round-trip and async tasks.
- Preview destructive ops — confirm the exact page/row before archive; Notion archives (recoverable) rather than hard-deletes, but bulk archives are still disruptive.
⛔ NEVER
- Never hardcode the token — read it from
notion_NOTION_TOKEN in the Code Mode environment; never inline ntn_… in a command, note, or example.
- Never use a community Notion MCP server as the default — this mode is the official
@notionhq/notion-mcp-server.
- Never assume the remote OAuth backend works headless — it cannot; Code Mode must use the local stdio backend.
- Never auto-modify
.utcp_config.json, .env.example, opencode.json, or hub files — the notion manual is already registered there; if it needs changing, print the config for the user and never write these files programmatically.
- Never fabricate pages, rows, or property values — if a query returns empty, the data source is genuinely empty or the integration lacks access. Report it.
- Never treat search as full-text —
search matches titles only; to find by content, retrieve candidate pages and inspect client-side.
- Never write markdown into a property field — prose belongs in blocks or the markdown round-trip; properties are typed values.
⚠️ ESCALATE IF
- No
NOTION_TOKEN and no OAuth session → direct the user to INSTALL-GUIDE.md (create an internal integration, copy the ntn_… token to .env, grant content access).
- A
401/403 → the token is missing/wrong, or the integration was not granted access to the target page/data source.
- A
validation_error naming data_source_id → a database id was used where a data-source id is required (2.0 migration); resolve the data source first.
- Persistent
429 → the integration is over ≈3 req/s; reduce concurrency, add backoff, or batch.
- The operator wants an interactive/OAuth workflow → follow the local→remote migration path in
references/troubleshooting.md.
6. SUCCESS CRITERIA
7. INTEGRATION POINTS
Gate 2 (Skill Routing): activates at ≥0.8 confidence for Notion workspace requests. The advisor matches on notion, notion mcp, notion database, notion data source, notion page, notion token.
Code Mode MCP: the official Notion MCP tools are invoked via mcp__code_mode__call_tool_chain; Code Mode namespaces each as notion.notion_<tool_name> — use hyphen-safe bracket access since Notion names are hyphenated. See references/mcp-tools.md.
Migration: this mode is the read-side inventory enabler for Notion→Obsidian migration (references/migration-inventory.md) — the same knowledge layer that operates a live workspace reads its structure to drive an Obsidian import; the write-side reconstruction method lives in mcp-obsidian's references/notion-migration.md.
Memory: save Notion workflow context (target data-source ids, integration name, backend) with /speckit:save when switching sessions.
Tool Usage: Bash for direct API calls and scripts/; mcp__code_mode__call_tool_chain for MCP operations; Read to load references on demand.
8. QUICK REFERENCE
Notion MCP tool surface (24 tools, 6 domains — confirm names with tool_info())
| Domain |
Count |
Representative tools |
| Pages |
7 |
create, retrieve, update, archive; markdown retrieve/update |
| Blocks |
5 |
retrieve, children, append, update, delete |
| Data sources |
6 |
query, retrieve, update, create, templates |
| Comments |
2 |
create, list |
| Users |
3 |
list, retrieve, bot |
| Search |
1 |
title search |
The 5 gaps → direct API (references/api-gap-tools.md)
| Gap |
Endpoint family |
| File uploads |
POST /v1/file_uploads (+ send / complete) |
| Views |
data-source view endpoints |
| Page property items |
GET /v1/pages/{id}/properties/{prop} |
| Async tasks |
task-status endpoint (native on remote MCP) |
| Daily notes |
convention (no endpoint) |
Code Mode call pattern
// 24 tools, namespaced notion.notion_<tool_name>; hyphenated names → bracket access.
// Confirm the exact callable with list_tools() before relying on either form.
await call_tool_chain({
code: `
const ds = await notion["notion_query-data-source"]({
data_source_id: "DATA_SOURCE_ID",
filter: { property: "Status", status: { equals: "In progress" } },
});
return ds.results.map(p => p.id);
`,
});
9. REFERENCES AND RELATED RESOURCES
Reference Files (load on demand via router):
references/mcp-tools.md — the 24-tool catalog by domain + Code Mode invocation
references/api-gap-tools.md — direct Notion API for the 5 uncovered capabilities
references/property-types.md — 22 property types: schema, value, filter/sort
references/database-model.md — data-source hierarchy, relations, rollups, Formulas 2.0
references/troubleshooting.md — auth, rate-limit, API-version, deprecation-migration
references/migration-inventory.md — Notion→Obsidian migration read-side inventory method: the 7-step inventory procedure, the 5 API-gap reads it uses, and the read-limit constraints that shape it
Install guide (front door): INSTALL-GUIDE.md — token setup, Code Mode registration, dual-backend config.
Scripts:
scripts/install.sh — prints the Code Mode manual + notion_NOTION_TOKEN env key (read-only)
scripts/doctor.sh — diagnoses Node/npx, the manual, and the token
Embedded Servers:
mcp-servers/notion-mcp/README.md — official @notionhq/notion-mcp-server config notes (stdio, NOTION_TOKEN, dual-backend)
Examples:
examples/README.md — Code Mode Notion workflow examples
Related Skills:
mcp-click-up — structural sibling (light workflow mode)
mcp-obsidian — sibling knowledge app; the migration counterpart
mcp-code-mode — Code Mode MCP orchestration (used for Notion MCP invocation)
External:
1---2name: mcp-notion3description: Operates a Notion workspace through the official Notion MCP over Code Mode, filling its API gaps with direct Notion API calls.4allowed-tools: [Bash, Edit, Glob, Grep, mcp__code_mode__call_tool_chain, Read, Write]5version: 0.1.5.06metadata:7 source: https://skillmd.com/skills/michelkerkmeester/mcp-notion8---910<!-- keywords: notion, notion mcp, notion api, notion database, notion data source, notion page, notion property, notion relation, notion rollup, notion formula, notion token, ntn_, notion-mcp-server, notion markdown, notion search -->1112# mcp-notion Skill1314Notion workspace operations via the **official Notion MCP** (`@notionhq/notion-mcp-server`, 24 tools) over Code Mode, plus **direct Notion API calls** for the five capabilities the MCP does not expose. It knows Notion's data model at the schema layer — data sources, 22 property types, relations, rollups, Formulas 2.0 — so an agent can create, query, and extend a workspace without guessing.1516---1718## 1. MARKDOWN + DATA-SOURCE CONTRACT: READ BEFORE ANY NOTION WRITE1920Two shape rules cause most Notion write failures:21221. **Page bodies vs page properties are different surfaces.** A page's *content* is a tree of **blocks** (append/update via block tools, or the markdown round-trip tools). A page's *metadata* is **properties** typed by its parent data source's schema. Writing prose into a property, or a property value into a block, fails or silently truncates.232. **API 2.0 replaced "databases" with "data sources"** (API version `2025-09-03`). A database is now a container of one or more **data sources**; queries, schema, relations, and rollups all target a **data source id**, not a database id. Using a database id where a data-source id is required is the most common 400.2425Markdown round-trip tools (`retrieve-page-markdown` / `update-page-markdown`) require API version `2026-03-11` and are the token-efficient path for AI. Full detail: `references/database-model.md` and `references/mcp-tools.md`.2627**Failure symptom:** a `validation_error` naming `data_source_id`, or property writes that vanish, means a database id was used where a data-source id was required, or content was routed to the wrong surface.2829---3031## 2. WHEN TO USE3233### Activation Triggers (explicit user phrases)3435- "notion", "notion mcp", "notion api", "mcp-notion"36- "notion page", "notion database", "notion data source", "query notion"37- "create a notion page", "add a row", "notion property", "notion relation", "notion rollup", "notion formula"38- "notion token", "notion integration", "ntn_", "notion search"39- "upload a file to notion", "notion view", "notion async task"4041### Automatic Triggers (keyword patterns)4243- `notion` + any action verb (create, read, update, query, search, append, archive)44- "data source" / "property" / "rollup" / "relation" in a Notion context45- MCP tool names: `create-a-page`, `query-data-source`, `retrieve-a-page` (namespaced `notion.notion_<name>`)4647### When NOT to Use4849- **Community Notion MCP servers** (suekou/mcp-notion-server, awkoy/notion-mcp-server) — this mode uses the **official** `@notionhq/notion-mcp-server` only.50- **Notion→Obsidian migration mechanics (running the importer itself)** — the importer runs inside the Obsidian desktop app, not here; this mode is the read-side inventory enabler (`references/migration-inventory.md`), not the importer.51- Generic markdown authoring with no Notion workspace — use `@markdown` / `sk-doc`.52- Non-Notion knowledge apps (Obsidian, ClickUp docs) — wrong surface (`mcp-obsidian`, `mcp-click-up`).5354---5556## 3. SMART ROUTING5758The `mcp-tooling` hub routes a Notion request here when the prompt names Notion or one of its surfaces (a page, a database or data source, a property, a relation, a token) and the hub's `mcp-notion` signal selects this packet.59The router makes two decisions: the official 24-tool MCP carries page, block, data-source, comment, user and search work while direct Notion API calls fill the five gaps, and the backend is the headless local stdio server, with the remote OAuth server only for an interactive session.6061`references/mcp-tools.md` is the default reference and the fallback suggestion, `references/database-model.md` and `references/property-types.md` load for schema intent, `references/api-gap-tools.md` for a gap, `references/troubleshooting.md` for install or an error, and `references/migration-inventory.md` for a migration inventory.6263A request that scores no intent returns `UNKNOWN_FALLBACK` with its disambiguation checklist, never a silent default.64Read [`ROUTER.md`](./ROUTER.md) before selecting skill-local resources; open only the matched files.6566---6768## 4. HOW IT WORKS6970### Backend Comparison7172| Dimension | Local stdio (default, headless) | Remote MCP (interactive) |73|---|---|---|74| **Transport** | stdio via `npx -y @notionhq/notion-mcp-server` | Streamable HTTP at `https://mcp.notion.com/mcp` |75| **Auth** | `NOTION_TOKEN` (`ntn_…` internal-integration token) | OAuth (browser) |76| **Headless?** | **Yes** — the only Code-Mode-capable backend | No — interactive only |77| **Tool names** | `create-a-page`, `retrieve-a-page`, … | `notion-create-pages`, … + async tasks |78| **Status** | **Deprecated** by Notion, still functional | **Recommended** by Notion |79| **Used by** | Code Mode / automation | Human-in-the-loop clients |8081> **Deprecation note.** Notion is deprecating the open-source local server in favor of the remote OAuth server. Code Mode is headless, so the local stdio server is the correct (and only) choice here today; `references/troubleshooting.md` carries the local→remote migration path for when the operator moves to an interactive workflow.8283### Official Notion MCP — via Code Mode (default path)8485The registered `notion` manual launches `@notionhq/notion-mcp-server` over **stdio** with `npx -y`. It talks to Notion's REST API with the integration's `NOTION_TOKEN`.8687**Prerequisites:**88- Code Mode MCP configured, with the `notion` manual in `.utcp_config.json` (already registered — see INSTALL-GUIDE).89- `notion_NOTION_TOKEN` (an `ntn_…` internal-integration token) available to Code Mode, and the integration granted content access to the target pages/data sources.9091**Configuration** (`.utcp_config.json`, `manual_call_templates`) — already applied:92```json93{94 "name": "notion",95 "call_template_type": "mcp",96 "config": {97 "mcpServers": {98 "notion": {99 "transport": "stdio",100 "command": "npx",101 "args": ["-y", "@notionhq/notion-mcp-server"],102 "env": { "NOTION_TOKEN": "${notion_NOTION_TOKEN}" }103 }104 }105 }106}107```108109The `notion_` env prefix matches the manual name `notion`, so `${notion_NOTION_TOKEN}` resolves. This mode documents that registration; it does not rewrite config files.110111**Tools:** the server exposes **24 `notion_*` tools** across 6 domains — pages (7), blocks (5), data sources (6), comments (2), users (3), search (1). Confirm every name with `tool_info()` / `list_tools()` before calling; the full catalog with per-tool inputs is in `references/mcp-tools.md`.112113**Invocation via Code Mode** (`call_tool_chain` takes a single `code` string):114```typescript115// Code Mode namespaces each tool as notion.notion_<tool_name>. Notion tool names are116// HYPHENATED (create-a-page, retrieve-a-page), so notion.notion_retrieve-a-page is invalid117// JS (it parses as subtraction) — use hyphen-safe BRACKET access. VERIFY once the manual is118// registered: run list_tools() to read the exact callable; Code Mode MAY instead sanitize119// hyphens to underscores (notion.notion_retrieve_a_page). Bracket form is the safe default.120const result = await call_tool_chain({121 code: `122 const hit = await notion["notion_search"]({ query: "Roadmap" });123 const page = await notion["notion_retrieve-a-page"]({ page_id: hit.results[0].id });124 return page;125 `,126});127```128129### The Five API Gaps (direct API)130131File uploads, views, non-truncated page property items, and async-task polling exist in the Notion REST API but **not** in the MCP tool surface; daily notes are a convention with no endpoint. Fill them with direct calls (`Authorization: Bearer $notion_NOTION_TOKEN`, `Notion-Version: 2025-09-03`, or `2026-03-11` for markdown/async). Recipes: `references/api-gap-tools.md`.132133**When to prefer the remote MCP:** interactive sessions where OAuth is available and async-task tools are needed. Otherwise stay on the local stdio backend.134135**Limitations:** search is title-only (no full-text content search); pages archive rather than hard-delete; the workspace is cloud-only (no headless filesystem); rate limit ≈ 3 req/s per integration with `Retry-After`.136137---138139## 5. RULES140141### ✅ ALWAYS1421431. **Resolve the backend before acting** — Code Mode uses the local stdio backend with `NOTION_TOKEN`; only route to the remote OAuth backend when an interactive session is genuinely available. Probe, do not assume.1442. **Target a data-source id, not a database id** — API 2.0 made data sources the primary abstraction; queries, schema, relations, and rollups all take a `data_source_id`.1453. **Route content to the right surface** — page prose → blocks (or markdown round-trip tools); metadata → typed properties. Never cross them.1464. **Confirm MCP tool names with `list_tools()` / `tool_info()`** before calling — Notion tool names are hyphenated (`create-a-page`), so the hyphen-safe callable is bracket-access `notion["notion_create-a-page"]` unless `list_tools()` shows Code Mode sanitized them to underscores.1475. **Read a data source's schema before writing rows** — property types and select options are schema-defined; writing an undefined option or wrong-typed value fails.1486. **Handle the rate limit** — ≈3 req/s per integration; on `429` back off with jitter and honor `Retry-After`. Batch reads where possible.1497. **Pin the API version per operation** — `2025-09-03` for most tools, `2026-03-11` for markdown round-trip and async tasks.1508. **Preview destructive ops** — confirm the exact page/row before archive; Notion archives (recoverable) rather than hard-deletes, but bulk archives are still disruptive.151152### ⛔ NEVER1531541. **Never hardcode the token** — read it from `notion_NOTION_TOKEN` in the Code Mode environment; never inline `ntn_…` in a command, note, or example.1552. **Never use a community Notion MCP server as the default** — this mode is the official `@notionhq/notion-mcp-server`.1563. **Never assume the remote OAuth backend works headless** — it cannot; Code Mode must use the local stdio backend.1574. **Never auto-modify `.utcp_config.json`, `.env.example`, `opencode.json`, or hub files** — the `notion` manual is already registered there; if it needs changing, print the config for the user and never write these files programmatically.1585. **Never fabricate pages, rows, or property values** — if a query returns empty, the data source is genuinely empty or the integration lacks access. Report it.1596. **Never treat search as full-text** — `search` matches titles only; to find by content, retrieve candidate pages and inspect client-side.1607. **Never write markdown into a property field** — prose belongs in blocks or the markdown round-trip; properties are typed values.161162### ⚠️ ESCALATE IF163164- No `NOTION_TOKEN` and no OAuth session → direct the user to `INSTALL-GUIDE.md` (create an internal integration, copy the `ntn_…` token to `.env`, grant content access).165- A `401`/`403` → the token is missing/wrong, or the integration was not granted access to the target page/data source.166- A `validation_error` naming `data_source_id` → a database id was used where a data-source id is required (2.0 migration); resolve the data source first.167- Persistent `429` → the integration is over ≈3 req/s; reduce concurrency, add backoff, or batch.168- The operator wants an interactive/OAuth workflow → follow the local→remote migration path in `references/troubleshooting.md`.169170---171172## 6. SUCCESS CRITERIA173174- [ ] Code Mode `notion["notion_search"]({query})` returns results (empty is valid) — confirms the manual + token work175- [ ] `list_tools()` shows `notion.notion_*` entries; `tool_info("notion.notion_retrieve-a-page")` resolves a live schema176- [ ] `query-data-source` returns rows for a data-source id the integration can access177- [ ] A page create + markdown round-trip (`update-page-markdown` → `retrieve-page-markdown`) preserves content178- [ ] An API-gap call (e.g. a page-property-item `GET`) returns data with the Bearer token from the environment179- [ ] `bash scripts/doctor.sh` reports Node/npx, the `notion` manual, and `notion_NOTION_TOKEN` state without mutating180181---182183## 7. INTEGRATION POINTS184185**Gate 2 (Skill Routing):** activates at ≥0.8 confidence for Notion workspace requests. The advisor matches on `notion`, `notion mcp`, `notion database`, `notion data source`, `notion page`, `notion token`.186187**Code Mode MCP:** the official Notion MCP tools are invoked via `mcp__code_mode__call_tool_chain`; Code Mode namespaces each as `notion.notion_<tool_name>` — use hyphen-safe bracket access since Notion names are hyphenated. See `references/mcp-tools.md`.188189**Migration:** this mode is the read-side inventory enabler for Notion→Obsidian migration (`references/migration-inventory.md`) — the same knowledge layer that operates a live workspace reads its structure to drive an Obsidian import; the write-side reconstruction method lives in `mcp-obsidian`'s `references/notion-migration.md`.190191**Memory:** save Notion workflow context (target data-source ids, integration name, backend) with `/speckit:save` when switching sessions.192193**Tool Usage:** Bash for direct API calls and `scripts/`; `mcp__code_mode__call_tool_chain` for MCP operations; Read to load references on demand.194195---196197## 8. QUICK REFERENCE198199### Notion MCP tool surface (24 tools, 6 domains — confirm names with `tool_info()`)200201| Domain | Count | Representative tools |202|---|---|---|203| **Pages** | 7 | create, retrieve, update, archive; markdown retrieve/update |204| **Blocks** | 5 | retrieve, children, append, update, delete |205| **Data sources** | 6 | query, retrieve, update, create, templates |206| **Comments** | 2 | create, list |207| **Users** | 3 | list, retrieve, bot |208| **Search** | 1 | title search |209210### The 5 gaps → direct API (`references/api-gap-tools.md`)211212| Gap | Endpoint family |213|---|---|214| File uploads | `POST /v1/file_uploads` (+ send / complete) |215| Views | data-source view endpoints |216| Page property items | `GET /v1/pages/{id}/properties/{prop}` |217| Async tasks | task-status endpoint (native on remote MCP) |218| Daily notes | convention (no endpoint) |219220### Code Mode call pattern221222```typescript223// 24 tools, namespaced notion.notion_<tool_name>; hyphenated names → bracket access.224// Confirm the exact callable with list_tools() before relying on either form.225await call_tool_chain({226 code: `227 const ds = await notion["notion_query-data-source"]({228 data_source_id: "DATA_SOURCE_ID",229 filter: { property: "Status", status: { equals: "In progress" } },230 });231 return ds.results.map(p => p.id);232 `,233});234```235236---237238## 9. REFERENCES AND RELATED RESOURCES239240**Reference Files (load on demand via router):**241- `references/mcp-tools.md` — the 24-tool catalog by domain + Code Mode invocation242- `references/api-gap-tools.md` — direct Notion API for the 5 uncovered capabilities243- `references/property-types.md` — 22 property types: schema, value, filter/sort244- `references/database-model.md` — data-source hierarchy, relations, rollups, Formulas 2.0245- `references/troubleshooting.md` — auth, rate-limit, API-version, deprecation-migration246- `references/migration-inventory.md` — Notion→Obsidian migration read-side inventory method: the 7-step inventory procedure, the 5 API-gap reads it uses, and the read-limit constraints that shape it247248Install guide (front door): [INSTALL-GUIDE.md](INSTALL-GUIDE.md) — token setup, Code Mode registration, dual-backend config.249250**Scripts:**251- `scripts/install.sh` — prints the Code Mode manual + `notion_NOTION_TOKEN` env key (read-only)252- `scripts/doctor.sh` — diagnoses Node/npx, the manual, and the token253254**Embedded Servers:**255- `mcp-servers/notion-mcp/README.md` — official `@notionhq/notion-mcp-server` config notes (stdio, `NOTION_TOKEN`, dual-backend)256257**Examples:**258- `examples/README.md` — Code Mode Notion workflow examples259260**Related Skills:**261- `mcp-click-up` — structural sibling (light workflow mode)262- `mcp-obsidian` — sibling knowledge app; the migration counterpart263- `mcp-code-mode` — Code Mode MCP orchestration (used for Notion MCP invocation)264265**External:**266- Official Notion MCP server: [makenotion/notion-mcp-server](https://github.com/makenotion/notion-mcp-server)267- Notion API reference: [developers.notion.com/reference](https://developers.notion.com/reference)