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.

    **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`.

    {% admonition type="info" %}
    For setup and configuration guidance, see [Model Context Protocol server](./index.md) and [MCP configuration reference](../../config/mcp.md).
    {% /admonition %}

    ## Authentication

    Public projects can expose Docs MCP without authentication.

    If your project requires login (`rbac` or `requiresLogin` configured), Docs MCP Server requires the user to authenticate using the configured method.
    This requirement ensures that AI Agents can only access APIs and operations the authenticated user has permission to view.

    The `whoami` tool is only available when authentication handling is enabled for the Docs MCP server.

servers:
  - url: https://{projectHost}/mcp
    description: Project Docs MCP endpoint.
    variables:
      projectHost:
        default: redocly.com
        description: Project host. Prepend your path prefix if applicable.

security:
  - OAuth2: []

tags:
  - name: Authentication
    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.

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.
  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: API name (or part of it)
            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
            minLength: 1
        required:
          - name
      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
            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
        required:
          - name
          - 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
            minLength: 1
        required:
          - name
      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
            minLength: 1
        required:
          - name
      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

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'
      required:
        - name
      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
    GetEndpointsOutput:
      type: object
      description: Endpoint list for a single published API.
      properties:
        api:
          type: string
          description: API title.
        version:
          type: string
          description: API version.
        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
        - 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.
        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.
          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
      required:
        - api
        - version
        - 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.
        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
      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.
        definition:
          type: object
          description: Full OpenAPI definition returned by the Docs MCP server.
          additionalProperties: true
      required:
        - api
        - version
        - definition
      additionalProperties: false
    SearchOutput:
      type: string
      description: Markdown string containing the rendered search results.