"APIs to Capabilities
Enterprises have invested 10-15+ years into exposing enterprise capabilities (internal and external) with APIs. That is not going away. MCP, as exciting as it is, is really just a simple protocol shim for AI models to call tools. But to expose the tools correctly to the model, we need to describe capabilities not just API contract structure:
- tool names should be unique, action oriented (e.g., “listAllTodoTasks” vs just “list”)
- include detailed purpose explanations
- give examples of when to call with example requests/responses
preconditions for using the tool
Using OpenAPI Spec
The OpenAPI Specification contains a number of fields and structures to support adding rich semantic meaning to our APIs:
-Using the info section
- A number of sections offer the ability to link out to externalDocs
- Most sections provide a title, summary, and description field
- You can link out to industry accepted (or enterprise specific) data fields using JSON-LD for very deep semantic meaning
- If none of these are adequate, you can extend the spec with “x-properties”
Let’s take a quick look at an example."
https://blog.christianposta.com/semantics-matter-exposing-openapi-as-mcp-tools/
#APIs #APIDesign #APIDevelopment #OpenAPI #MCP #LLMs #Metadata #AI #GenerativeAI #AIAgents