MCP

Your MCP server gives AI assistants and agents a live connection to your API spec and documentation. It works with any MCP client, including Cursor, Claude Code, VS Code Copilot, ChatGPT, Gemini CLI, and agents you build yourself. 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

Your hub's AI dropdown gives readers quick options to connect to Cursor, VS Code, or copy the MCP config directly. You can also write a custom guide page with connection instructions if you'd like to tailor the experience.

MCP gives agents tools to call. LLMs.txt gives agents that read before they act a map of your docs, and most projects turn on both. Agents that fetch your pages directly get clean Markdown through Markdown for Agents. For how all of these fit together, see AI-Ready Docs.

Configure

Available tools

OpenAPI tools — available on all plans:

Documentation tools — require AI Booster Pack:

Utility tools — Functionality outside the docs:

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.

Connect From AI Tools

Your MCP server works with any MCP client, so connecting is a matter of giving the client your MCP URL. The AI Dropdown already handles Cursor and VS Code, and the sections below show setup for a few other common clients. Each client changes its menus often, so every section links to that client's own setup guide.

⚠️

Treat any URL with a token as a secret

Clients that can't send custom headers connect to private projects with ?token= in the URL. Anyone who has that URL can read your private docs, so share it the way you'd share a password.

ChatGPT

ChatGPT connects to remote MCP servers as a custom connector once Developer mode is on. Availability depends on your ChatGPT plan and workspace settings.

1. In ChatGPT, open Settings and turn on Developer mode.
2. Add a new connector and paste your MCP URL: https://your-project.readme.io/mcp
3. For a private project, add your token to the URL: https://your-project.readme.io/mcp?token=rdme_xxxxxxxxxxxx

ChatGPT connectors don't send custom headers, so execute-request calls reach your API without an Authorization header. Read-only tools like list-endpoints and get-endpoint work normally. See OpenAI's MCP guide for current menu names.

Gemini CLI

Gemini CLI reads MCP servers from ~/.gemini/settings.json. Use the httpUrl field for a remote server:

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

Or add it from the terminal:

gemini mcp add --transport http my-api https://your-project.readme.io/mcp

For a private project, add an x-readme-auth header with the value from the Authentication table. See Google's Gemini CLI MCP guide for every option.

Custom Agents

If you're building your own agent, point any MCP client library at your MCP URL and pass the same headers described in Authentication. This example uses the official MCP Python SDK (v2, installed with pip install mcp) to connect and list the available tools:

import asyncio

import httpx2

from mcp import Client
from mcp.client.streamable_http import streamable_http_client

MCP_URL = "https://your-project.readme.io/mcp"


async def main() -> None:
    # Headers are only needed if your API requires them
    async with httpx2.AsyncClient(
        headers={"Authorization": "Bearer user-api-key-here"},
    ) as http_client:
        transport = streamable_http_client(MCP_URL, http_client=http_client)
        async with Client(transport) as client:
            result = await client.list_tools()
            for tool in result.tools:
                print(tool.name)


asyncio.run(main())

The script prints the tool names from Available tools, such as list-endpoints and get-endpoint. Agent frameworks that accept a remote MCP server URL, including the OpenAI Responses API and Anthropic's MCP connector, can use the same URL.

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