notion-mcp-skill

# Notion MCP Skill Use this skill to run Notion MCP operations through `uxc` with OAuth and guarded write behavior. Reuse the `uxc` skill guidance for discovery, schema inspection, OAuth lifecycle, and error recovery. Do not assume another skill is auto-triggered in every runtime. Keep this skill executable on its own. ## Prerequisites - `uxc` is installed and available in `PATH`. - Network access to `https://mcp.notion.com/mcp`. - OAuth callback listener is reachable (default examples use `http://127.0.0.1:8788/callback`). - `uxc` skill is available for generic discovery/describe/execute patterns. ## Core Workflow (Notion-Specific) Endpoint argument style in this skill: - Prefer shorthand `mcp.notion.com/mcp` (scheme omitted). - Full URL `https://mcp.notion.com/mcp` is also valid. 1. Ensure endpoint mapping exists: - `uxc auth binding match mcp.notion.com/mcp` 2. If mapping/auth is not ready, start OAuth login: - `uxc auth oauth start notion-mcp --endpoint mcp.notion.com/mcp --redirect-uri http://127.0.0.1:8788/callback --scope read --scope write` - Prompt user to open the printed authorization URL. - Ask user to paste the full callback URL after consent. - Complete login with `uxc auth oauth complete notion-mcp --session-id <session_id> --authorization-response '<callback-url>'` 3. Bind endpoint to the credential: - `uxc auth binding add --id notion-mcp --host mcp.notion.com --path-prefix /mcp --scheme https --credential notion-mcp --priority 100` 4. Use fixed link command by default: - `command -v notion-mcp-cli` - If missing, create it: `uxc link notion-mcp-cli mcp.notion.com/mcp` - `notion-mcp-cli -h` - If command conflict is detected and cannot be safely reused, stop and ask skill maintainers to pick a different fixed command name. 5. Discover tools and inspect schema before execution: - `notion-mcp-cli -h` - `notion-mcp-cli notion-fetch -h` - `notion-fetch` requires `id` (URL or UUID). Examples: - `notion-mcp-cli notion-fetch id="https://notion.so/your-page-url"` - `notion-mcp-cli notion-fetch id="12345678-90ab-cdef-1234-567890abcdef"` - Common operations include `notion-search`, `notion-fetch`, and `notion-update-page`. 6. Prefer read path first: - Search/fetch current state before any write. 7. Execute writes only after explicit user confirmation: - For `notion-update-page` operations that may delete content, always confirm intent first. ## OAuth Interaction Template Use this exact operator-facing flow: 1. Start login command and wait for authorization URL output. 2. Tell user: - Open this URL in browser and approve Notion access. - Copy the full callback URL from browser address bar. - Paste the callback URL back in chat. 3. Run `uxc auth oauth complete notion-mcp --session-id <session_id> --authorization-response '<callback-url>'`. 4. Optionally confirm success with: - `uxc auth oauth info <credential_id>` Do not ask user to manually extract or copy bearer tokens. Token exchange is handled by `uxc`. Use `uxc auth oauth login ... --flow authorization_code` only for a single-process interactive fallback. ## Guardrails - Keep automation on JSON output envelope; do not use `--text`. - Parse stable fields first: `ok`, `kind`, `protocol`, `data`, `error`. - Use `notion-mcp-cli` as the default command path for all Notion MCP calls in this skill. - `notion-mcp-cli <operation> ...` is equivalent to `uxc mcp.notion.com/mcp <operation> ...`. - Use direct `uxc mcp.notion.com/mcp ...` only as a temporary fallback when link setup is unavailable. - Call `notion-fetch` before `notion-create-pages` or `notion-update-page` when targeting database-backed content to obtain exact schema/property names. - Treat operations as high impact by default: - Require explicit user confirmation before create/update/move/delete-style actions. - If OAuth/auth fails, use `uxc` skill OAuth/error playbooks first, then apply Notion-specific checks in this skill's references. ## References - Notion-specific auth notes (thin wrapper over `uxc` skill OAuth guidance): - `references/oauth-and-binding.md` - Invocation patterns by task: - `references/usage-patterns.md` - Notion-specific failure notes (thin wrapper over `uxc` skill error guidance): - `references/error-handling.md`