{"templateId":"markdown","versions":[{"version":"v1","label":"1.x (archive)","link":"/docs/cli/v1/commands/introspect-mcp","default":false,"active":false,"folderId":"6f4800fc"},{"version":"v2","label":"2.x (current)","link":"/docs/cli/commands/introspect-mcp","default":true,"active":true,"folderId":"6f4800fc"}],"sharedDataIds":{"sidebar":"sidebar-docs-cli.sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"redocly_category":"Redocly CLI","type":"markdown"},"seo":{"title":"introspect-mcp","description":"OpenAPI-generated documentation tool with 24k+ stars on Github - make APIs your company's superpower.","siteUrl":"https://redocly.com","image":"/assets/redocly-card.f670aae34a39545a5ea633a540cb3a4a333a1f23bb2ed3c4a1b17a5fbcf0ac85.db81178d.png","lang":"en-US"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"introspect-mcp","__idx":0},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["introspect-mcp"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["introspect-mcp"]}," command analyzes a running MCP (Model Context Protocol) server and records what it found in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/realm/content/api-docs/openapi-extensions/x-mcp"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-mcp"]}," extension"]}," of an OpenAPI description."," ","The command connects to the server, lists its tools, prompts, and resources together with the server capabilities and the negotiated protocol version."," ","Then the command writes this information into the description file."," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/realm"},"children":["Redocly Realm"]}," renders the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-mcp"]}," extension as MCP documentation alongside the rest of the API reference."," ","The recorded tools, prompts, and resources become reader-facing docs."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Experimental"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is an experimental feature."," ","Its behavior, command, flags, and output may change in future releases."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":1},"children":["How it works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The command reaches the MCP server in one of two ways:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A server URL connects over Streamable HTTP, and automatically falls back to the legacy HTTP+SSE transport when the server doesn't support Streamable HTTP."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--command"]}," starts a local MCP server process and talks to it over stdio."," ","Most published MCP servers run this way, for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["npx -y my-mcp-server"]},"."," ","The process inherits your environment."," ","Servers that read API keys from environment variables work as they do in your shell."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the output file doesn't exist, the command creates a minimal OpenAPI 3.1 description scaffolded from the server's implementation info and instructions."," ","Review and complete the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info"]}," section afterward."," ","If the file exists, the command updates it in place:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The MCP server URL is appended to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-mcp.servers"]}," unless it's already listed."," ","The root ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["servers"]}," list (the API's base URLs) stays untouched, and stdio servers have no URL to record."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-mcp"]}," lists are replaced with what the server reports."," ","Renamed or removed entries don't linger."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Documentation-only annotations that the MCP protocol doesn't carry are preserved by entry name: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tags"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["security"]}," on tools, prompts, and resources, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["example"]}," on prompt arguments."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Everything else in the description stays untouched."," ","You can keep documenting the API around the generated ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-mcp"]}," section."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--check"]},", the command only compares the file with what an introspection run would produce without writing anything."," ","It reports the added, removed, and changed entries, and exits with code ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}," when the file is out of date."," ","This flag is useful for CI."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"usage","__idx":2},"children":["Usage"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly introspect-mcp <server-url>\nredocly introspect-mcp <server-url> --output <file>\nredocly introspect-mcp <server-url> -H \"Authorization: Bearer <token>\"\nredocly introspect-mcp --command \"npx -y my-mcp-server\" --output <file>\nredocly introspect-mcp <server-url> --output <file> --check\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"options","__idx":3},"children":["Options"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["server-url"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["URL of the MCP server (Streamable HTTP, with a fallback to the legacy HTTP+SSE transport). Provide either a server URL or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--command"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--command"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Command that starts a local MCP server to introspect over stdio, for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"npx -y my-mcp-server\""]},". Quote arguments that contain spaces. Provide either a server URL or this option."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--output, -o"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["OpenAPI description file to create or update. Default value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openapi.yaml"]},". A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".json"]}," file is written as JSON."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--header, -H"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["[string]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Header sent with every request to the MCP server, in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"Name: value\""]}," format. Repeat the option for multiple headers. Only applies to a server URL."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--check"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify the description is up to date with the MCP server instead of writing: report the differences and exit with code ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}," when it is not."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--config"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Specify path to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/cli/configuration"},"children":["configuration file"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--help"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Display help."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--version"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Display version number."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":4},"children":["Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"document-an-mcp-server-in-an-openapi-description","__idx":5},"children":["Document an MCP server in an OpenAPI description"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The same command creates the file on the first run and refreshes it afterward, keeping the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tags"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["security"]},", and prompt argument ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["example"]}," annotations you added by hand:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly introspect-mcp https://example.com/mcp --output api/openapi.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"document-a-local-stdio-server","__idx":6},"children":["Document a local stdio server"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly introspect-mcp --command \"npx -y my-mcp-server\" --output api/openapi.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"introspect-a-server-that-requires-authentication","__idx":7},"children":["Introspect a server that requires authentication"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly introspect-mcp https://example.com/mcp -H \"Authorization: Bearer $MCP_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"fail-ci-when-the-description-is-stale","__idx":8},"children":["Fail CI when the description is stale"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--check"]}," compares the file with the live server without writing, and reports what drifted:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly introspect-mcp https://example.com/mcp --output api/openapi.yaml --check\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"api/openapi.yaml is out of date with the MCP server:\n  - tools - added: orders/cancel; changed: orders/create\n  - protocolVersion - 2024-11-05 -> 2025-11-25\n\nRun the command without --check to update it.\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":9},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/realm/content/api-docs/openapi-extensions/x-mcp"},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-mcp"]}," extension reference"]}," describes every field the command writes and shows how the rendered MCP docs look."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/realm"},"children":["Redocly Realm"]}," renders an OpenAPI description with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-mcp"]}," as MCP documentation - use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/cli/commands/preview"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["preview"]}]}," command to see it locally."]}]}]},"headings":[{"value":"introspect-mcp","id":"introspect-mcp","depth":1},{"value":"How it works","id":"how-it-works","depth":2},{"value":"Usage","id":"usage","depth":2},{"value":"Options","id":"options","depth":2},{"value":"Examples","id":"examples","depth":2},{"value":"Document an MCP server in an OpenAPI description","id":"document-an-mcp-server-in-an-openapi-description","depth":3},{"value":"Document a local stdio server","id":"document-a-local-stdio-server","depth":3},{"value":"Introspect a server that requires authentication","id":"introspect-a-server-that-requires-authentication","depth":3},{"value":"Fail CI when the description is stale","id":"fail-ci-when-the-description-is-stale","depth":3},{"value":"Resources","id":"resources","depth":2}],"frontmatter":{"seo":{"title":"introspect-mcp"}},"lastModified":"2026-09-10T15:11:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/cli/commands/introspect-mcp","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}