Skip to content
Last updated

Model Context Protocol server

Model Context Protocol (MCP) is a standard that enables applications to provide context to large language models (LLMs). With MCP servers, AI assistants can retrieve additional information relevant to a user's query.

Realm provides built-in MCP server capabilities that expose your API Docs to AI assistants.

Benefits

  • Real-time API guidance — users receive accurate, contextual help about API endpoints and operations.
  • Secure API access — AI assistants can make authenticated requests to act on behalf of a user.
  • Dynamic documentation — AI assistants can extract and explain API reference content based on user needs.

Docs MCP server

Use the Docs MCP server to explore and discover APIs in your project. For the current MCP endpoint details, authentication semantics, server metadata, and tool schemas, see the Docs MCP reference.

The MCP server also includes a submit-feedback tool. An AI agent calls it when a page it relied on is incorrect, outdated, confusing, or incomplete. The report appears on the Reunite Feedback page with the MCP origin, the page, the agent name, and the feature involved. An agent can only report a page it has access to. Set feedback.hide to true to remove the tool together with the feedback form.

MCP server card

The MCP server card is a standardized JSON document that lets agents discover the Docs MCP server: its tools, transport endpoint, and capabilities. The discovery is a single request that follows the Model Context Protocol server-card format. It is available at /.well-known/mcp/server-card.json when the MCP server is enabled.

GET https://example.com/.well-known/mcp/server-card.json

The following example response describes a login-protected server that also publishes skills:

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/mcp-server-card/v1.json",
  "version": "1.0",
  "protocolVersion": "2025-06-18",
  "serverInfo": {
    "name": "Docs MCP server",
    "title": "Docs MCP server",
    "version": "2026-07-13"
  },
  "description": "Redocly Cafe documentation.",
  "documentationUrl": "https://example.com/",
  "transport": {
    "type": "streamable-http",
    "endpoint": "/mcp"
  },
  "capabilities": {
    "logging": {},
    "tools": { "listChanged": true },
    "resources": { "listChanged": true },
    "completions": {}
  },
  "authentication": {
    "required": true,
    "schemes": ["bearer", "oauth2"]
  },
  "tools": ["dynamic"]
}

The card lists the server's tools, declares its /mcp transport endpoint, and states its authentication requirements when the server requires login. When your project publishes agent skills, the card's capabilities advertise resource support so agents know to list them.

Restrict access to the MCP server

Control which teams can access the MCP server with the rbac.features.mcp option, the same way rbac.features.aiSearch controls access to AI search.

In the following example, only members of the Developers team can access the MCP server:

redocly.yaml
access:
  rbac:
    features:
      mcp:
        Developers: read

When a team-based role is set for the mcp feature, only teams with a role other than none can access the MCP server. Users must sign in unless the anonymous team is granted such a role, either directly or through the * wildcard. The wildcard covers all teams that are not listed explicitly, including anonymous. When the anonymous team has no access, requests without a valid token receive a 401 response. Authenticated users who don't belong to an allowed team receive a 403 response.

For more details, see the RBAC configuration reference.

Connect an AI agent to the MCP server

After you enable the Docs MCP server in configuration, it is available at /mcp on your project root URL. For example: https://example.com/mcp.

Use the MCP server

Users can connect their preferred AI tools that support MCP (for example, Cursor, Claude Code and VS Code) to your MCP server.

  1. 1

    Enable the MCP server in your configuration.

  2. 2

    Copy your MCP server URL and add it to your tool.

After connecting, the tool can access your OpenAPI documentation.

Connect Cursor to the MCP server

  1. 1

    In Cursor, open the command palette.

    • macOS: Command + Shift + P
    • Windows/Linux: Ctrl + Shift + P
  2. 2

    Type "Open MCP settings" in the command palette.

  3. 3

    Select "Add custom MCP".

Cursor opens the mcp.json file.

Configure the MCP server

  1. 1

    In mcp.json, add your server configuration:

    {
  "mcpServers": {
    "example-mcp": {
      "url": "https://example.com/mcp"
    }
  }
}

    Optionally, you can also pass additional headers that will be sent with each request:

    {
  "mcpServers": {
    "example-mcp": {
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Basic MTIzOjEyMw=="
      }
    }
  }
}
  2. 2

    Save the mcp.json file.

  3. 3

    Return to MCP settings and confirm the connection. If authentication is required, select Needs login and complete the sign‑in flow. After connecting, Cursor displays the list of available tools.

Test the Cursor connection

In Cursor chat (Agent mode), ask a question that triggers an MCP tool.

Public endpoint for anonymous users

When RBAC restricts content, the /mcp endpoint requires authentication and anonymous users cannot browse the content that RBAC marks public. To keep public content reachable for AI tools without a login, enable the public endpoint:

mcp:
  docs:
    publicEndpoint: true

The MCP server then also serves /mcp-public on your project root URL. Requests to it are never challenged for authentication, any provided credentials are ignored, and the served APIs and search results include only content available to the anonymous team. The /mcp endpoint keeps working as before for authenticated users.

Everything your RBAC rules grant to the anonymous team becomes reachable over /mcp-public without a login. Review these rules before you enable the endpoint.

If you restrict the MCP server itself with the rbac.features.mcp configuration, it must grant access to the anonymous team, or the /mcp-public endpoint is not registered and the build logs a note.

The public endpoint is only served when /mcp requires authentication and the anonymous team can reach some content. When the project has no protected content, /mcp already serves anonymous users, so /mcp-public is not registered and the build logs a note instead. A project that uses requiresLogin without rbac rules has no public content, so /mcp-public is not registered either.

Users discover the public endpoint in three ways:

  • A browser visit to /mcp-public displays the same setup page as /mcp, with connection snippets that point at the public endpoint and a note that it serves public content only.
  • The two setup pages link to each other: the /mcp page links to the public endpoint, and the /mcp-public page links back to the main endpoint.
  • When an unauthenticated MCP client connects to the restricted /mcp endpoint, the 401 response body mentions the /mcp-public URL.

Resources

Agent skills