Need MCP Documentation
The assumption that AI will figure out how to use MCP servers is wrong, and traditional documentation and discovery are still required.
Take Control Of Your Signals — Become a Naftiko Design Partner Today!
Persona Story:
Pat, the head of platforms, is discovering that the assumption “AI will figure out how to use MCP servers” is wrong, and traditional documentation and discovery are still required.
Problem Context
- Industry assumption: “You don’t need MCP documentation because AI/copilot will figure it out in the IDE”
- Reality: Without agentic workflows fully working, teams need to know “what are our resources? what do we do?”
- Discovery, documentation, virtualization—all the things done for REST APIs—are “on the table” for MCP too
Problem Impact
- MCP servers deployed without adequate documentation for human or AI consumption
- Developers can’t evaluate whether an MCP server meets their needs without trial and error
- Technical debt accumulates as undocumented MCP servers proliferate
Naftiko Today
- YAML capability specs serve as both documentation and executable runtime – the spec IS the documentation, eliminating drift
- Agent Skills exposure auto-generates HTTP APIs for skill discovery and download, providing machine-readable MCP documentation out of the box
- REST API exposure with full HTTP semantics documents resources and operations alongside MCP tool definitions
- JSON Schema validation ensures every capability spec is structurally complete, preventing undocumented MCP tools from being deployed
Naftiko Tomorrow
- Backstage capability template scaffolding (Fleet Second Alpha) would enforce documentation completeness at creation time via web UI
- HTML/Markdown format support (Second Alpha) would enable rich documentation output alongside MCP tool responses
- TechDocs integration (Fleet First Beta) would auto-publish capability documentation into the organization’s developer portal
- Fabric capability discovery (v1.1) would provide a searchable registry of all MCP capabilities and their documentation