Notion MCPのupdate_contentタイムアウト対策、ブロック単位削除への切替設計 This article tackles timeouts in Notion MCP's update_content on large pages by switching f…
- Notion MCPのupdate_contentが大規模ページでタイムアウトする問題に対し、ページ全体を一括更新せずブロック単位で削除・再構築する設計を提案。
- 安定性と再試行性を高める実装上の工夫を解説する。
English summary
- This article tackles timeouts in Notion MCP's update_content on large pages by switching from full-page updates to block-by-block deletion and reconstruction, improving reliability and retry behavior.
Notion公式のMCPサーバを利用してページを書き換える際、update_contentがタイムアウトしてしまう現象に直面した開発者による実装上の知見を紹介する記事である。AIエージェントとNotionを連携させる文脈で、安定動作のための設計パターンとして参考になる。
記事の主題は、update_contentがページ全体に対する一括操作として動作するため、ブロック数が多いページや複雑な構造を持つページでは処理時間が長引きタイムアウトに至るという問題だ。これに対し著者は、ページ全体を置換するのではなく、既存ブロックを単位ごとに削除し、その後で新しいコンテンツを追加していくアプローチへ切り替える設計を提示している。ブロックIDを取得してdelete_block相当の操作を順次実行することで、各APIコールの粒度を細かくし、失敗時にも部分的なリトライが可能になる点が利点である。
背景として、Notion APIはもともとブロックツリー構造を扱うREST APIであり、子ブロックの取得・追加・削除といった粒度の細かい操作が標準で提供されている。MCP(Model Context Protocol)はAnthropicが提唱したエージェント向けの共通インターフェースで、Notion以外にもGitHubやSlackなど多数のサーバ実装が登場している。Claude DesktopやCursorなどのクライアントから外部ツールを呼び出す際、長時間実行される操作はタイムアウトに弱いため、操作を分解して冪等性とリトライ性を確保する設計は他のMCPサーバ利用時にも応用が利くと見られる。
Notion MCPのupdate_contentが大規模ページでタイムアウトする問題に対し、ページ全体を一括更新せずブロック単位で削除・再構築する設計を提案。
また、Notionのような階層構造を持つドキュメントサービスでは、一括更新と差分更新のトレードオフが常に課題となる。今回のようにブロック単位削除へ切り替える方式はAPIコール数が増えるためレートリミットに注意が必要だが、ユーザ体験としては「途中で止まっても再開できる」という安心感を得やすい。エージェントワークフローを実運用に乗せる際の実装パターンとして示唆に富む内容だと言える。
This article shares a practical workaround discovered by a developer who hit timeout errors when using the official Notion MCP server's update_content tool on larger pages. It is a useful read for anyone integrating AI agents with Notion and looking for reliable update patterns.
The core problem is that update_content operates as a single bulk operation against an entire page. When a page contains many blocks or a deeply nested structure, the processing time grows long enough to exceed MCP client timeout limits, leaving the update in an indeterminate state. To work around this, the author proposes abandoning the all-at-once replacement model and instead deleting existing blocks one at a time, then appending new content block by block. By fetching block IDs and issuing delete operations sequentially, each API call stays small, and partial retries become possible when something fails midway.
For context, the underlying Notion API is fundamentally a REST interface over a tree of blocks, with first-class endpoints for fetching, appending, and deleting child blocks. MCP, the Model Context Protocol introduced by Anthropic, has rapidly accumulated server implementations beyond Notion, including GitHub, Slack, and various databases. Because MCP clients such as Claude Desktop and Cursor invoke tools over a request-response channel that is sensitive to long-running operations, decomposing coarse tools into finer-grained idempotent calls is a pattern that likely generalises to many other MCP servers as well.
There is also a broader design tension worth noting. Hierarchical document services like Notion always face a trade-off between bulk updates, which are convenient but fragile, and incremental updates, which require more API calls but are easier to recover from. Switching to per-block deletion as described here increases the total request count and may bring rate limits into play, so implementers should monitor 429 responses and consider backoff. On the other hand, the user experience benefits significantly: an interrupted run can resume from where it stopped rather than forcing a full retry from scratch. As agentic workflows move from demos into production, this kind of granular, retry-friendly orchestration is likely to become a standard pattern, and the article offers a concrete example of how to think about it.
本ページの本文・要約は AI による自動生成です。正確性は元記事 (zenn.dev) をご確認ください。
