はじめに

2026年9月17日、Notion MCP（Model Context Protocol）の検索関連ツールにまとまったアップデートが入りました。今回の変更は3件ありますが、特に注目すべきは notion-search / notion-ai-search のエラー挙動が変わった破壊的変更（severity: high） です。

これまでワークスペースのプランで対応していないフィルタやソートを指定した場合、API は validation_error を返して呼び出しそのものを失敗させていました。しかし変更後は、エラーを返さずに対応可能な範囲まで縮小して検索を実行する挙動に変わりました。

これは一見「親切な改善」に見えますが、validation_error を握ってリトライやフォールバック処理を実装している既存の統合コードにとっては、エラーが発生しないままユーザーの意図と異なる結果が返ってくるという静かな罠になります。

あわせて、プラン別のツール利用可否を事前に確認できる notion-get-tool-access ツールと、notion-ai-search でのユーザー検索（query_type パラメータ）も追加されました。本記事ではこの3点を整理し、実務でどう対応すべきかをまとめます。

📌 影響を受ける人

Notion MCP を使って検索機能を組み込んでいるエージェント/アプリの開発者

notion-search / notion-ai-search のエラーハンドリングで validation_error を前提に分岐しているコードを持つ人

複数プラン（Free/Plus/Business/Enterprise相当）のワークスペースを横断的にサポートする統合を作っている人

変更の全体像

3つの変更の関係性を図にすると以下のようになります。notion-get-tool-access が「事前確認」の役割を担い、実際の検索は notion-search / notion-ai-search が担当します。

破壊的変更（change-002）で挙動が変わった部分を、リクエストの流れとして示すとこうなります。

変更内容

ID	種別	Severity	対応要否	概要
change-001	新機能	medium	要対応	`notion-get-tool-access` でツール/パラメータ単位の利用可否を事前確認できる
change-002	破壊的変更	high	要対応	非対応フィルタ/ソート指定時、エラーではなく縮小実行 + `notices` 通知に変更
change-003	新機能	medium	対応不要	`notion-ai-search` に `query_type` を追加、ユーザー検索が可能に

change-001: `notion-get-tool-access`（事前確認ツール）

引数なし（{}）で呼ぶと、接続スコープ内の全ツールの利用可否マップ（current_tool_access）を返す
tool_names: ["search", "ai_search"] のように対象を絞ることも可能
状態を変更しない読み取り専用ツール（アクセス権の付与やワークスペース状態の変更は行わない）
マップの各エントリに restricted_parameters が新設され、filters.title_only のようなパラメータパス単位で「なぜ使えないか」を返す
status: available でも、パラメータ単位ではさらに制限されているケースがある点に注意
ai_search が利用可能な場合、マップから search は除外される（名前指定でも省略される）。逆に、選択されたツール構成によっては search（利用可）と ai_search（利用不可）が両方存在することもある

change-002: 検索ツールのエラー挙動変更（破壊的変更）

⚠️ Breaking Change
validation_error を前提にエラーハンドリングしている既存コードは、想定通りに動かなくなる可能性があります。

非対応のフィルタ/ソートは除去した上で検索を実行し、レスポンスの notices 配列に除去されたフィールド名を通知（可能ならアップグレードリンクも含む）
結果は要求より広い範囲になることがあり、関連度ソートが使われる場合もある
複数チームスペース検索非対応プランで teamspace_id と filters.teamspace_ids に異なるチームスペースを指定すると、両方とも除去される
除去後にクエリが空かつ有効な制約が残らない場合 → 結果0件 + 「非空クエリまたは対応フィルタを求める」notice
AIアクセスがないプランで notion-ai-search のコンテンツ検索を行うと、従来のアップグレードエラーではなく Notion内キーワード検索にフォールバック（type は "ai_search" のまま維持、notices で「接続ソースは未検索」と説明）
ただし未払い請求などの課金制限があるワークスペースでは、引き続き権限エラーとなる

change-003: `notion-ai-search` のユーザー検索対応

query_type: "user" を指定し、名前またはメールアドレスを渡すとワークスペースユーザーを検索できる
レスポンスは notion-search と同じ type: "user_search" を返す
query_type を省略、または "internal" にするとコンテンツ検索（従来通り）
ユーザー検索時にコンテンツ用のフィルタ/ソートを指定すると validation_error
ユーザー検索自体はAIアクセス不要だが、ユーザー情報系の capabilities は必須。ワークスペース所有のMCP接続では notion-get-users も公開されている必要があり、ツールを切り替えても権限チェックは回避できない

影響と対応

対応の判断フローはこのようになります。

最優先: validation_error の catch を前提にした分岐がある場合、レスポンスの notices 配列を見て「意図した検索が実行されたか」を判定するロジックに置き換える
検索結果を業務ロジックに直結させている場合、縮小実行された結果を「完全な結果」として扱わないよう、notices の有無をログやアラートに反映する
複数プランのワークスペースを横断的にサポートする実装では、検索前に notion-get-tool-access を呼んで restricted_parameters を確認し、UI側で該当オプションを非表示にする方が体験が良い
ユーザー検索機能を追加する場合は notion-get-users の公開設定も忘れずに確認する

💡 Tips
notion-get-tool-access は状態を変更しないツールなので、アプリ起動時やUI表示前にキャッシュ目的で呼んでおくのがおすすめです。

コード例

Before: `validation_error` に依存したエラーハンドリング

try {
  const result = await callTool("notion-search", {
    query: "",
    filters: { teamspace_ids: ["ts_a", "ts_b"] },
    sort: { field: "relevance" },
  });
  return result.results;
} catch (err) {
  if (err.type === "validation_error") {
    // 非対応オプションのため、フィルタなしで再試行していた
    return await callTool("notion-search", { query: "" }).results;
  }
  throw err;
}

この実装は変更後、エラーが発生しないため catch ブロックが呼ばれず、縮小実行された想定外の結果がそのまま result.results として返ってしまいます。

After: `notices` を見て挙動を判定する

const result = await callTool("notion-search", {
  query: "",
  filters: { teamspace_ids: ["ts_a", "ts_b"] },
  sort: { field: "relevance" },
});

if (result.notices?.length) {
  // 除去されたオプション名と、あればアップグレードリンクをログ/UIに反映
  console.warn("検索条件が一部縮小されました:", result.notices);
}

return result.results;

事前確認の組み込み例

const access = await callTool("notion-get-tool-access", {
  tool_names: ["search", "ai_search"],
});

const aiSearch = access.current_tool_access.ai_search;
if (aiSearch?.status === "available" &&
    !aiSearch.restricted_parameters?.["filters.title_only"]) {
  // title_onlyフィルタを安全に使える
}

まとめ

破壊的変更（change-002）が最重要: notion-search / notion-ai-search は非対応オプション指定時に validation_error で失敗しなくなり、縮小実行 + notices 通知に変わった。エラーハンドリングコードの見直しが必須
notion-get-tool-access（change-001） で、検索前にプラン別のツール/パラメータ制限を確認できるようになった。複数プラン対応の実装では活用したい
notion-ai-search のユーザー検索（change-003） で query_type: "user" によるユーザー検索が可能になったが、notion-get-users の権限が別途必要
全体として、Notion MCP は「エラーで止める」よりも「可能な範囲で実行し通知する」方向に挙動をシフトさせている。エージェント/統合を作る側は、レスポンスの notices を常にチェックする実装に更新することを推奨する