Notionのホスト型MCPサーバーの開発ストーリー

2024年11月にAnthropicが発表したモデルコンテキストプロトコル (MCP) は、ツールを発見し、相互作用するための共通言語で、テクノロジー企業と開発者を連携させるという、シンプルながらも力強いビジョンを持っていました。

MCPは、長年Web APIを支援してきたRESTなどの従来の概念を超える発想を採用しています。MCPは、大規模言語モデル (LLM) にコンテキストを提供し、Notion、Figma、Stripeなどのプロバイダーが提供する各ツールをいつ、どのように使用すべきかを判断できるようにするプロトコルです。従来のAPIインテグレーションを構築するために技術文書を組み立てる通常のプロセスを省略し、ユーザーは対話やワークフローの一部として自然言語を使用してシステムと連携できます。

CursorとClaude CodeはMCP クライアント、つまりLLMの「フロントエンド」であり、エンドユーザー向けのエージェントとして機能します。これらのフロントエンドは、自然言語によるリクエストを、さまざまなサービスプロバイダー（MCPサーバー）が提供するアクションへの呼び出し（ツール）に変換します。Notion、Stripe、Figmaなどがその実用例です。

今年始めになって、NotionはMCPサーバーについてのお問い合わせを受けるようになりました。AIを優先したワークフローをナレッジワークや製品開発プロセスに導入している大規模なエンタープライズからのお問い合わせや、Notionへのデータ移行や、CursorやClaude Desktopなどの使い慣れたLLMツールやワークスペースを操作できる簡単なソリューションを必要としている、ツール作成者、開発者、Notionアンバサダーの方々からのお問い合わせでした。

初期の概念実証の目的は、Notionの既存のAPI機能をAIで呼び出すアクションとして提供することと、「ツール」モデルによるエージェントワークフローの生産性向上の実証でした。

4月上旬に、ダウンロード可能なnotion-mcp-serverを初回リリースしました。このバージョンは、CursorまたはClaude Desktopにインストール可能でしたが、技術的な知識が必要でした。設定には新しいNotion APIインテグレーションの作成と、APIキーをMCPヘッダーにコピーするか、Dockerイメージを構築するかのいずれかの作業が必要でした。設定が完了すると、AIエージェントのチャットでNotionにページを作成するなどのフローが実行可能になります。

バックグラウンドでは、ライブラリでNotionのパブリックOpenAPI仕様、つまり利用可能なAPIエンドポイントとそのインターフェースの正式な記述を解析していました。この仕様ファイルを処理することによって、設定済みのAPIキーを使用して、MCPツールの呼び出しをNotionのパブリックAPIへのHTTP API呼び出しに変換し、各APIエンドポイントでは、サーバーのMCPツールに1対1でマッピングしていました。また、MCPサーバーはMCPクライアントからリクエストを受け取り、ダウンロード用にパーソナライズされたAPI呼び出しに変換していました。

実装は困難で機能も制限されていましたが、私たちはユーザーに早急に提供したいと考えていました。早期に実装したユーザーからのフィードバックでは、2つの重要な点が明らかになりました。1つめは、技術的な障壁が高く普及が難しいこと、2つめは、1対1のAPIマッピングでは、JSONの階層型ブロックデータを処理する際にコンテキスト依存の高いトークン消費が発生するなど、AIエージェントのパフォーマンスが理想的ではないことです。

こうした教訓を次のバージョン開発に反映しました。既存と新規のツールを組み合わせた強力な機能によって、誰でも簡単に使えるように改善し、Notionのコネクテッドワークスペースとしての価値を進化させたのです。Notionの要件ドキュメントではなく、Cursorを使用するプロトタイプを採用し、タスクのステータスをリアルタイムで更新しながらプロジェクト関係者に共有する際に、すべての作業をコードエディタで行うことができるようになりました。

重要なポイントは、AIエージェントツールがNotionワークスペースにシームレスに統合され、より直感的にエージェントを利用できるようになったことです。具体的には次のような利点があります。

• Notionは既存のコードベースと社内ツールを使用し、迅速な開発ループが可能な独自のMCPサーバーをホストしています。ユーザーに更新パッケージをダウンロードしてもらう必要がないため、改善した機能を迅速に提供することができます。

• AIエージェント用に最適化された、カスタマイズされたツール群を公開する単一の中央集約型インテグレーションを作成します。APIに対してHTTPリクエストは行いません。従来のRESTful Web APIを省略し、LLMに対応した記述の「プライベートな」機能スライスをMCPサーバー経由でのみアクセス可能にして、快適にエージェントを利用できます。

このようにして、各ユーザーは「ワンクリック」のOAuth認証フローを経由して、同じパブリックインテグレーションに安全に接続できるようになります。ここでは認証フローをワークスペースに実装し、共有するページやデータベースを決定します。

