How to Use the Notion Developer Platform with Claude and Codex Agents

What Notion’s Developer Platform Actually Gives You Now

If you’ve been watching Notion’s developer tooling, 2024–2025 has been a significant shift. The platform moved from a read-heavy REST API toward a full development environment — one that lets you build, deploy, and respond to events directly inside Notion. Combined with AI coding and reasoning agents like Claude and OpenAI Codex, you can now wire real intelligence into your workspace without stitching together half a dozen services.

This guide covers what’s new in the Notion developer platform, how to connect Claude or Codex agents to your workspace, and what that looks like in practice for real automations.

---

The Four Pillars of Notion’s Developer Platform

Before writing any agent code, it helps to understand what you’re actually working with. Notion’s developer platform now has four core components that didn’t all exist (or didn’t work well together) a year ago.

The Notion CLI

The Notion CLI lets you scaffold, develop, and deploy integrations from your terminal. Instead of manually creating integrations in the Notion UI and copying tokens, you can run notion create to bootstrap a project, configure auth locally, and push changes without leaving your editor.

It handles integration setup, environment variables, and deployment targets. For teams building Claude-powered Notion tools, it dramatically shortens the feedback loop.

Webhooks

Notion’s webhook support lets your integration subscribe to events on pages, databases, and comments. When a page is updated, a database row is added, or a comment is posted, Notion sends a POST request to your endpoint with a structured payload.

This is the trigger layer. Without webhooks, you’d need to poll the Notion API constantly to detect changes — expensive and slow. With webhooks, your Claude agent can respond to events in near-real-time.

Notion Workers

Workers are lightweight serverless functions that run on Notion’s infrastructure. You write a function, deploy it through the CLI, and Notion executes it in response to events or on demand. Workers can call external APIs, run logic, and write back to Notion pages or databases.

Think of them as the computation layer that sits between a webhook trigger and a Notion write operation. You can call a Claude or Codex API from a Worker, pass it page content, and write the result back — all without managing your own servers.

The External Agents API

This is the most relevant piece for AI integrations. The External Agents API is designed specifically for AI agents to interact with Notion. It exposes a set of tools — read page, query database, create page, update block — in a format that AI systems can discover and call.

When you connect Claude or Codex to Notion through this API, the agent can navigate your workspace, read context, and take actions based on instructions. It’s not just data access; it’s structured tool use.

---

Prerequisites Before You Start

You’ll need a few things in place:

• A Notion account with admin access to a workspace
• A Notion integration (created at developers.notion.com) with the pages and databases you want to access shared with it
• An Anthropic API key (for Claude) or OpenAI API key (for Codex)
• Node.js 18+ installed
• The Notion CLI installed: npm install -g @notionhq/notion-cli

Authentication in Notion uses OAuth 2.0 for public integrations or internal integration tokens for workspace-scoped tools. For most Claude/Codex agent setups, you’ll start with an internal integration token — simpler to set up and sufficient for workspace automation.

---

Setting Up Your Notion Integration

Create the Integration

Go to your Notion workspace settings, navigate to Connections, then Develop or manage integrations. Create a new internal integration and give it a descriptive name (something like “Claude Agent” or “Codex Automation”).

Set the capabilities your agent will need:

• Read content — lets the agent read pages and databases
• Update content — lets it write back results
• Insert content — lets it create new pages or blocks
• Read user information — optional, useful if your workflows are user-specific

Copy your integration token and store it securely (an .env file works for local development; a secrets manager for production).

Share Pages with the Integration

This step trips up a lot of people. Notion integrations don’t have blanket access to your workspace — you have to explicitly share pages or databases with them. Open the page or database you want the agent to access, click the three-dot menu, go to Connections, and add your integration.

Any child pages of a shared parent are automatically accessible. For database-driven workflows, share the database directly.

---

Connecting Claude to Notion

Claude’s tool use API lets you define a set of functions — with JSON Schema parameter definitions — that the model can choose to call during a conversation or task. You write the execution logic; Claude decides when to use which tool and what to pass in.

Define Notion as Tools for Claude

Here’s the basic pattern. You define tools that wrap Notion API calls and pass them to Claude via the Anthropic SDK:

import Anthropic from "@anthropic-ai/sdk";
import { Client } from "@notionhq/client";

const notion = new Client({ auth: process.env.NOTION_TOKEN });
const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

const tools = [
  {
    name: "query_database",
    description: "Query a Notion database with optional filters",
    input_schema: {
      type: "object",
      properties: {
        database_id: { type: "string", description: "The Notion database ID" },
        filter: { type: "object", description: "Optional filter object" },
      },
      required: ["database_id"],
    },
  },
  {
    name: "create_page",
    description: "Create a new page in a Notion database",
    input_schema: {
      type: "object",
      properties: {
        database_id: { type: "string" },
        title: { type: "string" },
        content: { type: "string" },
      },
      required: ["database_id", "title"],
    },
  },
  {
    name: "read_page",
    description: "Read the content of a Notion page by ID",
    input_schema: {
      type: "object",
      properties: {
        page_id: { type: "string" },
      },
      required: ["page_id"],
    },
  },
];

