Docs

Getting started

Sign in at app.readr.sh with GitHub and create an API key. Send it as a bearer token: Authorization: Bearer YOUR_KEY. The examples below read it from READR_API_KEY.

MCP

The MCP server is at https://api.readr.sh/mcp and has one tool, read, which takes a URL.

Claude Code

claude mcp add --transport http readr https://api.readr.sh/mcp \
  --header "Authorization: Bearer $READR_API_KEY"

Codex

~/.codex/config.toml

[mcp_servers.readr]
url = "https://api.readr.sh/mcp"
bearer_token_env_var = "READR_API_KEY"

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "readr": {
      "url": "https://api.readr.sh/mcp",
      "headers": { "Authorization": "Bearer ${env:READR_API_KEY}" }
    }
  }
}

VS Code

.vscode/mcp.json

{
  "servers": {
    "readr": {
      "type": "http",
      "url": "https://api.readr.sh/mcp",
      "headers": { "Authorization": "Bearer ${input:readr-key}" }
    }
  },
  "inputs": [
    { "id": "readr-key", "type": "promptString", "description": "readr.sh API key", "password": true }
  ]
}

HTTP API

POST https://api.readr.sh/v1/read with a JSON body:

curl https://api.readr.sh/v1/read \
  -H "Authorization: Bearer $READR_API_KEY" \
  -d '{"url": "https://example.com"}'

The response:

{
  "url": "https://example.com/",
  "title": "Example Domain",
  "status": 200,
  "markdown": "This domain is for use in documentation examples…"
}

`url`	The page's address after redirects.
`title`	The page title.
`status`	The HTTP status the page returned. Left out when the site didn't send one.
`markdown`	The page content.

Errors

Errors come back as JSON with a message, a code, and a request ID to quote if you contact support.

{ "error": "Invalid API key.", "code": "unauthorized", "request_id": "…" }

Status	Code	What to do
400	`invalid_request`	Send a JSON body with a `url`.
400	`invalid_url`	Use a public http or https URL.
401	`unauthorized`	Check the API key.
402	`no_reads_left`	Upgrade or buy more reads.
429	`rate_limited`	Retry after the `Retry-After` seconds.
503	`capacity`	Retry after the `Retry-After` seconds.
500	`internal_error`	Retry, or contact support with the request ID.

Limits

Plan	Reads a month	Requests per second
Free	200	1
Starter	2,000	5
Pro	20,000	20

Limits apply per account, across all its keys. Extra reads bought on the pricing page are used once a month's reads run out.