接続に成功すると、使用していたツール（Cursorなど）にフローがリダイレクトして返送されます。NotionのMCPサーバーはセッションを管理し、OAuthのトークン交換で取得したAPIトークンを安全に保存して、ツール呼び出しの際にNotionのパブリックAPIで認証を行います。

Cursorのエンジニアチームと緊密に連携し、ストリーム可能なHTTPを使用することで、OAuthに快適に接続するための最適化を推進しました。また、MCPに推奨されるもう1つの主要なトランスポートプロトコルであるSSE（サーバー送信イベント）にも対応し、より多くのクライアントとの互換性を確保しています。

技術スタックやホスティング以外にも、提供するAIツールを決定する必要がありました。Notionのアプローチは、アプリ内のNotionエージェントを開発するチームと協力し、既存の/v1/ APIエンドポイントではなく、AIに最適化したツールを優先的に公開することです。

MCPツールを構築するために、2種類のツールを高度なレベルで組み合わせました。

• 1つ目は、Notionのエージェント指向のツールです。たとえば、create-pageとupdate-pageは、既存のCreate & Update Page APIを大幅に書き直した新しいツールで、従来の厳格なWeb APIよりもAIエージェントの対話により適したインターフェースを提供します。

  • NotionスタイルのMarkdown記法をベースにして構築されています。ツールの記述や回答は、バックエンドインテグレーション向けの決定論的で構造化されたJSONではなく、エージェント型ワークフローに合わせて最適化されています。

  • Markdown記法はLLMトークンあたりのコンテンツ密度を効率化し、一般的なユースケースでは、オープンソースのMCPサーバーよりもツールとのインタラクションやコストを削減できます。

  • searchツールも同様の例です。既存のv1検索APIを公開し、シンプルなユースケースやNotion AIを有効にしていないアカウントに対応しました。ただし、メインのsearchツールは、質問によるセマンティック検索に対応しており、Notionワークスペース内のページだけではなく、10種類以上のサードパーティ接続アプリも対象にできます！

• 2つ目は、既存のAPIツールです。オープンソースのMCPサーバーの成功例を参考にし、既存のv1 APIをラップするMCPツールを追加することで、機能の不足を補っていました。

  • たとえば、create-commentツールのv1 API機能に、オープンソースパッケージの不足部分を補足するAI対応のツール記述を追加していました。

  • これらのプロンプトでは、MCPクライアントに各ツールの使用タイミングと使用方法を指示します。

このようなツールを組み合わせた戦略では、広範な機能を提供しながらも、チャットウィンドウで各ツールを呼び出す際に、NotionのURLやIDなどの詳細情報をシームレスに機能させることができます。

Notion MCPのベータ版では、ページコンテンツの新しい表現方法を試し、AIエージェントでさらに作成、編集、表示しやすくすることができました。Notionの幅広いブロックセットに合わせた強力なマークアップ言語である、強化された「Notion方式」のMarkdown記法の仕様を率先して開発しました。

私たちのブログを長くご覧になっているユーザーなら、Notion APIの構築に関する2022年のブログ記事を覚えていらっしゃるかもしれません。ただし、当時はMarkdownではなくJSONを採用していました。これは、リッチテキストの色付けやデータベース、CommonMark Markdownでは表現できないNotion独自の編集機能など、より表現力豊かな機能を実現するためでした。

それから3年が経過し、階層的なJSON形式ではブロックの子要素を処理する際に、複数のAPIリクエストの実施は困難だと報告されるようになりました。そこで、Notionブロックでの機能パリティを実現するためにMarkdown記法を再び採用し、このアプローチをNotionのリモートMCPサーバーに限定して試験的に始めました。

Notion方式のMarkdown記法の仕様を簡単にご紹介します。

コールアウト

複数の列構成

ページ

データベース

詳細については、MCPサーバー経由で提供されているツールの記述をご確認ください。実際には、AIエージェントにNotion方式のMarkdown仕様を要約するように、チャットで依頼することもできます！その必要がなければ実装の詳細はNotionにまかせて、ページに追加または編集する内容を自然言語で記述してください。LLMが自動的に変換します。

今回のローンチは、AIを活用したナレッジワークの究極のハブとしてNotionを進化させるという、Notionの取り組みの始まりにすぎません。MCPの機能拡張を継続する中で、技術的な専門知識の有無に関わらず、最も注力すべき点として、あらゆるユーザーが強力なツールを利用できるようにしていきます。

また、Cursorや他のチームと協力し、信頼できるMCPサーバーやクライアントのマーケットプレイス、サーバー発見プロトコルなど、発見しやすく、安全で、信頼性の高いMCPに改善する新しい規約を率先して策定していきます。

Notion MCPで皆さんがどのようなプロジェクトを構築するか、楽しみにしています！プロジェクトを作成したら、ぜひ@NotionHQをメンションしてご共有ください。