# How to Integrate Notion for Documentation and Planning Workflows in Codex

> Integrate Notion with Codex using its manifest registration, skill workflows, and MCP tool calls. Automate documentation, research, and planning directly in Notion.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-07-04

---

**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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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

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

```

### Fetch Page Content

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

```

### Create an Implementation Plan

```json
{
  "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

```json
{
  "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

```json
{
  "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`](https://github.com/openai/plugins/blob/main/plugins/notion/README.md)** – Provides the high-level description of the plugin structure and bundled capabilities.
- **[`plugins/notion/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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.