Notion API vs Notion MCP: Which to Use for AI Agent Integration

If you connect an AI agent to Notion, you will soon face a choice: call the Notion API directly from code, or give the agent a Notion MCP server. The two solve different problems, and confusing them causes most of the setup trouble. The Notion API is a set of HTTP requests that your code sends in a fixed format. Notion MCP is an intermediate server that lets an AI agent search, read, and modify Notion as if it were a set of tools. The short answer: the API is more predictable for automation, while MCP is faster for exploration, summarizing, and documentation. For important databases, use MCP to locate the structure and the API or scripts to apply changes. This article explains the difference, why a Notion connection that works in Claude may not appear in Codex, and how to divide the work between the two.

Core Data

1. The Actual State I Checked

When I queried MCP resources in Codex, the first result was empty.

No MCP servers configured yet.

The cause was that the Notion connection I used in Claude was not inherited automatically by Codex. Even if Notion is connected in Claude through an app or account connector, or through a separate environment, Codex CLI requires an MCP server to be registered in ~/.codex/config.toml.

After I registered the Notion MCP server in Codex, I checked the status:

codex mcp list

Name    Command  Args                            Env                 Status
notion  npx      -y @notionhq/notion-mcp-server  NOTION_TOKEN=*****  enabled

The configuration I added:

[mcp_servers.notion]
command = "npx"
args = ["-y", "@notionhq/notion-mcp-server"]

[mcp_servers.notion.env]
NOTION_TOKEN = "..."

2. Differences Between the API and MCP

Category	Notion API	Notion MCP
Basic concept	Calls the Notion API directly with HTTP requests	A Notion tool server that AI agents can use
Who uses it	Scripts, n8n, backend code	MCP clients such as Claude, Codex, and Cursor
Input method	Database IDs, property names, JSON payloads	Natural-language requests and MCP tool calls
Strengths	Predictability, repeatable automation, bulk processing	Exploration, document lookup, context-based organization
Weaknesses	You must know the request format and schema yourself	Agent judgment is involved, so predictability can be lower
Suitable tasks	Scheduled syncs, bulk field updates, n8n workflows	“Find related pages,” “Explain the kanban structure”

An analogy: the API is like sending official documents in a fixed format. MCP is like attaching a Notion assistant to the AI.

3. Why Claude Worked but Codex Did Not

MCP configuration is separate for each client.

Client	Where it is configured	Notes
Claude app and Claude Code	Claude account connectors, claude_desktop_config.json, plugins, and similar	Being visible in Claude does not automatically share the tool with other apps
Codex CLI	~/.codex/config.toml, codex mcp add ...	Requires separate registration
Cursor, Zed, and others	Each app’s MCP settings file	The schema differs from app to app

So it is not strange that Claude can find a page and Codex cannot. Even when the same Notion key is used, you must register the MCP server with each client separately.

4. CLI MCP Servers and Remote MCP Servers

The server I attached to Codex was a CLI MCP server:

codex mcp add notion \
  --env NOTION_TOKEN="$NOTION_API_KEY" \
  -- npx -y @notionhq/notion-mcp-server

With this setup, Codex runs the Notion MCP server locally through npx when it needs it.

Category	CLI MCP	Remote MCP
Where it runs	Your local machine	An external server or service
Authentication	Local environment variable or API key	OAuth or bearer token
Strengths	Simple setup and use of a local token	Easier to share across several clients
Weaknesses	Must be registered for each client, depends on the local environment	Depends on the service’s supported methods and permission policies

For the official Notion package, the NOTION_TOKEN environment variable is recommended.

Decision Criteria

When the API Is the Right Choice

• You create work cards at a fixed time every day.
• You sync Gmail, n8n, databases, and Notion on a recurring basis.
• You must update specific fields in a specific database precisely.
• Logs and retry policies matter when a run fails.
• You need bulk processing or batch jobs.

Example:

node scripts/notion-find-db.mjs "Task DB" --props

Or you can use the Notion node or API in n8n to create a card in the Task DB.

When MCP Is the Right Choice

• You need to explore first, as in “Find the work kanban and show me its structure.”
• You need to read page content and summarize or reorganize it.
• You need to write a document that uses several Notion pages as context.
• You do not know the exact database ID and must find candidates.
• The AI must consult material inside Notion before making a judgment.

Example:

Find the Task DB in Notion and check its status and priority properties.

Recommended Operating Model

1. Find with MCP, Fix with the API

The most stable pattern follows this sequence:

1. Use MCP to find the relevant databases and pages.
2. Confirm the database ID and property schema.
3. Run the actual changes explicitly through the API, a script, or n8n.
4. Verify the result again with an MCP or API query.

This lets you combine the convenience of MCP exploration with the predictability of the API.

2. Keep Database IDs in a Local Registry

