What stood out to me is that this article is really about judgment, not mapping. The schema conversions themselves are straightforward once you’ve built adapters for APIs before. The hard part is deciding what should be exposed to the model at all, and the piece is strongest when it stops pretending every HTTP field deserves equal status.
That’s the bit I’d actually pay attention to if I were wiring Claude to a real API. Path parameters are boring and obvious: keep them explicit, don’t mush three nested IDs into one vague id, and make the tool name reflect the action instead of the route. That all sounds basic, but in practice people get lazy and hand the model a messy blob because it is faster. Then they wonder why the agent starts making brittle calls.
I also think the header section is more interesting than the body section, because it forces a clean distinction between business inputs and transport concerns. Authentication absolutely should not be model-visible. The article says that plainly, and I agree. If your tool schema is asking the model for a bearer token, you’ve already broken the abstraction. The same goes for most operational headers: some should be generated by the server, some translated into friendlier fields, and some ignored altogether. That part is less “convert OpenAPI to MCP” and more “don’t leak your protocol into the user experience.”
Where I’m a little less convinced is the confident tone around “one clear input schema.” In real systems, a lot of APIs aren’t as tidy as the example. Query parameters can overlap with body fields. Headers can affect semantics in weird ways. Partial updates can be schema-validated differently from full updates. The article’s example is clean enough to teach the pattern, but I wouldn’t want someone to read it and think every endpoint can be flattened without tradeoffs. Sometimes the adapter should be opinionated; sometimes it should be strict and expose the awkwardness. That depends on how much you trust the agent versus how much damage a bad call can do.
Still, the piece gets something important right: MCP tooling is not just an exercise in serialization. It is a product decision about what the AI should see, what humans should have to think about, and what should stay hidden behind the runtime. That’s the layer where most of the real design work lives. The JSON is the easy part.
Reference: Mapping API Path, Query, Header, and Body Parameters to MCP Tool Schemas
