Skip to content
Last updated

MCP server

Plans:ProScaleEnterprise

Model Context Protocol (MCP) is a standard that lets AI clients get context from external sources. Each project on a plan that includes the MCP server serves it at /mcp on the project root URL, for example https://example.com/mcp. The server lets AI clients search your documentation and read your API descriptions. It also gives your agent skills to AI clients as resources. To turn off the server, set mcp.hide to true.

What the server exposes

The AI client gets three MCP tools:

  • execute runs a script that calls the documentation functions.
  • describe-tools returns the signatures of the documentation functions.
  • submit-feedback reports a problem with a documentation page. On @redocly/realm 0.138 and earlier, this tool exists only as a function inside execute.

The script calls these documentation functions:

FunctionWhat it does
listApisLists the APIs of the project.
getEndpointsReturns all endpoints of an API.
getEndpointInfoReturns the details of one endpoint, for example its parameters, security, and examples.
getSecuritySchemesReturns the security schemes of an API.
getFullApiDescriptionReturns the full OpenAPI description of an API.
searchSearches the documentation.
listGraphqlApisLists the GraphQL APIs of the project. Only a project with GraphQL APIs has the GraphQL functions.
getGraphqlTypeListReturns the operations and types of a GraphQL schema as a list that you can filter.
getGraphqlTypeReturns the SDL of one GraphQL type, operation, or directive.
getGraphqlSchemaReturns the full GraphQL schema as SDL.
whoamiReturns information about the signed-in user. Only a server that requires sign-in has this function.

Function names use camelCase, and a script calls them on the tools object, for example tools.getEndpoints().

Tools mode

Some AI clients and AI client directories need one MCP tool for each function instead of a script. For these clients, add ?mode=tools to the server URL, for example https://example.com/mcp?mode=tools. The server then gives one tool for each documentation function, with the function name in kebab-case, for example get-endpoints, and the submit-feedback tool. This switch needs @redocly/framework 0.139 or later.

What your readers see

When readers open /mcp in a browser, they see a setup page with the steps to connect their AI client. By default, the page actions on each page let readers add the server to Claude, VS Code, or Cursor. Another page action copies the server URL. To add a connect button to a page, use the Connect MCP tag.

To customize the setup page, eject the layouts/McpNotAllowed.tsx component:

To eject in the Redocly editor:

  1. Select Editor on the left side navigation.
  2. In the Files section, select Theme components.
  3. In the layouts folder, select the eject icon next to McpNotAllowed.tsx.

The ejected component is placed at @theme/layouts/McpNotAllowed.tsx, where you can modify the layout, styling, and content of the page.

MCP server card

The server card lets AI clients and registries discover the server with one request. It is a JSON document in the MCP server card format, at /.well-known/mcp/server-card.json on the project root URL. The card names the server, gives the /mcp transport endpoint, and lists the MCP tools. When the server requires sign-in, the card states the authentication schemes. When your project publishes agent skills, the card advertises support for resources.

The following example shows the card of a server that requires sign-in. The name in the example comes from mcp.name. The example leaves out the instructions field and shows only the name and the title of each tool.

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/mcp-server-card/v1.json",
  "version": "1.0",
  "protocolVersion": "2025-11-25",
  "serverInfo": {
    "name": "Redocly Cafe",
    "title": "Redocly Cafe",
    "version": "2026-10-22"
  },
  "description": "Redocly Cafe documentation.",
  "documentationUrl": "https://example.com/",
  "transport": {
    "type": "streamable-http",
    "endpoint": "/mcp"
  },
  "capabilities": {
    "logging": {},
    "tools": { "listChanged": true }
  },
  "authentication": {
    "required": true,
    "schemes": ["bearer", "oauth2"]
  },
  "tools": [
    { "name": "execute", "title": "Query the docs with code" },
    { "name": "describe-tools", "title": "Get docs function signatures" },
    { "name": "submit-feedback", "title": "Submit feedback" }
  ]
}

The feedback tool

An AI client calls the submit-feedback tool to report a documentation page that is wrong or incomplete. The report contains the page, a summary of the problem, and the name of the AI client. The report can also contain details and the feature that the page documents. The report appears on the Feedback page in the Redocly platform. The server accepts a report only for a page that the AI client can access.

To remove the tool, set feedback.hide to true. This setting also removes the feedback form from your pages.

submit-feedback is the only built-in tool that writes. The other built-in tools only read, and no built-in tool changes your content. Custom tools run code that you write.

Hide content

Use these options to remove content from the MCP server results for all AI clients:

  • mcp.ignore removes the API descriptions and the pages that match glob patterns.
  • x-mcp.docs.hide keeps a path or an operation away from AI clients.
  • skills.hide removes the agent skills, and the server then has no skill resources.
  • skills.excludeFiles removes only the skills that match glob patterns.

These options are not access control. To restrict content to teams, see Control access to the MCP server.

Limits and what Redocly logs

By default, the server accepts 600 requests per minute and 20,000 requests per day from one client IP address. Above that, it returns HTTP 429 with a Retry-After header. The server accepts a request body of up to 1 MiB and returns HTTP 413 for a larger one. A tool call can have up to 10,000 array elements and object keys in total in its arguments. Above that, the AI client gets a tool error.

For each tool call, Redocly records the tool name, the duration, the response size, and the name and version of the AI client. Redocly also keeps a security audit log of tool calls.

The MCP server analytics in the Redocly platform show the requests and the tool calls of your project. For the details of these records, see What does Redocly log for MCP tool calls?.

Resources

Connect an AI client