Supported Extensions

x-mcp

Use x-mcp to document MCP (Model Context Protocol) server metadata in your OpenAPI description. This extension describes the MCP server capabilities, tools, resources, and prompts at the document root.

Support for rendering x-mcp in Dev Portal is currently in development. For now, if you want to mark individual operations as MCP endpoints with full UI support, use the x-mcp-server extension.

Location

The x-mcp extension is added at the Root Object level — the outermost level of the OpenAPI description.

Option	Type	Description
`x-mcp`	MCP Object	MCP server description and configuration

MCP Object

Property	Type	Required	Description
`protocolVersion`	`string`	Yes	The MCP protocol version supported by the server.
`servers`	`[Server Object]`	No	A list of server objects used to add one or more target endpoints for the MCP server.
`capabilities`	`Capabilities Object`	No	Server capabilities including supported features like logging, prompts, resources, and tools.
`tools`	`[Tool Object]`	No	Array of tools provided by the MCP server.
`resources`	`[Resource Object]`	No	Array of resources provided by the MCP server.
`prompts`	`[Prompt Object]`	No	Array of prompts provided by the MCP server.

Capabilities Object

Property	Type	Description
`logging`	`object`	Logging capabilities configuration. Empty object indicates basic logging support.
`prompts`	`object`	Prompt capabilities configuration with optional `listChanged` boolean property.
`resources`	`object`	Resource capabilities configuration with optional `subscribe` and `listChanged` boolean properties.
`tools`	`object`	Tool capabilities configuration with optional `listChanged` boolean property.

Tool Object

Property	Type	Required	Description
`name`	`string`	Yes	The name of the tool.
`title`	`string`	No	Title of the tool.
`description`	`string`	Yes	Description of what the tool does.
`tags`	`[string]`	No	Tags for the tool.
`inputSchema`	`object`	No	JSON Schema describing the expected input parameters for the tool.
`outputSchema`	`object` or `string`	No	JSON Schema describing the tool's output, or a reference to a schema component.
`security`	`[object]`	No	Security requirements for the tool, following OpenAPI security scheme format.

Resource Object

Property	Type	Required	Description
`name`	`string`	Yes	The name of the resource.
`description`	`string`	No	Description of the resource.
`uri`	`string`	No	URI template for accessing the resource.
`mimeType`	`string`	No	MIME type of the resource content.

Prompt Object

Property	Type	Required	Description
`name`	`string`	Yes	The name of the prompt.
`title`	`string`	No	Title of the prompt.
`description`	`string`	No	Description of the prompt.
`arguments`	`[Argument Object]`	No	Array of arguments for the prompt.

Argument Object

Property	Type	Required	Description
`name`	`string`	Yes	The name of the argument.
`description`	`string`	No	Description of the argument.
`required`	`boolean`	No	Whether the argument is required.

Example

The following example shows an OpenAPI description with an x-mcp extension that defines an MCP server with OAuth2 security, multiple tools, and schema components:


Code
openapi: 3.2.0
info:
  version: 1.0.0
  title: API Clients MCP
  license:
    name: MIT
servers:
  - url: http://localhost:8080/mcp

paths: {}

x-mcp:
  protocolVersion: "2025-06-18"
  capabilities:
    logging: {}
    prompts:
      listChanged: true
    resources:
      subscribe: true
    tools:
      listChanged: true
  tools:
    - name: clients/get
      description: Get a list of clients with all scopes in a service domain.
      inputSchema:
        type: object
        properties:
          clientId:
            type: string
            description: The ID of the client to get.
      outputSchema:
        $ref: "#/components/schemas/Client"
      security:
        - OAuth2:
            - read
    - name: clients/list
      description: Get a list of clients with all scopes in a service domain.
      inputSchema:
        type: object
        properties:
          paginationToken:
            type: string
            description: The pagination token to get the next page of clients.
      outputSchema:
        type: object
        properties:
          clients:
            type: array
            items:
              $ref: "#/components/schemas/Client"
          paginationToken:
            type: string
            description: The pagination token to get the next page of clients.
  resources: []

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: http://localhost:8080/mcp/token
          scopes:
            read: Read access
            write: Write access
  schemas:
    Client:
      type: object
      properties:
        clientId:
          type: number
          description: The ID of the client.
        scopes:
          type: array
          items:
            type: string
          description: The scopes of the client.
      required:
        - clientId
        - scopes

