{
  "openapi": "3.1.0",
  "info": {
    "title": "Docs MCP",
    "version": "1.0.0",
    "termsOfService": "https://redocly.com/subscription-agreement/",
    "contact": {
      "email": "team@redocly.com",
      "url": "https://redocly.com"
    },
    "license": {
      "name": "Custom",
      "url": "https://redocly.com/subscription-agreement/"
    },
    "description": "Connect AI assistants to your project's Docs MCP server to browse API descriptions, inspect endpoints, and search documentation content.\n\n**Base URL:** The Docs MCP server is available at `/mcp` on your project host. If your project is deployed under a path prefix, prepend that prefix to `/mcp`.\n\n**Public endpoint:** Projects that enable [`mcp.docs.publicEndpoint`](../../config/mcp.md) also serve `/mcp-public`. That endpoint requires no login and serves only the content that RBAC grants to the `anonymous` team.\n\n{% admonition type=\"info\" %}\nFor setup and configuration guidance, see [Model Context Protocol server](./index.md) and [MCP configuration reference](../../config/mcp.md).\n{% /admonition %}\n\n## Authentication\n\nPublic projects can expose Docs MCP without authentication.\n\nIf your project requires login (`rbac` or `requiresLogin` configured), Docs MCP Server requires the user to authenticate using the configured method.\nThis requirement ensures that AI Agents can only access APIs and operations the authenticated user has permission to view.\n\nThe `whoami` tool is only available when authentication handling is enabled for the Docs MCP server.\n\nThe `/mcp-public` endpoint never challenges for authentication.\nIt ignores any credentials the client sends and serves only the content available to the `anonymous` team.\n\n### Token validation\n\nEvery request carries its own token, and the server validates that token on each request.\nThe server verifies the token signature and checks that the token hasn't expired.\nIf your identity provider configuration sets `audience`, the `aud` claim in the token must match one of those values.\nIf users sign in through Reunite, the token must also name this project.\n\nA token isn't sufficient to determine what content is served.\nRBAC decides which content and API descriptions the request can reach.\n"
  },
  "servers": [
    {
      "url": "https://{projectHost}/mcp",
      "description": "Project Docs MCP endpoint.",
      "variables": {
        "projectHost": {
          "default": "redocly.com",
          "description": "Project host. Prepend your path prefix if applicable."
        }
      }
    },
    {
      "url": "https://{projectHost}/mcp-public",
      "description": "Public Docs MCP endpoint, served only when `mcp.docs.publicEndpoint` is enabled.\nIt requires no authentication and serves only content available to the `anonymous` team.\n",
      "variables": {
        "projectHost": {
          "default": "redocly.com",
          "description": "Project host. Prepend your path prefix if applicable."
        }
      }
    }
  ],
  "security": [
    {
      "OAuth2": []
    },
    {}
  ],
  "tags": [
    {
      "name": "Authentication",
      "x-displayName": "Identity",
      "description": "Tools for authentication and identity inspection for MCP clients when Docs MCP authentication handling is enabled."
    },
    {
      "name": "API Catalog",
      "description": "Tools for discovering published APIs, inspecting endpoints, reviewing security schemes, and retrieving full OpenAPI descriptions."
    },
    {
      "name": "Search",
      "description": "Tools for searching documentation content."
    },
    {
      "name": "Feedback",
      "description": "Tools that report documentation problems to the project team."
    }
  ],
  "paths": {},
  "x-mcp": {
    "protocolVersion": "2025-06-18",
    "servers": [
      {
        "url": "https://{projectHost}/mcp",
        "description": "Project Docs MCP endpoint.",
        "variables": {
          "projectHost": {
            "default": "redocly.com",
            "description": "Project host. Prepend your path prefix if applicable."
          }
        }
      },
      {
        "url": "https://{projectHost}/mcp-public",
        "description": "Public Docs MCP endpoint, served only when `mcp.docs.publicEndpoint` is enabled.\nIt requires no authentication and serves only content available to the `anonymous` team.\n",
        "variables": {
          "projectHost": {
            "default": "redocly.com",
            "description": "Project host. Prepend your path prefix if applicable."
          }
        }
      }
    ],
    "capabilities": {
      "logging": {},
      "tools": {
        "listChanged": true
      }
    },
    "tools": [
      {
        "name": "whoami",
        "description": "Get information about the currently authenticated user",
        "inputSchema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {}
        },
        "outputSchema": {
          "$ref": "#/components/schemas/WhoAmIOutput"
        },
        "tags": [
          "Authentication"
        ]
      },
      {
        "name": "list-apis",
        "description": "Lists available APIs with their context and purpose",
        "inputSchema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "filter": {
              "type": "string",
              "description": "Matches part of an API name, or of a description when no name matches",
              "minLength": 1
            },
            "page": {
              "type": "number",
              "description": "Page number",
              "minimum": 1,
              "default": 1
            },
            "limit": {
              "type": "number",
              "description": "Number of APIs per page. Default is 300",
              "minimum": 1,
              "default": 300
            }
          }
        },
        "outputSchema": {
          "$ref": "#/components/schemas/ListApisOutput"
        },
        "tags": [
          "API Catalog"
        ]
      },
      {
        "name": "get-endpoints",
        "description": "Get all endpoints for a specific API.",
        "inputSchema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "name": {
              "type": "string",
              "description": "API name, or a unique part of it. Omit when `filePath` is given.",
              "minLength": 1
            },
            "version": {
              "type": "string",
              "description": "API version. When omitted and several versions exist, the highest one is used."
            },
            "filePath": {
              "type": "string",
              "description": "Path to the API description file."
            }
          }
        },
        "outputSchema": {
          "$ref": "#/components/schemas/GetEndpointsOutput"
        },
        "tags": [
          "API Catalog"
        ]
      },
      {
        "name": "get-endpoint-info",
        "description": "Get comprehensive information about specific endpoint including parameters, security, and examples",
        "inputSchema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "name": {
              "type": "string",
              "description": "API name, or a unique part of it. Omit when `filePath` is given.",
              "minLength": 1
            },
            "path": {
              "type": "string",
              "description": "Endpoint path (for example, `/users`)",
              "minLength": 1
            },
            "method": {
              "type": "string",
              "description": "HTTP method",
              "enum": [
                "GET",
                "POST",
                "PUT",
                "DELETE",
                "PATCH",
                "OPTIONS",
                "HEAD",
                "TRACE",
                "get",
                "post",
                "put",
                "delete",
                "patch",
                "options",
                "head",
                "trace"
              ],
              "minLength": 1
            },
            "version": {
              "type": "string",
              "description": "API version. When omitted and several versions exist, the highest one is used."
            },
            "filePath": {
              "type": "string",
              "description": "Path to the API description file."
            }
          },
          "required": [
            "path",
            "method"
          ]
        },
        "outputSchema": {
          "$ref": "#/components/schemas/GetEndpointInfoOutput"
        },
        "tags": [
          "API Catalog"
        ]
      },
      {
        "name": "get-security-schemes",
        "description": "Get the security schemes for a specific API",
        "inputSchema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "name": {
              "type": "string",
              "description": "API name, or a unique part of it. Omit when `filePath` is given.",
              "minLength": 1
            },
            "version": {
              "type": "string",
              "description": "API version. When omitted and several versions exist, the highest one is used."
            },
            "filePath": {
              "type": "string",
              "description": "Path to the API description file."
            }
          }
        },
        "outputSchema": {
          "$ref": "#/components/schemas/GetSecuritySchemesOutput"
        },
        "tags": [
          "API Catalog"
        ]
      },
      {
        "name": "get-full-api-description",
        "description": "Get the complete OpenAPI description.",
        "inputSchema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "name": {
              "type": "string",
              "description": "API name, or a unique part of it. Omit when `filePath` is given.",
              "minLength": 1
            },
            "version": {
              "type": "string",
              "description": "API version. When omitted and several versions exist, the highest one is used."
            },
            "filePath": {
              "type": "string",
              "description": "Path to the API description file."
            }
          }
        },
        "outputSchema": {
          "$ref": "#/components/schemas/GetFullApiDescriptionOutput"
        },
        "tags": [
          "API Catalog"
        ]
      },
      {
        "name": "search",
        "description": "Search across the documentation to fetch relevant content for a given query.",
        "inputSchema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "query": {
              "type": "string",
              "description": "Search query.",
              "minLength": 1
            },
            "product": {
              "type": "string",
              "description": "Optional product name to filter search results by specific product."
            }
          },
          "required": [
            "query"
          ]
        },
        "outputSchema": {
          "$ref": "#/components/schemas/SearchOutput"
        },
        "tags": [
          "Search"
        ]
      },
      {
        "name": "submit-feedback",
        "description": "Report a documentation page that is wrong or incomplete.",
        "inputSchema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "path": {
              "type": "string",
              "description": "Path or URL of the documentation page the feedback is about (e.g. /guides/auth).",
              "minLength": 1,
              "maxLength": 1000
            },
            "summary": {
              "type": "string",
              "description": "One sentence that names what is wrong with the page.",
              "minLength": 1,
              "maxLength": 500
            },
            "details": {
              "type": "string",
              "description": "Expected versus actual behavior, missing steps, or the snippet that failed.",
              "maxLength": 4000
            },
            "targetFeature": {
              "type": "string",
              "description": "The API or feature the page documents.",
              "maxLength": 500
            }
          },
          "required": [
            "path",
            "summary"
          ]
        },
        "outputSchema": {
          "$ref": "#/components/schemas/SubmitFeedbackOutput"
        },
        "tags": [
          "Feedback"
        ]
      }
    ]
  },
  "components": {
    "securitySchemes": {
      "OAuth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://{projectHost}/_mcp/oauth2/auth",
            "tokenUrl": "https://{projectHost}/_mcp/oauth2/token-portal",
            "scopes": {}
          }
        }
      }
    },
    "schemas": {
      "OpenApiServer": {
        "type": "object",
        "description": "OpenAPI Server Object for the published API description.",
        "properties": {
          "url": {
            "type": "string",
            "description": "Server URL."
          },
          "description": {
            "type": "string",
            "description": "Human-readable server description."
          },
          "name": {
            "type": "string",
            "description": "Optional server name."
          },
          "variables": {
            "type": "object",
            "description": "Server variable definitions keyed by variable name.",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "default": {
                  "type": "string"
                },
                "enum": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "description": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "url"
        ],
        "additionalProperties": true
      },
      "ApiCatalogItem": {
        "type": "object",
        "description": "API entry returned by the docs catalog.",
        "properties": {
          "name": {
            "type": "string",
            "description": "API name used by the Docs MCP tools."
          },
          "description": {
            "type": "string",
            "description": "API description or summary."
          },
          "version": {
            "type": "string",
            "description": "API version string from the source description."
          },
          "servers": {
            "type": "array",
            "description": "Servers defined by the published OpenAPI description.",
            "items": {
              "$ref": "#/components/schemas/OpenApiServer"
            }
          },
          "filePath": {
            "type": "string",
            "description": "Path to the API description file."
          }
        },
        "required": [
          "name",
          "filePath"
        ],
        "additionalProperties": false
      },
      "ApiEndpointSummary": {
        "type": "object",
        "description": "Endpoint summary returned by the API catalog tools.",
        "properties": {
          "path": {
            "type": "string",
            "description": "Endpoint path."
          },
          "method": {
            "type": "string",
            "description": "Uppercase HTTP method."
          },
          "summary": {
            "type": "string",
            "description": "OpenAPI operation summary."
          },
          "description": {
            "type": "string",
            "description": "OpenAPI operation description."
          },
          "security": {
            "type": "array",
            "description": "Operation security requirements from the source OpenAPI description.",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        },
        "required": [
          "path",
          "method"
        ],
        "additionalProperties": false
      },
      "WhoAmIOutput": {
        "type": "object",
        "description": "Authenticated user details returned by the `whoami` tool.",
        "properties": {
          "email": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "subject": {
            "type": "string"
          },
          "clientId": {
            "type": "string"
          },
          "scope": {
            "type": "string"
          },
          "issuedAt": {
            "type": "string",
            "format": "date-time"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "ListApisOutput": {
        "type": "object",
        "description": "Paginated list of APIs available through the Docs MCP server.",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiCatalogItem"
            }
          },
          "limit": {
            "type": "number"
          },
          "total": {
            "type": "number"
          },
          "page": {
            "type": "number"
          },
          "totalPages": {
            "type": "number"
          }
        },
        "required": [
          "items",
          "limit",
          "total",
          "page",
          "totalPages"
        ],
        "additionalProperties": false
      },
      "ApiDescriptionRef": {
        "type": "object",
        "description": "Reference to an API description file the lookup also matched.",
        "properties": {
          "version": {
            "type": "string",
            "description": "API version."
          },
          "filePath": {
            "type": "string",
            "description": "API description file path. Pass it as `filePath` to load this definition."
          }
        },
        "required": [
          "filePath"
        ],
        "additionalProperties": false
      },
      "GetEndpointsOutput": {
        "type": "object",
        "description": "Endpoint list for a single published API.",
        "properties": {
          "api": {
            "type": "string",
            "description": "API title."
          },
          "version": {
            "type": "string",
            "description": "API version."
          },
          "filePath": {
            "type": "string",
            "description": "API description file path for this result."
          },
          "otherMatches": {
            "type": "array",
            "description": "Other description files the lookup matched. Present only when several share the requested name.",
            "items": {
              "$ref": "#/components/schemas/ApiDescriptionRef"
            }
          },
          "servers": {
            "type": "array",
            "description": "Servers defined by the published OpenAPI description.",
            "items": {
              "$ref": "#/components/schemas/OpenApiServer"
            }
          },
          "endpoints": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiEndpointSummary"
            }
          }
        },
        "required": [
          "api",
          "version",
          "filePath",
          "servers",
          "endpoints"
        ],
        "additionalProperties": false
      },
      "GetEndpointInfoOutput": {
        "type": "object",
        "description": "Detailed endpoint information with resolved OpenAPI structures.",
        "properties": {
          "api": {
            "type": "string",
            "description": "API title."
          },
          "version": {
            "type": "string",
            "description": "API version."
          },
          "filePath": {
            "type": "string",
            "description": "API description file path for this result."
          },
          "otherMatches": {
            "type": "array",
            "description": "Other description files the lookup matched. Present only when several share the requested name.",
            "items": {
              "$ref": "#/components/schemas/ApiDescriptionRef"
            }
          },
          "servers": {
            "type": "array",
            "description": "Servers defined by the published OpenAPI description.",
            "items": {
              "$ref": "#/components/schemas/OpenApiServer"
            }
          },
          "endpoint": {
            "type": "object",
            "description": "Endpoint details derived from the resolved OpenAPI operation. Besides `path` and `method`, the object may include parameters, request body, responses, security, examples, and other operation-level fields from the source OpenAPI description.\n",
            "properties": {
              "path": {
                "type": "string"
              },
              "method": {
                "type": "string"
              }
            },
            "required": [
              "path",
              "method"
            ],
            "additionalProperties": true
          },
          "globalSecurity": {
            "type": "array",
            "description": "Global security requirements defined on the OpenAPI document.",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "securitySchemes": {
            "type": "object",
            "description": "Security schemes map from the OpenAPI components section.",
            "additionalProperties": true
          },
          "components": {
            "type": "object",
            "description": "Components that the endpoint references, keyed as the source OpenAPI description keys them. A `$ref` in `endpoint` resolves against the root of the result.",
            "additionalProperties": true
          }
        },
        "required": [
          "api",
          "version",
          "filePath",
          "servers",
          "endpoint",
          "globalSecurity",
          "securitySchemes"
        ],
        "additionalProperties": false
      },
      "GetSecuritySchemesOutput": {
        "type": "object",
        "description": "Security metadata returned for a published API.",
        "properties": {
          "name": {
            "type": "string",
            "description": "API title."
          },
          "version": {
            "type": "string",
            "description": "API version."
          },
          "filePath": {
            "type": "string",
            "description": "API description file path for this result."
          },
          "otherMatches": {
            "type": "array",
            "description": "Other description files the lookup matched. Present only when several share the requested name.",
            "items": {
              "$ref": "#/components/schemas/ApiDescriptionRef"
            }
          },
          "securitySchemes": {
            "type": "object",
            "description": "Security schemes map from the OpenAPI components section.",
            "additionalProperties": true
          },
          "security": {
            "type": "array",
            "description": "Global security requirements defined on the OpenAPI document.",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        },
        "required": [
          "name",
          "version",
          "filePath",
          "securitySchemes",
          "security"
        ],
        "additionalProperties": false
      },
      "GetFullApiDescriptionOutput": {
        "type": "object",
        "description": "Full published OpenAPI document after access filtering.",
        "properties": {
          "api": {
            "type": "string",
            "description": "API title."
          },
          "version": {
            "type": "string",
            "description": "API version."
          },
          "filePath": {
            "type": "string",
            "description": "API description file path for this result."
          },
          "otherMatches": {
            "type": "array",
            "description": "Other description files the lookup matched. Present only when several share the requested name.",
            "items": {
              "$ref": "#/components/schemas/ApiDescriptionRef"
            }
          },
          "definition": {
            "type": "object",
            "description": "Full OpenAPI description file returned by the Docs MCP server.",
            "additionalProperties": true
          }
        },
        "required": [
          "api",
          "version",
          "filePath",
          "definition"
        ],
        "additionalProperties": false
      },
      "SearchOutput": {
        "type": "string",
        "description": "Markdown string containing the rendered search results."
      },
      "SubmitFeedbackOutput": {
        "type": "object",
        "description": "Confirmation returned by the `submit-feedback` tool.",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "received"
            ]
          },
          "page": {
            "type": "string",
            "description": "Absolute URL of the page the feedback refers to."
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "status",
          "page",
          "message"
        ],
        "additionalProperties": false
      }
    }
  }
}