[object Object]

← back to Cli Printing Press

docs(skills): document x-mcp as the OpenAPI form of the mcp: enrichment block (#1201)

9df8c5a2f6c370ef382504be768921d27f8f519b · 2026-05-12 08:58:07 -0700 · Trevin Chow

The SKILL's Pre-Generation MCP Enrichment section only showed the
internal-YAML `mcp:` form, leaving agents working from OpenAPI specs to
guess the vendor-extension key. The generator's >50-tool warning had the
same gap. Names both forms (`mcp:` for internal YAML, `x-mcp:` for
OpenAPI) and points at docs/SPEC-EXTENSIONS.md for the canonical schema.

Closes #1049

Files touched

Diff

commit 9df8c5a2f6c370ef382504be768921d27f8f519b
Author: Trevin Chow <trevin@trevinchow.com>
Date:   Tue May 12 08:58:07 2026 -0700

    docs(skills): document x-mcp as the OpenAPI form of the mcp: enrichment block (#1201)
    
    The SKILL's Pre-Generation MCP Enrichment section only showed the
    internal-YAML `mcp:` form, leaving agents working from OpenAPI specs to
    guess the vendor-extension key. The generator's >50-tool warning had the
    same gap. Names both forms (`mcp:` for internal YAML, `x-mcp:` for
    OpenAPI) and points at docs/SPEC-EXTENSIONS.md for the canonical schema.
    
    Closes #1049
---
 internal/generator/mcp_warning.go | 5 +++--
 skills/printing-press/SKILL.md    | 9 ++++++++-
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/internal/generator/mcp_warning.go b/internal/generator/mcp_warning.go
index 2edc5f18..8da3aa67 100644
--- a/internal/generator/mcp_warning.go
+++ b/internal/generator/mcp_warning.go
@@ -10,12 +10,13 @@ import (
 const largeMCPSurfaceWarning = `warning: spec exposes %d MCP endpoint tools (>%d threshold). The default
          endpoint-mirror surface burns agent context at this scale and will
          score poorly on the scorecard's MCP architectural dimensions. Consider
-         enriching the spec's mcp: block before generation:
+         enriching the spec's mcp: (internal YAML) or x-mcp: (OpenAPI) block
+         before generation:
            mcp:
              transport: [stdio, http]    # remote-capable; reaches hosted agents
              orchestration: code         # thin <api>_search + <api>_execute pair
              endpoint_tools: hidden      # suppress raw per-endpoint mirrors
-         See docs/SPEC-EXTENSIONS.md for the full mcp: schema.
+         See docs/SPEC-EXTENSIONS.md for the full mcp:/x-mcp: schema.
 `
 
 // warnUnenrichedLargeMCPSurface honors the contract on
diff --git a/skills/printing-press/SKILL.md b/skills/printing-press/SKILL.md
index f494783a..96a53c2f 100644
--- a/skills/printing-press/SKILL.md
+++ b/skills/printing-press/SKILL.md
@@ -1874,7 +1874,8 @@ The total is what an agent loads at MCP server start.
 | >50 | Default to recommending the Cloudflare pattern (transport + code orchestration + hidden endpoint tools). The generator will also print a warning at this size. |
 
 **The Cloudflare pattern** (recommended for large surfaces) — edit the spec's
-`mcp:` block before running `generate`:
+`mcp:` block (internal YAML) or `x-mcp:` block (OpenAPI) before running
+`generate`:
 
 ```yaml
 mcp:
@@ -1894,6 +1895,12 @@ emits the thin search+execute pair that covers the full surface in ~1K tokens.
 `mcp.endpoint_tools: hidden` removes the raw per-endpoint tools that would
 otherwise still show up alongside the orchestration pair.
 
+For OpenAPI input specs, declare these fields under `x-mcp:` at the document
+root (OpenAPI 3.0 `x-*` vendor extensions). The shape is identical to the
+internal-YAML `mcp:` block above — same field names, just nested under a
+vendor-extension key. See [`docs/SPEC-EXTENSIONS.md`](../../docs/SPEC-EXTENSIONS.md) for the canonical
+schema and `info`-level placement option.
+
 **Smaller-surface variants:**
 
 - Just want remote reach? `mcp.transport: [stdio, http]` alone is fine.

← c9a35b5e fix(cli): refuse to ship CLIs with placeholder base URL (#11  ·  back to Cli Printing Press  ·  fix(cli): index args[] by positional ordinal in path-param e 460d676e →