{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"openapi-extension-x-mcp","__idx":0},"children":["OpenAPI extension: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-mcp"]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Experimental"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is an experimental feature."," ","Its behavior may change in future releases."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-mcp"]}," to document MCP (Model Context Protocol) servers for consumers."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"location","__idx":1},"children":["Location"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-mcp"]}," extension can be added to Root Object."," ","The root is the outer most level of the OpenAPI description."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"options","__idx":2},"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":["x-mcp"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#mcp-object"},"children":["MCP object"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["MCP server description and configuration."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"mcp-object","__idx":3},"children":["MCP object"]},{"$$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":["protocolVersion"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," ","The MCP protocol version supported by the server."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["servers"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["[ ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#serverObject"},"children":["Server Object"]}," ]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A list of server objects used to add one or more target endpoints for the MCP server."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["capabilities"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#capabilities-object"},"children":["Capabilities object"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Server capabilities including supported features like logging, prompts, resources, and tools."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["tools"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["[ ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#tool-object"},"children":["Tool object"]}," ]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Array of tools provided by the MCP server."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["resources"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["[ ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#resource-object"},"children":["Resource object"]}," ]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Array of resources provided by the MCP server."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["prompts"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["[ ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#prompt-object"},"children":["Prompt object"]}," ]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Prompt capabilities configuration with optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["listChanged"]}," boolean property."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"capabilities-object","__idx":4},"children":["Capabilities object"]},{"$$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":["logging"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Logging capabilities configuration."," ","Empty object indicates basic logging support."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["prompts"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Prompt capabilities configuration with optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["listChanged"]}," boolean property."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["resources"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Resource capabilities configuration with optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscribe"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["listChanged"]}," boolean properties."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["tools"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tool capabilities configuration with optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["listChanged"]}," boolean property."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"tool-object","__idx":5},"children":["Tool object"]},{"$$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":["name"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," ","The name of the tool."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["title"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Title of the tool."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["description"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," ","Description of what the tool does."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["tags"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["[ string ]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tags for the tool."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["inputSchema"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["JSON Schema describing the expected input parameters for the tool."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["outputSchema"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object | string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["JSON Schema describing the tool's output, or a reference to a schema component."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["security"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["[ object ]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Security requirements for the tool, following OpenAPI security scheme format."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"resource-object","__idx":6},"children":["Resource object"]},{"$$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":["name"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," ","The name of the resource."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["description"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Description of the resource."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["uri"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["URI template for accessing the resource."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["mimeType"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["MIME type of the resource content."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"prompt-object","__idx":7},"children":["Prompt object"]},{"$$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":["name"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," ","The name of the prompt."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["title"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Title of the prompt."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["description"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Description of the prompt."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["arguments"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["[ ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#argument-object"},"children":["Argument object"]}," ]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Array of arguments for the prompt."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"argument-object","__idx":8},"children":["Argument object"]},{"$$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":["name"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," ","The name of the argument."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["description"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Description of the argument."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Whether the argument is required."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":9},"children":["Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"x-mcp-example","__idx":10},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-mcp"]}," example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Metadata keys can be any string."," ","The values can be any primitive type, or a list of strings."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following is an example of an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-mcp"]}," described within an OpenAPI description file:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","data-title":"api-clients-mcp.yaml","header":{"title":"api-clients-mcp.yaml","controls":{"copy":{}}},"source":"openapi: 3.2.0\ninfo:\n  version: 1.0.0\n  title: API Clients MCP\n  license:\n    name: MIT\nservers:\n  - url: http://localhost:8080/mcp\n\npaths: {} # no paths\n\nx-mcp:\n  protocolVersion: '2025-06-18'\n  capabilities:\n    logging: {}\n    prompts:\n      listChanged: true\n    resources:\n      subscribe: true\n    tools:\n      listChanged: true\n  tools:\n    # this is the output of the list/tools call to the MCP\n    - name: clients/get\n      description: Get a list of clients with all scopes in a service domain.\n      inputSchema:\n        type: object\n        properties:\n          clientId:\n            type: string\n            description: The ID of the client to get.\n      outputSchema:\n        $ref: '#/components/schemas/Client'\n      # we added the OAuth2 security scheme\n      security:\n        - OAuth2:\n            scopes:\n              read: Read access\n    - name: clients/list\n      description: Get a list of clients with all scopes in a service domain.\n      inputSchema:\n        type: object\n        properties:\n          paginationToken:\n            type: string\n            description: The pagination token to get the next page of clients.\n      outputSchema:\n        type: object\n        properties:\n          clients:\n            type: array\n            items:\n              $ref: '#/components/schemas/Client'\n          paginationToken:\n            type: string\n            description: The pagination token to get the next page of clients.\n  resources: []\n\ncomponents:\n  securitySchemes:\n    OAuth2:\n      type: oauth2\n      flows:\n        clientCredentials:\n          tokenUrl: http://localhost:8080/mcp/token\n          scopes:\n            read: Read access\n            write: Write access\n  schemas:\n    Client:\n      type: object\n      properties:\n        clientId:\n          type: number\n          description: The ID of the client.\n        scopes:\n          type: array\n          items:\n            type: string\n          description: The scopes of the client.\n      required:\n        - clientId\n        - scopes\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The data is presented similar to the following screenshot:"]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/mcp-docs-example-4ccdbb25ca2585f5.png","alt":"Example MCP docs","framed":true,"withLightbox":true},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":11},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/api-docs/openapi-extensions"},"children":["Supported OpenAPI extensions"]}]}," - Complete list of all OpenAPI extensions supported by Redocly for enhanced API documentation"]}]}]},"frontmatter":{},"tagList":["admonition","img","partial","table"],"title":"OpenAPI extension: x-mcp","lastModified":"2026-09-17T13:26:51.000Z"}