Skip to content

Commit 2fac732

Browse files
adamaltmanRomanHotsiy
adamaltman
and
RomanHotsiy
committed
docs(project): add x-mcp docs (#18238)
Co-authored-by: Roman Hotsiy <[email protected]> remoteId: rem_01jwbtfqhbbam07z9j9m0etng6 remoteUpdateId: grupd_01k73cf3yskqqazv78rv2m6xqv branchName: main commitSha: 08d5495bdef490e3ced2f967c5f1c48decfa9c3b commitUrl: Redocly/redocly@08d5495
1 parent 460f8f4 commit 2fac732

File tree

4 files changed

+368
-0
lines changed

4 files changed

+368
-0
lines changed

‎docs/realm/content/api-docs/openapi-extensions/images/mcp-docs-example.png‎

37.1 KB
Loading

‎docs/realm/content/api-docs/openapi-extensions/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ The list of extensions supported in OpenAPI by Redoc is as follows:
1111
- [x-displayName](./x-display-name.md) - Use a human-friendly display name for a tag.
1212
- [x-enumDescriptions](./x-enum-descriptions.md) - Readable labels for enum values.
1313
- [x-hideReplay](./x-hide-replay.md) - Disable the Replay for the specific operation.
14+
= [x-mcp](./x-mcp.md) - Document MCP servers and tools.
1415
- [x-metadata](./x-metadata.md) - Add custom metadata at the top of the info section.
1516
- [x-rbac](x-rbac.md) - Control access to OpenAPI objects.
1617
- [x-traitTag](./x-trait-tag.md) - Indicate tags that label operations rather than grouping them.

‎docs/realm/content/api-docs/openapi-extensions/x-mcp.md‎

Lines changed: 365 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,365 @@
1+
# OpenAPI extension: `x-mcp`
2+
3+
{% admonition type="warning" name="Beta feature" %}
4+
This feature is currently experimental and may be subject to changes.
5+
6+
Currently, only the `tools` section is included in the generated documentation.
7+
{% /admonition %}
8+
9+
Use `x-mcp` to document MCP (Model Context Protocol) servers for consumers.
10+
11+
## Location
12+
13+
The `x-mcp` extension can be added to Root Object.
14+
The root is the outer most level of the OpenAPI description.
15+
16+
## Options
17+
18+
{% table %}
19+
20+
- Option
21+
- Type
22+
- Description
23+
24+
---
25+
26+
- x-mcp
27+
- [MCP object](#mcp-object)
28+
- MCP server description and configuration.
29+
30+
{% /table %}
31+
32+
### MCP object
33+
34+
{% table %}
35+
36+
- Option
37+
- Type
38+
- Description
39+
40+
---
41+
42+
- protocolVersion
43+
- string
44+
- **REQUIRED.** The MCP protocol version supported by the server.
45+
46+
---
47+
48+
- servers
49+
- [ [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#serverObject) ]
50+
- A list of server objects used to add one or more target endpoints for the MCP server.
51+
52+
---
53+
54+
- capabilities
55+
- [Capabilities object](#capabilities-object)
56+
- Server capabilities including supported features like logging, prompts, resources, and tools.
57+
58+
---
59+
60+
- tools
61+
- [ [Tool object](#tool-object) ]
62+
- Array of tools provided by the MCP server.
63+
64+
---
65+
66+
- resources
67+
- [ [Resource object](#resource-object) ]
68+
- Array of resources provided by the MCP server.
69+
70+
---
71+
72+
- prompts
73+
- [ [Prompt object](#prompt-object) ]
74+
- Prompt capabilities configuration with optional `listChanged` boolean property.
75+
76+
{% /table %}
77+
78+
### Capabilities object
79+
80+
{% table %}
81+
82+
- Option
83+
- Type
84+
- Description
85+
86+
---
87+
88+
- logging
89+
- object
90+
- Logging capabilities configuration. Empty object indicates basic logging support.
91+
92+
---
93+
94+
- prompts
95+
- object
96+
- Prompt capabilities configuration with optional `listChanged` boolean property.
97+
98+
---
99+
100+
- resources
101+
- object
102+
- Resource capabilities configuration with optional `subscribe` and `listChanged` boolean properties.
103+
104+
---
105+
106+
- tools
107+
- object
108+
- Tool capabilities configuration with optional `listChanged` boolean property.
109+
110+
{% /table %}
111+
112+
### Tool object
113+
114+
{% table %}
115+
116+
- Option
117+
- Type
118+
- Description
119+
120+
---
121+
122+
- name
123+
- string
124+
- **REQUIRED.** The name of the tool.
125+
126+
---
127+
128+
- title
129+
- string
130+
- Title of the tool.
131+
132+
---
133+
134+
- description
135+
- string
136+
- **REQUIRED.** Description of what the tool does.
137+
138+
---
139+
140+
- tags
141+
- [ string ]
142+
- Tags for the tool.
143+
144+
---
145+
146+
- inputSchema
147+
- object
148+
- JSON Schema describing the expected input parameters for the tool.
149+
150+
---
151+
152+
- outputSchema
153+
- object | string
154+
- JSON Schema describing the tool's output, or a reference to a schema component.
155+
156+
---
157+
158+
- security
159+
- [ object ]
160+
- Security requirements for the tool, following OpenAPI security scheme format.
161+
162+
{% /table %}
163+
164+
### Resource object
165+
166+
{% table %}
167+
168+
- Option
169+
- Type
170+
- Description
171+
172+
---
173+
174+
- name
175+
- string
176+
- **REQUIRED.** The name of the resource.
177+
178+
---
179+
180+
- description
181+
- string
182+
- Description of the resource.
183+
184+
---
185+
186+
- uri
187+
- string
188+
- URI template for accessing the resource.
189+
190+
---
191+
192+
- mimeType
193+
- string
194+
- MIME type of the resource content.
195+
196+
{% /table %}
197+
198+
199+
### Prompt object
200+
201+
{% table %}
202+
203+
- Option
204+
- Type
205+
- Description
206+
207+
---
208+
209+
- name
210+
- string
211+
- **REQUIRED.** The name of the prompt.
212+
213+
---
214+
215+
- title
216+
- string
217+
- Title of the prompt.
218+
219+
---
220+
221+
- description
222+
- string
223+
- Description of the prompt.
224+
225+
---
226+
227+
- arguments
228+
- [ [Argument object](#argument-object) ]
229+
- Array of arguments for the prompt.
230+
231+
{% /table %}
232+
233+
### Argument object
234+
235+
{% table %}
236+
- Option
237+
- Type
238+
- Description
239+
240+
---
241+
242+
- name
243+
- string
244+
- **REQUIRED.** The name of the argument.
245+
246+
---
247+
248+
- description
249+
- string
250+
- Description of the argument.
251+
252+
---
253+
254+
- required
255+
- boolean
256+
- Whether the argument is required.
257+
258+
{% /table %}
259+
260+
## Examples
261+
262+
### `x-mcp` example
263+
264+
Metadata keys can be any string.
265+
The values can be any primitive type, or a list of strings.
266+
267+
The following is an example of an `x-mcp` described within an OpenAPI description file:
268+
269+
```yaml {% title="api-clients-mcp.yaml" %}
270+
openapi: 3.2.0
271+
info:
272+
version: 1.0.0
273+
title: API Clients MCP
274+
license:
275+
name: MIT
276+
servers:
277+
- url: http://localhost:8080/mcp
278+
279+
paths: {} # no paths
280+
281+
x-mcp:
282+
protocolVersion: '2025-06-18'
283+
capabilities:
284+
logging: {}
285+
prompts:
286+
listChanged: true
287+
resources:
288+
subscribe: true
289+
tools:
290+
listChanged: true
291+
tools:
292+
# this is the output of the list/tools call to the MCP
293+
- name: clients/get
294+
description: Get a list of clients with all scopes in a service domain.
295+
inputSchema:
296+
type: object
297+
properties:
298+
clientId:
299+
type: string
300+
description: The ID of the client to get.
301+
outputSchema:
302+
$ref: '#/components/schemas/Client'
303+
# we added the OAuth2 security scheme
304+
security:
305+
- OAuth2:
306+
scopes:
307+
read: Read access
308+
- name: clients/list
309+
description: Get a list of clients with all scopes in a service domain.
310+
inputSchema:
311+
type: object
312+
properties:
313+
paginationToken:
314+
type: string
315+
description: The pagination token to get the next page of clients.
316+
outputSchema:
317+
type: object
318+
properties:
319+
clients:
320+
type: array
321+
items:
322+
$ref: '#/components/schemas/Client'
323+
paginationToken:
324+
type: string
325+
description: The pagination token to get the next page of clients.
326+
resources: []
327+
328+
components:
329+
securitySchemes:
330+
OAuth2:
331+
type: oauth2
332+
flows:
333+
clientCredentials:
334+
tokenUrl: http://localhost:8080/mcp/token
335+
scopes:
336+
read: Read access
337+
write: Write access
338+
schemas:
339+
Client:
340+
type: object
341+
properties:
342+
clientId:
343+
type: number
344+
description: The ID of the client.
345+
scopes:
346+
type: array
347+
items:
348+
type: string
349+
description: The scopes of the client.
350+
required:
351+
- clientId
352+
- scopes
353+
```
354+
355+
The data is presented similar to the following screenshot:
356+
357+
{% img
358+
alt="Example MCP docs"
359+
src="./images/mcp-docs-example.png"
360+
withLightbox=true
361+
/%}
362+
363+
## Resources
364+
365+
- **[Supported OpenAPI extensions](./index.md)** - Complete list of all OpenAPI extensions supported by Redocly for enhanced API documentation

‎docs/realm/sidebars.yaml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -240,6 +240,8 @@
240240
label: x-enumDescriptions
241241
- page: content/api-docs/openapi-extensions/x-additional-properties-name.md
242242
label: x-additionalPropertiesName
243+
- page: content/api-docs/openapi-extensions/x-mcp.md
244+
label: x-mcp
243245
- page: content/api-docs/openapi-extensions/x-metadata.md
244246
label: x-metadata
245247
- page: content/api-docs/openapi-extensions/x-hide-replay.md

0 commit comments

Comments
 (0)