If you ship an MCP (Model Context Protocol) server, that server is an API surface of its own: tools with input schemas, prompts with arguments, resources with URIs. AI agents discover all of it at runtime, but the humans evaluating your API usually can't, because that surface lives only in the server code.

The x-mcp OpenAPI extension records the MCP server's capabilities in the same OpenAPI description as the rest of your API. You can then render it for humans with Redocly Realm, next to your API reference. The new experimental introspect-mcp command in Redocly CLI fills that extension in for you, by asking the server itself.

Point the command at a running MCP server and tell it which file to write:

npx @redocly/cli@latest introspect-mcp https://learn.microsoft.com/api/mcp -o openapi.yaml

That's the public MCP server of Microsoft Learn, Microsoft's documentation and training platform, so you can run this exact command right now. The CLI connects over Streamable HTTP, falling back to the legacy HTTP+SSE transport for older servers. It negotiates the protocol version, lists every tool, prompt, and resource — following pagination — and writes the result. If openapi.yaml doesn't exist yet, it's scaffolded from the server's own name, version, and instructions.

A trimmed excerpt from a real run:

x-mcp:
  protocolVersion: '2025-06-18'
  servers:
    - url: https://learn.microsoft.com/api/mcp
  capabilities:
    # ...the logging, prompts, and resources capabilities
    tools:
      listChanged: true
  tools:
    - name: microsoft_docs_search
      title: Microsoft Docs Search
      # ...the tool's long description
      inputSchema:
        type: object
        properties:
          query:
            description: >-
              a query or topic about Microsoft/Azure products, services,
              platforms, developer tools, frameworks, or APIs
            type: string
            default: null
      # ...the tool's outputSchema, and the other two tools

For servers that require authentication, pass headers the same way you would with curl:

npx @redocly/cli@latest introspect-mcp https://example.com/mcp -H "Authorization: Bearer $MCP_TOKEN" -o openapi.yaml

Most published MCP servers packages you launch with npx instead of HTTP endpoints. The --command option starts one as a local process and introspects it over stdio:

npx @redocly/cli@latest introspect-mcp --command "npx -y @modelcontextprotocol/server-everything" -o openapi.yaml

Running that against the MCP reference server records 13 tools, 4 prompts, and 7 resources. The spawned process inherits your environment, so a server that reads its API key from an environment variable behaves exactly as it does in your shell.

The command updates the description in place: your info, paths, servers, and components stay untouched, and only the x-mcp section changes. On every refresh, the tool, prompt, and resource lists are replaced with what the server reports. This way, renamed and removed entries are cleaned up. The annotations the MCP protocol doesn't carry are preserved by entry name: tags and security on tools, prompts, and resources, and example on prompt arguments.

Suppose the Redocly Cafe API shipped an MCP server for order management. Its OpenAPI description already defines an OAuth2 security scheme and an Orders tag, so you annotate the introspected tool to match:

x-mcp:
  tools:
    - name: orders/create
      description: Create an order.
      inputSchema:
        type: object
        properties:
          customerName:
            type: string
        required:
          - customerName
      tags:
        - Orders
      security:
        - OAuth2:
            - orders:write

When the server's schemas or descriptions change, rerun the command: the introspected data is updated, and your tags and security are kept.

MCP servers change, and the documented snapshot gets outdated. The --check flag makes the command usable as a CI check: it compares the file with what an introspection run would produce, writes nothing, and exits with code 1 when they differ.

npx @redocly/cli@latest introspect-mcp https://learn.microsoft.com/api/mcp -o openapi.yaml --check

For example, after the server renames a tool, the command reports:

openapi.yaml is out of date with the MCP server:
  - tools - added: microsoft_docs_search; removed: microsoft_docs_search_v1

Run the command without --check to update it.

Add this command to your CI pipeline to fail the build when the published description no longer matches the MCP server.

Once x-mcp is in the description, it's regular OpenAPI: lint it, bundle it, version it in Git. And Redocly Realm renders the extension as MCP documentation right next to your API reference. The tools, prompts, and resources you just introspected become reader-facing docs — no extra authoring step.

To learn more, see the introspect-mcp documentation and the x-mcp extension reference.

Have you tried it against your own MCP server? Let us know — the command is new and experimental, and real-world feedback shapes where it goes next.