--- title: OpenAPI Overlays for MCP and AI-Agent Enrichment | daily.dev description: OpenAPI Overlays can solve the problem of serving both human developers and AI agents from a single API spec. Rather than bloating human-facing docs with... canonical: https://daily.dev/posts/openapi-overlays-for-mcp-and-ai-agent-enrichment-tlwcd4t7t twitter:card: summary_large_image twitter:site: @dailydotdev og:type: website og:site_name: daily.dev og:title: OpenAPI Overlays for MCP and AI-Agent Enrichment | daily.dev og:description: OpenAPI Overlays can solve the problem of serving both human developers and AI agents from a single API spec. Rather than bloating human-facing docs with... og:url: https://daily.dev/posts/openapi-overlays-for-mcp-and-ai-agent-enrichment-tlwcd4t7t og:image: https://api.daily.dev/og/posts/TLWCD4t7t.png og:image:alt: OpenAPI Overlays for MCP and AI-Agent Enrichment og:image:width: 1200 og:image:height: 630 og:locale: en --- > ## Documentation Index > Fetch the complete documentation index at: https://daily.dev/llms.txt > Use this file to discover all available pages before exploring further. # OpenAPI Overlays for MCP and AI-Agent Enrichment **[API Evangelist](https://daily.dev/sources/apievangelist)** · 4 min read · 1 upvotes · 2 comments ## Summary OpenAPI Overlays can solve the problem of serving both human developers and AI agents from a single API spec. Rather than bloating human-facing docs with agent-specific disambiguation hints, you maintain a base OpenAPI contract and apply separate overlays at build time. One overlay rewrites operation descriptions in imperative language agents can act on (e.g., distinguishing PUT /products/{id} from a cancel operation). A second overlay injects vendor extensions like x-mcp-tool-name and x-agent-hint that MCP generators consume to produce deterministic, well-labeled tool definitions. The result: human docs render from the clean base spec, while the MCP surface is generated with agent-enriched overlays applied only during that build step. ## Full article daily.dev links to this article rather than hosting it. Read it at the original source: ## Questions this post answers ### How can I make my OpenAPI spec agent-friendly without cluttering the human-facing docs? Use the OpenAPI Overlay specification to layer agent-specific context on top of a single base contract instead of rewriting the spec. One overlay rewrites operation descriptions in explicit imperative language (e.g., distinguishing PUT for updates from POST cancel for permanent removal) targeted at agents, while a second overlay injects vendor extensions like x-mcp-tool-name and x-agent-hint that an MCP generator reads at build time to name tools and flag destructive operations. _daily.dev surfaces practical overlay patterns for teams building MCP-ready APIs without duplicating specs._ ### How do vendor extensions like x-mcp-tool-name help when generating an MCP tool list from OpenAPI? Vendor extensions such as x-mcp-tool-name and x-agent-hint let an MCP generator name tools deterministically and flag destructive operations, instead of mangling an operation path like post /products/{id}/cancel into an unusable auto-generated name. These x- prefixed fields pass through OpenAPI untouched and can be applied via an overlay targeted only at the MCP build step. _developers wiring up MCP servers can track patterns like this through daily.dev to avoid ad hoc tool naming._ ## Community discussion Top comments from developers on daily.dev. **@trevorsuna** · 0 upvotes > Separating agent hints from the human-facing contract keeps the base spec readable without starving generated tools of context. The tricky bit will be testing overlays as versioned build inputs so an API change cannot leave the MCP surface with stale instructions. **@agustinbarrientos** · 0 upvotes > Would you allow one overlay to override another, or fail the build when two overlays touch the same operation? ## Similar posts on daily.dev - [The Many Use Cases for OpenAPI Overlays](https://daily.dev/posts/the-many-use-cases-for-openapi-overlays-1gjpvrair) · API Evangelist · 0 upvotes · 0 comments - [Using MCP For API Documentation Discovery](https://daily.dev/posts/using-mcp-for-api-documentation-discovery-d2pyfbuyu) · Nordic APIs · 1 upvotes · 0 comments - [OpenAPI Overlays for Adding Tool-Specific Content Without Polluting the Spec](https://daily.dev/posts/openapi-overlays-for-adding-tool-specific-content-without-polluting-the-spec-np7suyu3c) · API Evangelist · 0 upvotes · 0 comments - [Why More MCP Tools Can Make an AI Agent Less Useful](https://daily.dev/posts/why-more-mcp-tools-can-make-an-ai-agent-less-useful-piqjmps6m) · Dev Genius · 3 upvotes · 1 comments - [How to Build AI Agents That Can Control Cloud Infrastructure](https://daily.dev/posts/how-to-build-ai-agents-that-can-control-cloud-infrastructure-yyzbrnqg9) · freeCodeCamp · 2 upvotes · 0 comments --- Tags: [#ai-agents](https://daily.dev/tags/ai-agents), [#architecture](https://daily.dev/tags/architecture), [#mcp](https://daily.dev/tags/mcp), [#openapi](https://daily.dev/tags/openapi) [View this post on daily.dev](https://daily.dev/posts/openapi-overlays-for-mcp-and-ai-agent-enrichment-tlwcd4t7t) ```json {"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://daily.dev/#organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180},"sameAs":["https://twitter.com/dailydotdev","https://github.com/dailydotdev","https://www.linkedin.com/company/daily-dev-ltd"]},{"@type":"WebSite","@id":"https://daily.dev/#website","url":"https://daily.dev","name":"daily.dev","publisher":{"@id":"https://daily.dev/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://daily.dev/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]} {"@context":"https://schema.org","@type":"TechArticle","headline":"OpenAPI Overlays for MCP and AI-Agent Enrichment","url":"https://daily.dev/posts/openapi-overlays-for-mcp-and-ai-agent-enrichment-tlwcd4t7t","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/openapi-overlays-for-mcp-and-ai-agent-enrichment-tlwcd4t7t"},"datePublished":"2026-08-11T12:07:18.631Z","dateModified":"2026-09-14T07:53:58.191Z","description":"OpenAPI Overlays can solve the problem of serving both human developers and AI agents from a single API spec. Rather than bloating human-facing docs with...","image":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/077163187eead76bedab193fe9a02739?_a=AQAEuop","thumbnailUrl":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/077163187eead76bedab193fe9a02739?_a=AQAEuop","isAccessibleForFree":true,"articleSection":"API Evangelist","inLanguage":"en","publisher":{"@type":"Organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180}},"author":{"@type":"Organization","name":"API Evangelist","logo":"https://media.daily.dev/image/upload/t_logo,f_auto/v1/logos/a36244ae67bc4f41a605f780267ecb5f","url":"https://daily.dev/sources/apievangelist"},"commentCount":2,"discussionUrl":"https://daily.dev/posts/openapi-overlays-for-mcp-and-ai-agent-enrichment-tlwcd4t7t","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":1},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":2}],"keywords":"ai-agents,architecture,mcp,openapi","timeRequired":"PT4M"} {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"API Evangelist","item":"https://daily.dev/sources/apievangelist"},{"@type":"ListItem","position":3,"name":"OpenAPI Overlays for MCP and AI-Agent Enrichment"}]} {"@context":"https://schema.org","@type":"WebPage","@id":"https://daily.dev/posts/openapi-overlays-for-mcp-and-ai-agent-enrichment-tlwcd4t7t","comment":[{"@type":"Comment","text":"Separating agent hints from the human-facing contract keeps the base spec readable without starving generated tools of context. The tricky bit will be testing overlays as versioned build inputs so an API change cannot leave the MCP surface with stale instructions.","datePublished":"2026-08-12T02:45:07.795Z","url":"https://daily.dev/posts/TLWCD4t7t#c-FcCgYFBgO","author":{"@type":"Person","name":"Trevor Suna","url":"https://daily.dev/trevorsuna","image":"https://media.daily.dev/image/upload/s--dZ7gXxpp--/f_auto/v1784081551/avatars/avatar_EMoP47rpuw8DNjhp6R1b6?_a=BAMAMicg0"}},{"@type":"Comment","text":"Would you allow one overlay to override another, or fail the build when two overlays touch the same operation?","datePublished":"2026-08-12T21:13:46.362Z","url":"https://daily.dev/posts/TLWCD4t7t#c-ljaLM4cjS","author":{"@type":"Person","name":"Agustin Barrientos","url":"https://daily.dev/agustinbarrientos","image":"https://media.daily.dev/image/upload/s--5ayxQnqn--/f_auto/v1788281802/avatars/avatar_wQYYVe5Tbj0NJ7C7qPoa8?_a=BAMAMicg0"}}]} {"@context":"https://schema.org","@type":"FAQPage","@id":"https://daily.dev/posts/openapi-overlays-for-mcp-and-ai-agent-enrichment-tlwcd4t7t#faq","mainEntity":[{"@type":"Question","name":"How can I make my OpenAPI spec agent-friendly without cluttering the human-facing docs?","acceptedAnswer":{"@type":"Answer","text":"Use the OpenAPI Overlay specification to layer agent-specific context on top of a single base contract instead of rewriting the spec. One overlay rewrites operation descriptions in explicit imperative language (e.g., distinguishing PUT for updates from POST cancel for permanent removal) targeted at agents, while a second overlay injects vendor extensions like x-mcp-tool-name and x-agent-hint that an MCP generator reads at build time to name tools and flag destructive operations. daily.dev surfaces practical overlay patterns for teams building MCP-ready APIs without duplicating specs."}},{"@type":"Question","name":"How do vendor extensions like x-mcp-tool-name help when generating an MCP tool list from OpenAPI?","acceptedAnswer":{"@type":"Answer","text":"Vendor extensions such as x-mcp-tool-name and x-agent-hint let an MCP generator name tools deterministically and flag destructive operations, instead of mangling an operation path like post /products/{id}/cancel into an unusable auto-generated name. These x- prefixed fields pass through OpenAPI untouched and can be applied via an overlay targeted only at the MCP build step. developers wiring up MCP servers can track patterns like this through daily.dev to avoid ad hoc tool naming."}}]} ```