Notion MCPをClaude Codeに接続して仕様書を読ませる

Notionに書いた仕様書は、Claude Codeから直接読ませられる。claude mcp addで登録してブラウザ認証を通すだけで、チャットに内容を貼り直す作業がなくなる。

繋ぐと仕様書を貼らずに実装まで依頼できる

「Notionの仕様書に沿ってログイン機能のバリデーションを実装して」「この画面仕様とテーブル定義に差異がないか確認して」といった依頼が、仕様を貼り付けずに一度で通る。突き合わせを目視でやらずに済むので確認漏れが減る。

読み取りだけでなく書き込みもできる。議事録やタスク管理DBを参照させて「先週決まった方針をコードに反映して」と頼む、調査結果をページに書き戻して記録させる、といった使い方になる。

claude mcp addでNotionを登録する

ターミナルで次を実行する。このURLはClaude Code公式ドキュメントにNotionの例として載っているものと同じだ。

claude mcp add --transport http notion https://mcp.notion.com/mcp

成功するとAdded ...と出る。これは設定ファイルに書けたという意味で、接続や認証が済んだ合図ではない。

/mcpからブラウザ認証を通す

追加直後のclaude mcp listは! Needs authenticationを返す。サーバーには到達できていてOAuthのサインインだけが未了なので、ここで設定を疑わなくてよい。

セッション内で/mcpを実行し、notionを選んでEnter、続けてAuthenticateを選ぶ。ブラウザでNotionにサインインして対象ワークスペースへの接続を許可すると✔ Connectedに変わる。

繋がったかは表示だけで判断しない。「Notionの仕様書からログイン機能の要件を教えて」と依頼し、ツール呼び出しにnotionが出るかを見る。出ていなければNotionを読まずに一般知識で答えている。

接続が切れたらclaude mcp listの表示で切り分ける

切れた直後に手を動かすのは早い。HTTPサーバーが途中で切断された場合、Claude Codeは1秒から倍々に延ばすバックオフで最大5回まで自動再接続する。その間は/mcpでpendingと出るので、少し待ってclaude mcp listを叩き直す。5回失敗してfailedになってから手動で再接続すればよい。

Notionでは切断そのものも報告がある。VSCode拡張でコネクタが日次で切れる件（issue #82246）と、OAuthトークンの更新が保持されない件（issue #28256）だ。頻発するなら設定の書き方より先に、Claude Codeを最新版へ更新して再現を見る。

MCPサーバーは繋ぎっぱなしを前提に絞る

接続したサーバーは、ツール名と説明文がセッションごとにコンテキストウィンドウを消費する。使うたびに付け外しするのは現実的でないので、繋ぎっぱなしを前提に数を絞るほうが運用に乗る。

案件ごとに使うものが違うなら、プロジェクト単位の設定ファイルに書けばよい。そのディレクトリで作業するときだけ有効になり、全案件ぶんを常に抱えなくて済む。