Handle Tool Calls

Claude will return a tool_use content block when it decides to call a Notion function. You execute the actual API call and pass the result back:

async function executeToolCall(toolName, toolInput) {
  if (toolName === "query_database") {
    const response = await notion.databases.query({
      database_id: toolInput.database_id,
      filter: toolInput.filter,
    });
    return JSON.stringify(response.results);
  }

  if (toolName === "create_page") {
    const response = await notion.pages.create({
      parent: { database_id: toolInput.database_id },
      properties: {
        Name: { title: [{ text: { content: toolInput.title } }] },
      },
      children: toolInput.content
        ? [
            {
              object: "block",
              type: "paragraph",
              paragraph: {
                rich_text: [{ text: { content: toolInput.content } }],
              },
            },
          ]
        : [],
    });
    return JSON.stringify({ id: response.id });
  }

  if (toolName === "read_page") {
    const blocks = await notion.blocks.children.list({
      block_id: toolInput.page_id,
    });
    return JSON.stringify(blocks.results);
  }
}

Run the Agent Loop

Claude may call tools multiple times in a single task. You need an agentic loop that keeps passing results back until Claude signals it’s done:

async function runClaudeNotionAgent(userMessage) {
  const messages = [{ role: "user", content: userMessage }];

  while (true) {
    const response = await anthropic.messages.create({
      model: "claude-opus-4-5",
      max_tokens: 4096,
      tools,
      messages,
    });

    if (response.stop_reason === "end_turn") {
      return response.content.find((b) => b.type === "text")?.text;
    }

    if (response.stop_reason === "tool_use") {
      messages.push({ role: "assistant", content: response.content });

      const toolResults = [];
      for (const block of response.content) {
        if (block.type === "tool_use") {
          const result = await executeToolCall(block.name, block.input);
          toolResults.push({
            type: "tool_result",
            tool_use_id: block.id,
            content: result,
          });
        }
      }

      messages.push({ role: "user", content: toolResults });
    }
  }
}

With this setup, you can run prompts like:

• “Find all tasks in the project database marked High Priority and summarize them.”
• “Create a weekly review page with bullet points for each item added to the backlog this week.”
• “Read the meeting notes from yesterday and extract all action items into the tasks database.”

---

Connecting Codex to Notion

OpenAI’s Codex capabilities are now baked into the GPT-4 family via the API’s function calling interface. The pattern is similar to Claude but uses OpenAI’s SDK and function definition format.

Define Functions for Codex

import OpenAI from "openai";

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const functions = [
  {
    name: "query_notion_database",
    description: "Query a Notion database",
    parameters: {
      type: "object",
      properties: {
        database_id: { type: "string" },
        filter_property: { type: "string" },
        filter_value: { type: "string" },
      },
      required: ["database_id"],
    },
  },
  {
    name: "update_notion_page",
    description: "Update a property on an existing Notion page",
    parameters: {
      type: "object",
      properties: {
        page_id: { type: "string" },
        property_name: { type: "string" },
        property_value: { type: "string" },
      },
      required: ["page_id", "property_name", "property_value"],
    },
  },
];

Codex (via GPT-4) is particularly effective for code-adjacent workflows — generating SQL-like filter logic for Notion databases, writing content for documentation pages, or producing structured data from unstructured text and inserting it directly into a database.

---

Triggering Agents with Webhooks and Workers

The real power comes when you combine webhooks with your agent logic. Instead of running agents manually, you trigger them automatically when something happens in Notion.

Set Up a Webhook

Register your webhook endpoint through the Notion API:

curl -X POST https://api.notion.com/v1/webhooks \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-worker.example.com/webhook",
    "filter": {
      "object": "page",
      "event_type": "page.updated"
    }
  }'

When a page is updated, Notion sends a payload to your endpoint with the page ID, event type, and actor.

Deploy a Notion Worker to Handle It

Inside your Notion Worker, receive the webhook, extract the page ID, pass it to Claude with relevant context, and write the result back:

export default {
  async fetch(request) {
    const event = await request.json();
    const pageId = event.entity.id;

    // Claude reads the page and generates a summary
    const summary = await runClaudeNotionAgent(
      `Read page ${pageId} and update its Summary property with a 2-sentence summary of the content.`
    );

    return new Response("OK", { status: 200 });
  },
};

This pattern works for a range of automated workflows: auto-tagging content, generating summaries on save, routing items between databases based on content, or alerting team members via a Notion comment.

---

Practical Workflows Worth Building

Here are a few patterns that work well with Claude or Codex agents in Notion:

Weekly digest generator — A scheduled Codex agent queries your tasks database for items completed in the past seven days, formats them into a structured summary, and creates a new page in a Reports database.