Edit this page

Last modified on April 24, 2026

API Catalog x-mcp-server

Option

Type

Description

x-mcp

MCP Object

MCP server description and configuration

MCP Object

Property

Type

Required

Description

protocolVersion

string

Yes

The MCP protocol version supported by the server.

servers

[Server Object]

A list of server objects used to add one or more target endpoints for the MCP server.

capabilities

Capabilities Object

Server capabilities including supported features like logging, prompts, resources, and tools.

tools

[Tool Object]

Array of tools provided by the MCP server.

resources

[Resource Object]

Array of resources provided by the MCP server.

prompts

[Prompt Object]

Array of prompts provided by the MCP server.

Capabilities Object

Property

Type

Description

logging

object

Logging capabilities configuration. Empty object indicates basic logging support.

prompts

object

Prompt capabilities configuration with optional listChanged boolean property.

resources

object

Resource capabilities configuration with optional subscribe and listChanged boolean properties.

tools

object

Tool capabilities configuration with optional listChanged boolean property.

Tool Object

Property

Type

Required

Description

name

string

Yes

The name of the tool.

title

string

Title of the tool.

description

string

Yes

Description of what the tool does.

tags

[string]

Tags for the tool.

inputSchema

object

JSON Schema describing the expected input parameters for the tool.

outputSchema

object or string

JSON Schema describing the tool's output, or a reference to a schema component.

security

[object]

Security requirements for the tool, following OpenAPI security scheme format.

Property

Type

Required

Description

name

string

Yes

The name of the resource.

description

string

Description of the resource.

uri

string

URI template for accessing the resource.

mimeType

string

MIME type of the resource content.

Prompt Object

Property

Type

Required

Description

name

string

Yes

The name of the prompt.

title

string

Title of the prompt.

description

string

Description of the prompt.

arguments

[Argument Object]

Array of arguments for the prompt.

Argument Object

Property

Type

Required

Description

name

string

Yes

The name of the argument.

description

string

Description of the argument.

required

boolean

Whether the argument is required.

Example

The following example shows an OpenAPI description with an x-mcp extension that defines an MCP server with OAuth2 security, multiple tools, and schema components:

Code

openapi: 3.2.0
info:
  version: 1.0.0
  title: API Clients MCP
  license:
    name: MIT
servers:
  - url: http://localhost:8080/mcp

paths: {}

x-mcp:
  protocolVersion: "2025-06-18"
  capabilities:
    logging: {}
    prompts:
      listChanged: true
    resources:
      subscribe: true
    tools:
      listChanged: true
  tools:
    - name: clients/get
      description: Get a list of clients with all scopes in a service domain.
      inputSchema:
        type: object
        properties:
          clientId:
            type: string
            description: The ID of the client to get.
      outputSchema:
        $ref: "#/components/schemas/Client"
      security:
        - OAuth2:
            - read
    - name: clients/list
      description: Get a list of clients with all scopes in a service domain.
      inputSchema:
        type: object
        properties:
          paginationToken:
            type: string
            description: The pagination token to get the next page of clients.
      outputSchema:
        type: object
        properties:
          clients:
            type: array
            items:
              $ref: "#/components/schemas/Client"
          paginationToken:
            type: string
            description: The pagination token to get the next page of clients.
  resources: []

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: http://localhost:8080/mcp/token
          scopes:
            read: Read access
            write: Write access
  schemas:
    Client:
      type: object
      properties:
        clientId:
          type: number
          description: The ID of the client.
        scopes:
          type: array
          items:
            type: string
          description: The scopes of the client.
      required:
        - clientId
        - scopes

Edit this page

Last modified on April 24, 2026