Most AI APIs Break When Agents Call Them
The core insight: agents call APIs differently than humans do. They omit optional parameters. They expect precise error messages. They need operations that preserve state across multi-step workflows.
Building MCP support meant solving for how agents actually behave, not just publishing an OpenAPI spec.
Design Constraint: Avoiding Full Document Regeneration
The first architectural decision was avoiding naive full-document regeneration on every edit.
In practice, agent-driven workflows require scoped, state-aware edits, not rewriting entire documents from scratch on every request. Full regeneration breaks trust, overwrites human changes, and makes long-running documents impossible to maintain.
Waldium treats documents as persistent, structured objects with:
Stable identity across sessions Explicit revision history Stateful publishing lifecycle (draft → unlisted → published)
MCP operations map directly onto these primitives. When an agent calls WALDIUM_UPDATE_POST, it's applying a targeted edit to a known document version, not regenerating from a prompt.
This allows agents operating from external tools to work safely against real document state without losing context or drifting over time. MCP is not a separate execution path, it's an interface into the same document system that powers the editor.
What We Fixed by Actually Using It
We built Waldium's MCP integration by using it in Cursor and Claude Desktop. That meant hitting real integration failures and fixing them:
Schema validation breaking on optional parameters MCP clients often omit optional fields. Our initial implementation was converting undefined to null, but Zod's .optional() only accepts undefined. We updated the route to pass through undefined naturally so agents can call endpoints without specifying every parameter.
Authentication requiring manual token formatting The original OpenAPI schema used type: 'apiKey', forcing users to manually prefix API keys with "Bearer". This caused failures in Gram and Cursor. We switched to HTTP Bearer authentication, which handles token formatting automatically and aligns with OpenAPI best practices.
The result: MCP tools that work the way agents actually call them, not just in idealized API specs.
How It Works
Here's what a typical MCP-driven content workflow looks like in practice:
Agent workflow in Cursor:
Why We Built This
As agentic workflows mature, the bottleneck is no longer generation, it's where agents are allowed to operate.
If content only exists behind a UI boundary, agents can't:
Maintain state across sessions Make precise, scoped edits Integrate into real development workflows Operate on structured knowledge sources By exposing Waldium through MCP, we're treating content infrastructure the same way modern teams treat internal APIs: composable, addressable, and automation-friendly.
This is a step toward content systems that evolve alongside codebases, instead of separately from them.
Available Tools
Full MCP toolset: WALDIUM_GENERATE_POST, WALDIUM_BATCH_CREATE_POSTS, WALDIUM_CREATE_KNOWLEDGE, WALDIUM_UPDATE_POST_STATUS, WALDIUM_GET_POST, WALDIUM_DELETE_POST, WALDIUM_CREATE_GEO_REPORT, and more.
Server URL: https://mcp.waldium.com/mcp/waldium-mcp
Best, Amrutha