Meeting notes processor — A webhook fires when a new meeting notes page is created. Claude reads the page, extracts decisions and action items, creates tasks in your project database, and adds a “Processed” tag to the original page.

Content brief enrichment — When a new row is added to a content brief database, a Claude agent reads the brief, searches for relevant context from other linked pages, and fills in a “Research Notes” field with synthesis.

Bug triage assistant — A Codex agent monitors a bug report database, reads each new entry, cross-references a known-issues page, labels duplicates, and assigns severity based on description content.

---

How MindStudio Fits Into Notion Agent Workflows

Building the infrastructure for Claude-Notion or Codex-Notion integrations takes time — you’re writing tool definitions, managing auth, handling webhook routing, building agentic loops, and deploying Workers. That’s meaningful engineering work before you’ve even started on the actual logic your workflow needs.

MindStudio handles that infrastructure layer so you can focus on what the agent actually does. It has native Notion integration built in, along with 200+ AI models including Claude (Opus, Sonnet, Haiku) and all current OpenAI models — no API keys or separate accounts required.

You can build a Notion-connected Claude agent in the visual builder without writing any of the tool definition or agentic loop code described above. MindStudio manages the connection, handles retries and rate limiting, and lets you test the workflow interactively before deploying it.

For the webhook-and-worker pattern, MindStudio supports webhook/API endpoint agents — you get a URL, configure your Notion integration to send events there, and your agent processes them without you running any infrastructure. It also supports scheduled background agents for the weekly digest or periodic cleanup workflows.

If you’re already comfortable with the code path, MindStudio’s Agent Skills Plugin (@mindstudio-ai/agent) is worth knowing about: it exposes 120+ typed capabilities as simple method calls, so a Claude Code or LangChain agent can call agent.runWorkflow() to hand off to a MindStudio Notion workflow without rewriting everything.

You can try it free at mindstudio.ai.

---

Frequently Asked Questions

What is the Notion External Agents API?

The Notion External Agents API is a set of endpoints designed for AI agents to interact with Notion workspaces. It exposes structured tools — for reading pages, querying databases, creating content, updating properties — in a format compatible with AI tool use frameworks. It’s different from the standard Notion REST API in that it’s structured around the actions an agent would take, not just raw CRUD operations.

Can Claude access my Notion workspace directly?

Not without setup on your part. Claude doesn’t have built-in Notion access. You need to create a Notion integration, share the relevant pages with it, and define Notion API calls as tools that Claude can invoke through Anthropic’s tool use API. Once set up, Claude can read pages, query databases, create content, and update properties within whatever you’ve shared with the integration.

What’s the difference between using Claude vs. Codex for Notion automation?

Claude tends to perform better on tasks that require reading and synthesizing long-form content — meeting notes, research pages, multi-step reasoning. Codex (via GPT-4) is particularly strong at generating structured output from unstructured input, writing code-like queries, and handling well-defined data transformation tasks. For most Notion automation, either model works. The right choice depends on the task: use Claude for analysis and synthesis, Codex for data manipulation and structured generation.

Do I need Notion’s paid plan to use the developer platform?

No. The Notion API and integration features are available on all plans, including free workspaces. Some features (like certain database properties or page history) may be plan-limited, but the core developer platform — CLI, webhooks, integrations — is accessible without a paid subscription.

How do Notion webhooks work with AI agents?

You register a webhook endpoint with Notion, specifying the event type (page updated, database item added, etc.) and the URL to receive payloads. When the event occurs, Notion sends a POST request to that URL with event details including the affected object ID. Your server or worker receives this, calls the Notion API to get full context, passes it to an AI agent, and optionally writes results back to Notion. The whole loop can complete in seconds.

Is there a rate limit I need to worry about?

Yes. The Notion API has a rate limit of approximately three requests per second per integration. For agent workflows that make multiple API calls per task (reading a page, querying a database, writing results), you can hit this quickly. Build in request queuing or use a library that handles rate limiting. If you’re using MindStudio, rate limiting is handled automatically.

---

Key Takeaways

• Notion’s developer platform now includes a CLI, webhooks, serverless Workers, and an External Agents API — together they give you the primitives to build event-driven AI agent workflows inside Notion.
• Claude connects to Notion through Anthropic’s tool use API: define Notion API calls as tools, write an agentic loop, and Claude can read, write, and reason across your workspace.
• Codex (via OpenAI’s function calling API) follows the same pattern and is especially effective for structured data tasks.
• Webhooks plus Workers let your agents respond to Notion events automatically — no polling, no manual triggers.
• If you want to skip building the infrastructure layer, MindStudio’s native Notion integration with Claude support gets you to a working agent workflow faster.

The combination of Notion’s structured workspace data and Claude’s reasoning capabilities opens up a useful class of automations — ones that don’t just move data but actually process and act on it. Start with one concrete workflow, get it working end to end, and build from there.