Neglected OpenAPI Specs in a World of MCP Launches
Patrick Kelly
Everyone's rushing to launch MCP servers. It seems to be what startups and big companies alike feel they need to do right now.
There's a lot of excitement surrounding MCPs (Model Context Protocol). However, there is also growing developer disappointment. One possible cause for this disappointment may be the poor quality of the OpenAPI specifications that are used as reference files in most MCP server implementations. They contain countless instances of inconsistencies and errors:
Request body and response examples that do not match their schema
Response schemas that don't describe the real API response
Authentication requirements detailed incorrectly
Missing schemas
Issues like the above create problems for developers and lead to hours wasted debugging issues in production. This is true with or without MCP.
But surely this can't be true at the top tech companies, right? Tech companies that built their entire business around developer adoption? Unfortunately, it is. The official OpenAPI specifications for GitHub, Twilio, Notion, and others revealed between 100-2,500 OpenAPI errors. Out of 20 select APIs, only the Stripe OpenAPI is logically and syntactically correct.
Here is a Python Stripe SDK generated by Sideko using Stripe's OpenAPI spec. Nice work, Stripe!
It is shocking to find basic issues like incorrect examples at these massive companies. It's less shocking to see GitHub issues piling up in MCP server repos. The CEO of Perplexity, Aravind Srinivas, has picked up on the trend:
When documentation doesn't match reality, when parameters don't work as described, when authentication fails inexplicably, developers notice. Incorrect OpenAPI specs are just one of the many shortcomings of the architecture behind MCP. Excitement will give way to the realization that most implementations don't work reliably. I've met with MCP server maintainers facing unsolvable issues that the consumers are facing. If you want to see what it's actually like to use MCP as a developer, check out this article.
In the long run, mastering the fundamentals of great API development, like accurate OpenAPI specifications, will matter far more than racing to deploy an MCP server. The infrastructure for agent-API interaction is still evolving, and there are emerging approaches beyond MCP.
Companies rushing to implement today's trendy solution may find themselves rebuilding tomorrow, especially if they've neglected the underlying foundations.Launching an MCP server feels like progress. It's something you can demo to investors or announce on Twitter. Getting your OpenAPI spec right isn't applauded online, but it will lead to long-lasting developer success down the road.
-Patrick
PS. Lint your own OpenAPI with the Sideko CLI: sideko api lint --spec ./openapi.yaml
Scale your DevEx and Simplify Integrations
Read More
Sideko Releases C# SDK Generator
Sideko's new C# SDK generator, leveraging C#'s growth (+1.43% in TIOBE), creates invisible, fully tested, strongly typed, and auto-authenticated SDKs with customizable code and complete documentation.
Can APIs Be Beautiful?
Sideko's team, with insights from Keith Casey, explores why some APIs "feel right" by connecting API design trends to art and architecture movements, aiming to articulate the concept of "beautiful" APIs.