Codex で Notion を MCP 連携する手順と注意点

Notion と Codex を MCP でつなぐと何ができるか

MCP は、AI エージェントと外部ツールの間を標準化された手順でつなぐ仕組みだ。Codex 単体ではローカルのファイルとシェルしか触れないが、MCP サーバーを登録すると、そのサーバーが公開する「ツール」を Codex が呼び出せるようになる。Notion の MCP サーバーは、ページの検索・取得・作成・更新、データベースのクエリといった操作をツールとして提供しているため、Codex から Notion のコンテンツへ読み書きの両方向でアクセスできるようになる。

実際の開発で効果が出やすいのは、仕様や要件が Notion に集約されているケースだ。たとえば「Notion の『API 仕様』ページに書かれたエンドポイント定義を読んで、対応するハンドラを実装してほしい」と指示すれば、Codex は Notion からページ本文を取得し、その内容を文脈として実装に反映できる。逆に、実装が終わった後に「変更点を Notion の作業ログページに追記しておいて」と頼めば、結果を Notion 側へ書き戻すことも可能だ。ドキュメントとコードを人間が手で往復していた部分を、Codex に橋渡しさせられる点が最大の利点と言える。

MCP の仕様や対応状況は変化が速い領域でもある。Codex 側の MCP 対応の詳細は OpenAI の開発者ドキュメント(https://developers.openai.com/codex/mcp)に、Notion 側の MCP サーバーの使い方は Notion の公式ガイド(https://developers.notion.com/guides/mcp/get-started-with-mcp)にまとまっている。接続前に双方の最新情報を確認しておくと、仕様変更によるつまずきを避けやすい。

連携前に押さえる 2 つの接続方式

Notion の MCP サーバーには接続方式が 2 系統あり、どちらを選ぶかで設定内容も認可の流れも変わる。先に違いを理解しておくと、自分の用途に合った方を迷わず選べる。Codex CLI 側はどちらの方式にも対応しており、設定はいずれも ~/.codex/config.toml への追記、またはプロジェクト直下の .codex/config.toml(信頼済みプロジェクトのみ)で行う。設定ファイルのキーは mcpServers ではなく mcp_servers(スネークケース)である点に注意したい。

ホスト型リモート MCP(推奨)

Notion が自社で運用しているリモートサーバーで、エンドポイントは https://mcp.notion.com/mcp だ。Codex 側からは Streamable HTTP 方式で接続する。インフラを自分で立てる必要がなく、Notion が継続的に保守しているため、まず試すならこの方式が向いている。AI エージェント向けに最適化されたツール群が用意されているのも利点だ。認可はブラウザ上で行い、利用者ごとにワークスペースへのアクセスを許可する形になる。固定トークンを設定ファイルへ書き込む必要がない分、接続情報の取り回しもシンプルになる。

セルフホスト型 STDIO サーバー

@notionhq/notion-mcp-server を npx などでローカルプロセスとして起動し、Codex と標準入出力(STDIO)でやり取りする方式だ。Notion のインテグレーショントークンを環境変数で渡して接続するため、ブラウザ認可を挟まない固定的なつなぎ方ができる。旧来の JSON ベースの v1 API を使いたい場合や、接続をスクリプトで再現したい場合に向く。ただしこのオープンソースパッケージは現在、積極的なメンテナンス対象から外れているとされているため、長期運用ではホスト型への移行も視野に入れておくとよい。

ホスト型 Notion MCP を Codex に登録する手順

ここからは、推奨方式であるホスト型リモート MCP を Codex CLI に登録する具体的な流れを示す。所要時間は数分で、特別なツールのインストールは不要だ。

Step 1: config.toml を開く

Codex の設定ファイルは既定で ~/.codex/config.toml にある。まだ存在しない場合は新規に作成してよい。プロジェクト単位で接続先を分けたいときは、リポジトリ直下に .codex/config.toml を置く方法もあるが、これは信頼済みプロジェクトでのみ有効になる点を覚えておく。チームで共有するリポジトリに接続定義を含めるかどうかは、後述の権限設計と合わせて判断したい。

Step 2: mcp_servers.notion を追記する

設定ファイルに、Notion のリモートサーバーを指す [mcp_servers.notion] テーブルを追記する。Streamable HTTP 方式では url フィールドにエンドポイントを指定するだけでよい。

[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"

テーブル名の notion の部分が Codex 内でのサーバー識別子になる。複数の MCP サーバーを併用する場合は、それぞれ別名のテーブルを並べて書けばよい。コマンドラインから追加したい場合は codex mcp add <名前> -- <コマンド> の形式が用意されており、登録済みサーバーは codex mcp list で一覧できる。

Step 3: ブラウザでアクセスを認可する

設定を保存したら、ターミナルで codex を起動してセッションを開始する。続けて /mcp と入力すると、登録済みの MCP サーバーが一覧表示される。Notion サーバーを選ぶと、ワークスペースへのアクセスを許可するためのブラウザ用 URL が表示されるので、それを開いて Notion にログインし、認可を完了させる。この認可は利用者単位で行われ、Codex に対してどのワークスペースを見せるかをここで決める。Notion のホスト型 MCP は固定トークンによる接続には対応しておらず、このブラウザでの認可フローが前提となっている。

Step 4: /mcp で疎通を確認する

認可後、再び /mcp を実行すると、Notion サーバーが利用可能なツールとともに表示される。ここでツール名が見えていれば接続は成功だ。試しに「Notion から『開発タスク』という名前のページを検索して、見出しを一覧で教えて」のように指示し、Codex が Notion のツールを呼び出してページ情報を返してくれば、読み取り経路が機能していることを確認できる。うまく表示されない場合は、url の綴りや認可の完了状態を見直す。

セルフホスト型(npm)で接続する場合

固定トークンでの接続や、スクリプトで再現できる構成を優先したいときは、セルフホスト型を選ぶ。この方式では、Notion 側で作成したインテグレーショントークンを環境変数として Codex に渡し、ローカルで起動した MCP サーバーと STDIO でやり取りする。

設定ファイルには、command に起動コマンド、args に引数、env にトークンを記述する。STDIO 方式の最小構成は次のようになる。

[mcp_servers.notion]
command = "npx"
args = ["-y", "@notionhq/notion-mcp-server"]
env = { "NOTION_TOKEN" = "<Notion のインテグレーショントークン>" }

ここで指定する NOTION_TOKEN は、Notion の連携設定で発行したトークンに置き換える。トークンは権限の強い接続情報なので、設定ファイルをそのまま公開リポジトリへコミットしないよう注意し、必要に応じて環境変数経由で渡す運用にする。トークンを渡したインテグレーションが、対象のページやデータベースに対して「接続済み」になっているかも Notion 側で確認しておく。共有されていないページは、トークンが有効でも Codex からは見えない。

セルフホスト型は Notion 側のメンテナンス方針の影響を受けるため、ツールの挙動が想定と異なる場合は、ホスト型での接続に切り替えて切り分けると原因を特定しやすい。パッケージの最新の状態は公式リポジトリ(https://github.com/makenotion/notion-mcp-server)で確認できる。

連携時の注意点とトラブルシュート

Notion と Codex の連携は便利だが、外部サービスへの読み書き権限を AI エージェントへ渡すことになるため、運用面でいくつか押さえておきたい点がある。導入前にここを設計しておくと、後から事故を防ぎやすい。

第一に、編集権限の渡しすぎに注意する。Codex に書き込み可能な接続を与えると、指示の解釈次第では既存ページを上書きしたり、意図しない更新を行ったりするリスクがある。重要なドキュメントを扱う場合は、まず閲覧中心の接続から始め、書き込みが必要になった段階で範囲を広げるのが安全だ。Codex には承認モード(ツール実行前に確認を挟む設定)があり、approval_mode 系の設定でツール単位の確認を有効にできる。破壊的な操作を含むツールには確認を挟む構成にしておくとよい。

第二に、接続するページ・データベースの範囲を絞る。Notion 側で MCP に共有するコンテンツを限定すれば、Codex から見える情報をその範囲に閉じられる。ワークスペース全体を渡すのではなく、開発に必要なページだけを共有する設計にすると、情報の取り扱い範囲が明確になる。

第三に、ツールが多いサーバーでの呼び出し精度を意識する。Codex CLI は 2026 年 6 月リリースの v0.142.2 で、MCP のツール検索をデフォルトで使う挙動へ変更された(出典: https://github.com/openai/codex/releases/tag/rust-v0.142.2)。これにより、多数のツールを公開するサーバーでも、Codex が必要なツールを探し出して呼び出しやすくなっている。それでも目的のツールが使われないときは、指示の中で「Notion のページを検索して」のように操作を具体的に書くと、意図したツールが選ばれやすい。設定ファイル側で enabled_tools や disabled_tools を使い、使うツールを明示的に絞り込む方法も有効だ。

接続そのものがうまくいかない場合は、まず /mcp でサーバーがツール付きで表示されるかを確認する。表示されないときは、ホスト型なら認可の完了状態と url を、セルフホスト型なら command の実行可否とトークンの有効性を順に切り分ける。Codex 側の MCP 仕様は更新が続いているため、想定どおり動かないときは OpenAI の開発者ドキュメント(https://developers.openai.com/codex/mcp)で最新の設定項目を照合するのが近道だ。

まとめ

Codex から Notion を扱うには、MCP サーバーを ~/.codex/config.toml に登録するのが基本だ。手軽に始めたいなら、Notion 公式のホスト型リモートサーバー https://mcp.notion.com/mcp を url で登録し、ブラウザで認可するだけでよい。固定トークンや旧 API を使いたい場合は、@notionhq/notion-mcp-server をローカル起動するセルフホスト型を選ぶ。どちらの方式でも、/mcp でツールの表示を確認すれば疎通の可否を判断できる。

連携が機能すると、Notion に集約した仕様・タスク・議事録を Codex が直接読み取り、実装へ反映し、結果を書き戻すところまで一気通貫で頼めるようになる。一方で、編集権限の付与は破壊的変更を許すことでもあるため、共有範囲を絞り、承認モードで確認を挟む設計が欠かせない。まずは閲覧用途の接続から試し、運用に慣れてから書き込みへ広げていく進め方が、Notion と Codex を安全に組み合わせる現実的な道筋になる。Codex の最新情報は OpenAI 公式(https://openai.com/ja-JP/codex/)で確認できる。