Notes from the Field: When to Stop Debugging and Switch to MCP

This is an abstract of a Chinese-language Synapse case study. While migrating PMO data into Notion, my Python script kept hitting object_not_found errors. The Notion Integration Token model requires every page and database to be explicitly shared with the integration — there is no recursive permission inheritance, so each of 40 dynamically created sub-pages needed manual UI authorization. Instead of building yet another half-automated workaround, I switched to Claude’s Notion MCP integration, which uses OAuth-based user-identity inheritance. The full Chinese article walks through the auth-model mismatch, the decision rule I now apply (“if debug time exceeds rewrite time × 1.5, reconsider the approach”), and the engineering trade-offs of MCP vs. raw API.

Key Takeaways

• Auth-model mismatch is a re-architect signal, not a debug task: Integration Tokens use resource-level allowlists (default deny). MCP OAuth uses user-level inheritance (default allow). For personal/internal automation, the user-identity model is the natural permission boundary; Integration tokens are over-engineering imported from third-party-app design.
• A 200-line Python script became one prompt: targeting notion-create-pages via MCP, the control point shifts from API call sequencing to natural-language intent declaration.
• Error handling moves up a layer: rate limits, transient failures, schema drift — Claude handles these via tool-call retries without try/except boilerplate. You’re outsourcing low-value integration plumbing to platform-native capabilities.
• MCP is not a silver bullet: throughput is lower than raw scripts, and strict-idempotency scenarios (financial reconciliation) still need code. MCP wins when the task is non-high-frequency, the platform offers an MCP/SDK integration, and user-identity matches the actual permission model.

Why This Matters

Most engineers default to “make it work” rather than “should this work this way.” A 30-minute permission battle often hides a deeper architectural mismatch — and grinding through it just delays the inevitable rewrite. The Synapse approach treats MCP-vs-script as a real architectural decision with explicit criteria, not a fallback. Every permission you bypass returns later as a security audit finding, a maintenance burden, or a confused colleague reading your code. The Chinese article’s three-question decision framework is now part of our internal “stop and switch” SOP.

---

This is an abstract. Read the full article in Chinese → 当脚本撞墙：用 Notion MCP 替代本地 API 脚本