I had some great conversations this last week about the evolution of documentation as part of the MCP evolution in the API conversation. Alongside these conversations I have been diving into recent releases from leading tech companies when it comes to doubling down on MCP and AI integration, and meeting developers where they work when it comes documentation and other resources.
Documentation
Documentation is central to any API, and it is equally important to MCP. There is a lot of open discussion right now about what documentation is needed when it comes to AI integration. I am more focused generally on what documentation means in the first place, as well as what it means when it comes to AI integration, and specifically meeting developers where they are while also delivering guidance when it comes to producing and consuming APIs.
OpenAPI
When I document an API, I produce an OpenAPI. But I do not think that many other people see it that way. An OpenAPI documents the surface area of an API. From there you can generate HTML or Markdown documentation for users, but you can also generate MCP, Skills, and other client derivatives like Postman or Bruno Collections. Robust and complete OpenAPI are required for REST, MCP, and other types of APIs.
Markdown
As I dove into at the intersection of API and MCP documentation I noticed the proliferation of export and download as Markdown options for API and tooling documentation. I like the usage of Markdown, and I think it should be a generated derivative of other standards, but it is a belief I am challenging as I move forward with a spec-driven approach to how different artifacts can be used to produce and consume APIs for any type of integration.
Resources
Another way in which the concept of documentation becomes fuzzy is when it comes to the other resources offered alongside the documentation of the surface area of an API. I track on the many different properties of what API producers generally label as documentation, resources, and other elements of how we integrate APIs into a variety of applications, including the increasing copilot and agentic integrations with APIs.
Microsoft Learn MCP Server
One of the first places I began thinking about the shift in documentation with MCP was Microsoft announcing that they were routing all of their training via MCP. Microsoft provides a documentation search, fetch, as well as moving into the area of other resources with a code sample search. Microsoft’s approach is a pretty broad approach to making documentation available via copilots and agentic integrations, but provides a compelling look at where companies are going.
Google Developer Knowledge MCP
After Microsoft, I noticed that Google did the same thing with their Developer Knowledge API, and published an MCP server for their documentation. Like Microsoft they offer a search documents, get documents, and a batch get documents tools via their Developer Knowledge MCP. It is another broad approach to making documentation available via copilots and agentic integrations, with another big company nod to where things are headed.
Amazon Web Services MCP Documentation
Next up, Amazon Web Services. They take a similar approach as Microsoft and Google, Amazon puts everything into their MCP server for their knowledge. Putting API docs, what’s new, getting started, blog posts, architectural references, guidance, troubleshooting, CDK, CLI, and even CloudFormation templates. Sounds like everything you need to integrate AWS infrastructure into copilots and agentic activity, but also sounds like a pretty broad approach.
Cloudflare Documentation MCP
After Microsoft, Google, and Amazon, I was pleased to see Cloudflare’s approach. They are taking a much more modular and domain-driven approach to publishing their operational level MCP servers. This list of Cloudflare MCP servers provide a pretty compelling look at what is possible when it comes to translating the properties of our operations into what we need to produce and consume APIs.
Documentation Server - Get up to date reference information on Cloudflare.
Workers Bindings Server - Build Workers applications with storage, AI, and compute primitives.
Workers Builds Server - Get insights and manage your Cloudflare Workers Builds.
Observability Server - Debug and get insight into your application's logs and analytics
Radar Server - Get global Internet traffic insights, trends, URL scans, and other utilities.
Container Server - Spin up a sandbox development environment.
Browser rendering Server - Fetch web pages, convert them to markdown and take screenshots.
Logpush Server - Get quick summaries for Logpush job health.
AI Gateway Server - Search your logs, get details about the prompts and responses.
AI Search Server - List and search documents on your AI Searches.
Audit Logs Server - Query audit logs and generate reports for review.
DNS Analytics Server - Optimize DNS performance and debug issues based on current set up.
Digital Experience Monitoring Server - Get quick insight on critical applications for your organization.
Cloudflare One CASB Server - Quickly identify any security misconfigurations for SaaS applications to safeguard users & data.
GraphQL Server - Get analytics data using Cloudflare's GraphQL API.
Agents SDK Documentation Server - Token-efficient search of the Cloudflare Agents SDK documentation.
I imagine all of the common properties I track on as part of APIs.json available as modular MCP servers. In my opinion, you should be able to layer operational level documentation as part of your Ai Integration, engineering exactly the context window you need, providing the guidance teams need to get their work done.
Model Context Protocol Servers
Another dimension of this conversation I wanted to understand the separation of concerns at the protocol level. It looks like generally this documentation and other resources are being bundled as tools, where the protocol offers a pretty nuanced separation between tools, resources, and prompts. To be able to do this you would need to have your APIs, and their resources, including associated prompts managed in a composable way.
Tools - Functions that your LLM can actively call, and decides when to use them based on user requests. Tools can write to databases, call external APIs, modify files, or trigger other logic.
Resources - Passive data sources that provide read-only access to information for context, such as file contents, database schemas, or API documentation. Retrieve documents
Prompts - Pre-built instruction templates that tell the model to work with specific tools and resources.
Next I will evaluate Microft’s, Google, Amazon, and Cloudflare’s usage of the protocol and how they organize their tools, resources, and prompts. I will also look to see how different OpenAPI to MCP generators translate OpenAPI properties across tools, resources, and prompts. I see an opportunity for APIs.json to lead when it comes to tagging and organizing the context window needed to for delivering documentation.
Context
This is where we begin getting at more of the context needed to integrate with AI. Most of the context delivered via MCP seems to be focused on the core resource, and not the operational level stuff. When the whole package is what is required. I see an opportunity for domain alignment. I see APIs.json, OpenAPI, AsyncAPI, and JSON Schema behind these MCP servers, providing a source of composable truth that can be used in different ways to provide guidance needed via AI copilots and agents.
Skills
This week’s newsletter is focused on MCP. Next week I will likely cover Skills in the same way. I see Agent Skills as another derivative of this spec-driven bundle. The trick is how you manage the source and all of the derivatives. Like with MCP, I am looking at how leading providers are publishing and sharing their skills, with an emphasis on the operational side of things. I am most interested in supporting the intersection of AI integration with ah spec-driven approach.
Guidance
I see an opportunity to provide guidance and guardrails for developers using MCP and Agent Skills—using both to shape the context window of AI integrations. While the flattened and tactical nature of Agent Skills, as well as the overloading of the MCP context window both worry me, I think there is a new opportunity to introduce snackable, usable, and guidable documentation and other resources intelligently into the existing workflows of developers.
Governance
All of this leads back to governance for me. As my email newsletter says, API governance is just guidance. This is why I am intersted in operational level MCP servers and Agent skills. I see the Lego building blocks of API governance. I see a composable layer of policies and rules that can be used to govern the generation of derivatives like MCP, Agent Skills, Bruno Collections, or whatever is needed to govern a spec-driven approach to producing and consuming APIs using a GitOps mindset.
“Document your dreams. Sketch that shape you saw. Write those lyrics before they fade out.” ― Michael Bassey Johnson, The Oneironaut’s Diary
