How to Integrate Notion for Documentation and Planning Workflows in Codex

Codex integrates with Notion through a dedicated plugin that combines manifest registration, skill-based workflows, and Model Context Protocol (MCP) tool calls to automate documentation, research, and implementation planning directly within your Notion workspace.

The openai/plugins repository provides a production-ready Notion integration that enables Codex to read specifications, create structured project plans, and manage task databases. Integrating Notion for documentation and planning workflows in Codex involves configuring the plugin manifest, leveraging skill-based payloads, and invoking specific MCP tool calls. By leveraging the Notion plugin located under plugins/notion, developers can automate end-to-end documentation processes without leaving their AI coding environment.

Plugin Architecture and Manifest Configuration

The Notion integration is governed by the plugin manifest located at plugins/notion/.codex-plugin/plugin.json. This file registers the Notion app and declares three core capabilities: Read, Write, and Interactive.

According to the openai/plugins source code, the manifest points Codex to the skill directory ("skills": "./skills/") and the app definition (".app.json"). This wiring ensures that once the Notion app is authorized, any skill under plugins/notion/skills/* can be invoked automatically. The architecture sandboxes all operations within the plugin directory, executing only through the official Notion MCP integration.

Core Notion MCP Tool Calls

Codex interacts with your Notion workspace through four concrete Model Context Protocol (MCP) tool calls defined in the plugin:

• Notion:search – Queries the workspace to locate pages by title or content.
• Notion:fetch – Retrieves full page content and metadata from a specific URL.
• Notion:notion-create-pages – Generates new pages or database entries with specified templates and properties.
• Notion:notion-update-page – Modifies existing pages to add links, update content, or change status.

These tools enable the full spectrum of documentation and planning workflows, from discovering specification documents to creating hierarchical task structures.

The Spec-to-Implementation Workflow

When a user prompts Codex to "create a project plan in Notion," the system executes the Spec-to-Implementation workflow defined in plugins/notion/skills/notion-spec-to-implementation/SKILL.md. This skill orchestrates the tool calls into a six-step process:

1. Authentication Check – Ensure the Notion app is connected; if tools are missing, prompt the user to complete the auth flow (referenced in SKILL.md sections 0-3).

2. Locate Spec Page – Use Notion:search to find the specification, then Notion:fetch to retrieve its content (sections 35-38).

3. Parse Requirements – Extract requirements, acceptance criteria, and constraints using local parsing logic defined in reference/spec-parsing.md.

4. Create Implementation Plan – Invoke Notion:notion-create-pages with either a "quick" or "full" template to generate the plan page (sections 40-44).

5. Generate Tasks – Search for the task database using Notion:search, confirm the schema with Notion:fetch, and create individual tasks using Notion:notion-create-pages (sections 45-49).

6. Link Resources – Optionally use Notion:notion-update-page to connect the spec, plan, and tasks together, then establish progress tracking cadences (sections 50-55 and reference/progress-tracking.md).

Example Tool Call Payloads

Below are the JSON payloads that Codex emits when executing Notion workflows. These represent the actual MCP tool calls made during the spec-to-implementation process.

Search for a Specification Page

{
  "tool": "Notion:search",
  "arguments": {
    "query": "Payment Integration spec",
    "filters": {}
  }
}

Fetch Page Content

{
  "tool": "Notion:fetch",
  "arguments": {
    "url": "https://www.notion.so/your-workspace/abc123def456"
  }
}

Create an Implementation Plan

{
  "tool": "Notion:notion-create-pages",
  "arguments": {
    "parent": { "type": "page_id", "page_id": "abc123def456" },
    "title": "Implementation Plan: Payment Integration",
    "template": "quick",
    "content": {
      "overview": "Brief description …",
      "requirements": "Parsed from spec …"
    }
  }
}

Create a Task in the Database

{
  "tool": "Notion:notion-create-pages",
  "arguments": {
    "parent": { "type": "collection_id", "collection_id": "task-db-789xyz" },
    "title": "Validate payment gateway webhook",
    "properties": {
      "Status": "To Do",
      "Priority": "High",
      "Related Plan": "Implementation Plan: Payment Integration",
      "Due date": "2026-08-01"
    }
  }
}

Update the Spec with Plan Links

{
  "tool": "Notion:notion-update-page",
  "arguments": {
    "url": "https://www.notion.so/your-workspace/abc123def456",
    "command": "update_content",
    "old_str": "## Implementation",

    "new_str": "## Implementation\n- Plan: [Implementation Plan: Payment Integration](https://www.notion.so/plan-link)"

  }
}

Key Source Files Reference

Understanding the following files is essential for customizing or debugging the Notion integration:

• plugins/notion/README.md – Provides the high-level description of the plugin structure and bundled capabilities.
• plugins/notion/.codex-plugin/plugin.json – The manifest that registers the app and declares Read, Write, and Interactive capabilities.
• plugins/notion/skills/notion-spec-to-implementation/SKILL.md – Defines the complete workflow for converting specs into implementation plans and tasks.
• plugins/notion/skills/notion-spec-to-implementation/reference/spec-parsing.md – Documents patterns for extracting structured requirements from specification pages.
• plugins/notion/skills/notion-spec-to-implementation/reference/task-creation.md – Contains templates and property schemas for task database entries.
• plugins/notion/skills/notion-spec-to-implementation/reference/progress-tracking.md – Specifies cadence templates for updating task and plan progress.

Summary

• The Notion plugin in plugins/notion enables Codex to perform Read, Write, and Interactive operations on your Notion workspace through MCP tool calls.
• The notion-spec-to-implementation skill orchestrates a six-step workflow that transforms specification pages into linked implementation plans and actionable tasks.
• Four core tools—Notion:search, Notion:fetch, Notion:notion-create-pages, and Notion:notion-update-page—handle all data exchange between Codex and Notion.
• Workflow logic is defined in SKILL.md files with supporting references for parsing, task creation, and progress tracking, ensuring reproducible documentation and planning automation.

Frequently Asked Questions

What capabilities does the Notion plugin declare in Codex?

The plugin manifest at plugins/notion/.codex-plugin/plugin.json declares three capabilities: Read for retrieving page content, Write for creating and updating pages, and Interactive for handling user authentication flows. These capabilities determine which Notion MCP tools are available to Codex at runtime.

How does Codex authenticate with Notion?

Authentication occurs during Step 0 of any Notion workflow. If the required MCP tools are missing, Codex prompts the user to complete the OAuth flow to connect the Notion app. Once authorized, the connection persists across sessions, allowing seamless invocation of Notion:search, Notion:fetch, and other tools without repeated authentication.

What is the difference between "quick" and "full" templates in the spec-to-implementation workflow?

The "quick" template generates a lightweight implementation plan with essential sections like overview and requirements, while the "full" template creates a comprehensive plan including detailed timelines, risk assessments, and resource allocation. Both are invoked through Notion:notion-create-pages and are defined in the skill configuration at plugins/notion/skills/notion-spec-to-implementation/SKILL.md.

Where are the skill definitions stored for Notion documentation workflows?

Skill definitions are stored in the plugins/notion/skills/ directory. The primary workflow for documentation and planning is defined in plugins/notion/skills/notion-spec-to-implementation/SKILL.md, with supporting reference files located in the reference/ subdirectory of that skill folder. These files contain the parsing logic, task templates, and progress tracking cadences that Codex follows when executing workflows.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}