MCP

Your MCP server gives AI coding assistants — Cursor, Claude Code, VS Code Copilot — a live connection to your API spec and documentation. Once enabled, AI tools connect to your MCP URL and can list endpoints, inspect schemas, make API calls, and search your docs directly, so they generate accurate code instead of guessing at your endpoints and parameters.

Getting Started

1. Open your project in ReadMe.
2. Open AI → MCP and toggle MCP Server on.
3. Share the URL with your users: https://your-project.readme.io/mcp

Click Generate MCP Template in the MCP panel to create a ready-to-publish guide page with connection instructions for Cursor, Claude Desktop, VS Code, and more.

Configure

Available tools

OpenAPI tools — available on all plans:

Documentation tools — require AI Booster Pack:

Authentication

Public projects — no auth needed. Users connect with just the URL.

API execution — the execute-request tool forwards headers from the user's MCP config to your API. If your API requires an Authorization header:

{
  "mcpServers": {
    "My API": {
      "url": "https://your-project.readme.io/mcp",
      "headers": {
        "Authorization": "Bearer user-api-key-here"
      }
    }
  }
}

Private projects — users must pass an x-readme-auth header:

For clients that don't support custom headers (like the Claude web UI), pass the same value as a token query parameter instead:

https://your-project.readme.io/mcp?token=your-site-password
https://your-project.readme.io/mcp?token=rdme_xxxxxxxxxxxx

MCP server URLs

The standard URL is https://your-project.readme.io/mcp. Append parameters to customize behavior:

Custom tools

Define your own tools that users' AI assistants can call. Go to AI → MCP → Custom Tools and click New Tool.

Each tool requires a title, a description (when should the AI use it), and a body (instructions to follow). Tool titles cannot match built-in tool names.

Controlling which endpoints are exposed

All endpoints in your OpenAPI spec are available by default. Toggle individual endpoints on or off in AI → MCP → Enabled MCP Routes.

Use Cases

These examples use the Petstore API to show what users can do with your MCP server.

Build an API client

A developer connects their coding assistant to your MCP server and prompts:

Write a Python script that lists all pets with status "available"
and lets me add a new pet by name.

The AI calls list-endpoints to discover the relevant paths, get-endpoint to read the schemas, and generates working code with correct fields and auth.

import requests

BASE_URL = "https://petstore.swagger.io/v2"
API_KEY  = "your-api-key"

def list_available_pets():
    resp = requests.get(
        f"{BASE_URL}/pet/findByStatus",
        params={"status": "available"},
        headers={"api_key": API_KEY},
    )
    resp.raise_for_status()
    return resp.json()

def add_pet(name: str, status: str = "available") -> dict:
    payload = {"name": name, "status": status, "photoUrls": []}
    resp = requests.post(
        f"{BASE_URL}/pet",
        json=payload,
        headers={"api_key": API_KEY, "Content-Type": "application/json"},
    )
    resp.raise_for_status()
    return resp.json()

Explore an unfamiliar API

I've never used this API before. Use MCP tools to give me a quick-start
guide: what endpoints exist, what auth I need, and a curl example.

The AI calls list-endpoints and assembles an overview without you writing any additional documentation.

Generate tests from your spec

Look at the POST /pet endpoint and generate a Jest test suite covering:
a successful create, missing required fields, and an invalid status value.

The AI reads the request body schema, finds enum values for status, and writes tests against the actual contract.

Automated API monitoring

Check that the API is behaving correctly:
1. Call GET /pet/1 and verify the response matches the schema
2. Try POST /pet with an invalid status and confirm it returns a 400
3. Report any discrepancies

The agent uses get-endpoint to know what a valid response looks like, then execute-request to make the calls and compare.

FAQ