Setting up Notion Knowledge Capture in Codex

What Notion Knowledge Capture is and why it is used

Notion Knowledge Capture is a skill from the official openai/skills repository, stored in the curated skills/.curated directory, and primarily designed for use with OpenAI Codex. According to the provider, the skill converts conversations, notes, and decisions into structured, linkable Notion pages, for example for team wikis, how-to guides, FAQ collections, or decision logs. The core idea is that conversations with an AI agent often produce valuable knowledge that gets lost quickly without deliberate follow-up work. The skill automates the step of turning that knowledge into a durably findable form by selecting the right Notion database type, structuring the content accordingly, and creating links to related pages. This is particularly relevant for teams that regularly use Codex or similar agents for research, architecture decisions, or debugging and don't want those results to disappear into chat logs.

Prerequisites

The technical prerequisite is a working connection between the coding agent and Notion via the Model Context Protocol, or MCP. According to the skill's documentation, the Notion MCP server is added with the command codex mcp add notion using the URL https://mcp.notion.com/mcp. In addition, the option rmcp_client must be set to true in Codex's config.toml configuration file, or Codex must be started with the --enable rmcp_client flag, since otherwise no remote MCP connection can be established. After that, an OAuth login via codex mcp login notion is required, for which a valid Notion account with write access to the target workspace is needed. Without this setup, any attempt to create or update a page will fail.

Setting it up step by step

First, the Notion MCP server is registered as described and remote MCP support is enabled. After a successful OAuth login, Codex needs to be restarted once for the connection to become fully active. In the actual workflow, the skill first clarifies what should be captured, for example a decision, a how-to guide, or an FAQ, and for which audience. It then identifies the appropriate Notion database and its schema using the reference files shipped with the skill, searches existing pages with the notion-search tool to avoid duplicates, and creates a new page via notion-create-pages with a summary, context, source links, and tags. Pages that already exist are instead updated via notion-update-page, and finally links from higher-level hub pages are added.

Security and best practices

Because the skill gains direct write access to a Notion workspace via MCP, the connected Notion account should hold only the permissions that are actually needed for the intended use, to avoid accidental or unwanted changes to sensitive areas. It is advisable to verify in a test area, before production use, that generated pages are formatted and linked correctly. Since OAuth credentials remain permanently tied to the Codex profile, it should be possible to revoke access via the Notion account settings whenever needed. The provider also notes that when updating existing pages, a short change note should be added so later readers can understand when and why an entry was changed.

A practical example and its limits

A practical example is an architecture review conversation with Codex that results in a structured decision page in Notion's decision log, complete with alternatives, rationale, and a link to the affected project. The limits are that the quality of the generated page depends heavily on the quality of the original conversation, and the skill performs no fact-checking in the sense of content verification; it merely structures what was present in the conversation. Functionality is also tied to a working, authorized MCP connection, so users without Notion access or without the ability to configure MCP servers cannot make meaningful use of the skill.