Redocly Docs MCP Server

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.


    ### Token validation


    Every request carries its own token, and the server validates that token on
    each request.

    The server checks the signature against the identity provider that issued
    the token, checks the expiry, and compares the `aud` (audience) claim to
    your organization ID.


    A token whose `aud` names a different organization is recorded and, when
    audience enforcement is on for your project, rejected with a `401` response.

    Enforcement is off by default, and [MCP configuration
    reference](../../config/mcp.md#token-audience-validation) names the
    environment variable that turns it on.


    Two cases skip the audience comparison.

    Tokens that carry no `aud` claim are accepted, because portal session tokens
    and tokens from some identity provider setups don't set one.

    Projects that run without an organization ID, such as self-hosted
    deployments, have nothing to compare against.


    A token isn't sufficient to determine what content is served.

    RBAC decides which content and API descriptions the request can reach.
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
    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.
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: >-
              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
            minLength: 1
          version:
            type: string
            description: API version
          filePath:
            type: string
            description: API definition file path
        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, or a unique part of it
            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
          filePath:
            type: string
            description: API definition file path
        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, or a unique part of it
            minLength: 1
          version:
            type: string
            description: API version
          filePath:
            type: string
            description: API definition file path
        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, or a unique part of it
            minLength: 1
          version:
            type: string
            description: API version
          filePath:
            type: string
            description: API definition file path
        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'
        filePath:
          type: string
          description: API definition file path.
      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
    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.