SKILL

Overview

Use this skill to get the readme MCP server working and then use that server as the primary source of truth for ReadMe tasks.

Available Tools

When the readme server is configured, these are the high-level actions available through the ReadMe MCP integration:

• list-specs: list the available OpenAPI specs exposed through ReadMe.
• search-endpoints: search paths, operations, and schemas when you do not yet know the exact endpoint.
• list-endpoints: enumerate all paths and HTTP methods for a specific spec.
• get-endpoint: inspect one endpoint in detail, including parameters, security schemes, and servers.
• execute-request: send an API request using a HAR-shaped payload against a selected ReadMe spec.
• draft-changelog: generate a polished changelog draft from merged PRs or git history for publishing in ReadMe.
• search: search ReadMe guide pages and docs content by keyword.
• fetch: retrieve a specific guide page after locating its id with search.
• update-docs: start the docs update flow when the task requires documentation changes.

Prefer discovery tools first (list-specs, search-endpoints, search, list-endpoints), then detailed inspection (get-endpoint, fetch), and only then execution or updates (execute-request, draft-changelog, update-docs) when the task calls for it.

Required Workflow

Step 0: Ensure the readme server is configured

If the readme server is unavailable, set it up before doing substantive work:

1. Ask the user for a ReadMe API key if they have not provided one.
2. Configure the MCP server for the user's tool:

Claude Code:

export README_API_KEY='...'
claude mcp add readme --transport http https://docs.readme.com/mcp --header "Authorization: Basic $README_API_KEY"

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "readme": {
      "url": "https://docs.readme.com/mcp",
      "headers": {
        "Authorization": "Basic <README_API_KEY>"
      }
    }
  }
}

Windsurf:

{
  "mcpServers": {
    "readme": {
      "serverUrl": "https://docs.readme.com/mcp",
      "headers": {
        "Authorization": "Basic <README_API_KEY>"
      }
    }
  }
}

Other MCP clients: The ReadMe MCP server is available at https://docs.readme.com/mcp via HTTP transport. Authentication requires a ReadMe API key passed as a Basic auth header.

3. Tell the user to restart their tool after adding the server or changing the API key.
4. Continue the task only after the server is available, or clearly state that setup is incomplete.

Do not commit API keys into files. Prefer environment variables.

Step 1: Clarify the ReadMe task

Determine whether the user wants:

• MCP setup or troubleshooting
• Documentation lookup
• API or schema guidance
• Content or project operations exposed through the MCP server

Ask for missing context only when it blocks progress.

Step 2: Use MCP first

Once the server is available:

• Prefer the readme server over manual browsing for ReadMe-specific work.
• Read first and mutate second.
• Confirm intent before destructive or user-visible changes.
• Do not invent tool names or capabilities; inspect what the server exposes in the current environment.

Step 3: Close with the actual outcome

Summarize what was configured or changed, note any remaining blockers, and tell the user if a restart or re-run is required.

Troubleshooting Rules

• If setup fails, capture the exact error and check whether the API key is present in the environment.
• If the remote server is reachable but tool calls are absent, verify that the readme server was added successfully and that the tool was restarted.
• If tool calls fail with authentication errors, verify the API key is valid and being passed correctly as a Basic auth header.