Notion search gets confusing when many databases have similar names or there are copies. So I keep frequently used databases in a separate registry:

shared/notion-db-registry.md

Current reference:

Name	ID
Task DB	2dfd0e76-ed44-808a-a7f2-da98f32c65e6

3. Check Each Client’s MCP Status First

For Codex, the first diagnostic step is this command:

codex mcp list

If the output says No MCP servers configured yet, the problem is not MCP itself. The server simply has not been registered.

Applying This to a Kanban Board

Kang Seulgi’s approach centers on four fields:

Task | Collaboration needed | Deadline | Review date before deadline

The Task DB already has these properties (the Korean UI labels them differently; they are listed here in English):

Status, Project DB, Start date, Priority, Due date, Name

So the new properties to consider are these:

Property	Type	Purpose
Collaboration needed	checkbox or select	Distinguishes work you can finish alone from work that needs others’ input
Review date	date	The date to confirm with a manager or collaborator before the deadline
Requester/reviewer	person or rich_text	Records who asked and who must review the work
Next action	rich_text	The smallest action to take right now

Start with simple operating rules:

1. Kick off work that requires collaboration before solo work.
2. Look at the review date before the deadline.
3. When a manager assigns new work, agree on both the deadline and the review date at the same time.
4. When priorities change, record the reason on the card.

Insights

1. MCP Gives the AI a Tool With Permissions

Adding MCP does not make the AI “know” Notion better. It gives the AI a tool that can access Notion. Therefore, tool permissions, the connected workspace, and the scope of shared pages determine the results.

2. The API Is Slow to Set Up but Precise, and MCP Is Fast but Needs Verification

The API is tedious at first. You must know the database ID, property names, and JSON structure. Once you get it right, though, it is strong for repeated work.

MCP starts quickly. You can ask in natural language to “find it.” However, the agent may choose the wrong candidate, and results can differ because of configuration differences between clients.

3. “Claude Works but Codex Does Not” Is an Environment Difference

AI tools can look like the same model while running in different environments. Claude connectors, Codex MCP settings, n8n credentials, and the local .zshenv file are separate layers. Most Notion integration problems come from mixing these layers together.

4. Keep a Readable Log for Important Changes

Notion automation changes results quietly inside Notion, which makes them hard to trace later. Record which key, which database, and which property were changed in a local document or script output.

Social Post Drafts

LinkedIn Version

I ran into a case where Claude could find Notion pages, but Codex could find nothing.

At first I wondered whether the Notion API key was wrong. The cause was simpler: no Notion MCP server was registered in Codex.

The criteria I settled on:

• The Notion API is a way for code to send requests to Notion directly.
• Notion MCP is an intermediate server that lets an AI agent use Notion as a tool.
• An MCP connection that works in Claude is not automatically inherited by Codex.
• Each client needs its own MCP server registration.

My practical rule:

For repeated automation, bulk processing, and precise field updates, the API is better. For exploratory tasks such as “find related pages,” “explain the work kanban structure,” or “read this page and organize it,” MCP is much more convenient.

The best combination is to find with MCP and fix with the API.

Use MCP to locate databases and pages, then make the actual changes explicitly with a script, the API, or n8n. That keeps the AI’s exploration convenience and the predictability of code.

Threads Version

The reason Claude can find Notion but Codex cannot.

It may not be an API key problem.

MCP configuration is separate for each client.

Even if Claude has a Notion connector,
Codex does not get it automatically.

In Codex, check this first:

codex mcp list

If you see No MCP servers configured yet, the answer is simple.

You need to register the Notion MCP server.

codex mcp add notion \
  --env NOTION_TOKEN="$NOTION_API_KEY" \
  -- npx -y @notionhq/notion-mcp-server

My rule of thumb:

• Exploration, summarizing, and documentation: MCP
• Repeated automation and precise updates: API
• Important work: find with MCP, fix with the API

This combination causes the least confusion.

Bottom line

The Notion API and Notion MCP are complementary, not interchangeable. The API is the right tool when you need predictable, repeatable, and auditable changes to specific fields, such as scheduled syncs, bulk updates, and n8n workflows. MCP is the right tool when an agent needs to explore a workspace, locate databases, or read and summarize pages. Connection problems like the Claude-versus-Codex case usually come from MCP configuration being per client, not from a bad key, so check the client’s registered servers first with codex mcp list. The workflow the evidence supports is to find with MCP, apply changes with the API or a script, and verify the result afterward.

Sources

The source note contains no URLs. It references these local files and one package:

• Codex MCP configuration: ~/.codex/config.toml
• Notion database search script: scripts/notion-find-db.mjs
• Notion database registry: shared/notion-db-registry.md
• n8n progress notes: n8n-local/PROGRESS.md
• Official Notion MCP npm package: @notionhq/notion-mcp-server