# Connect an agent

Add the realpng MCP server to Claude Code, Codex, Cursor or Claude Desktop with one URL and your API key.

The realpng MCP server gives your agent four tools to check and optimize images, listed in [MCP tools](/docs/mcp/tools). [API or MCP](/docs#api-or-mcp) says when to use the REST API instead.

## Before you start

You need an API key from your [account page](/account#keys) on a plan with API access. [Authentication](/docs/authentication) covers keys and which plans include the API.

Name the key after the agent. [Usage](/account#usage) lists every check and optimization with the name of the key that ran it and marks it MCP. Right after you create a key, **Set up MCP with this key** opens the [MCP section](/account#mcp) with that key filled in.

## Add the server

Each config points at the realpng MCP server and sends your key in the `X-API-Key` header, as [Authentication](/docs/authentication) describes. The server is remote and speaks Streamable HTTP, so if a client asks for a transport, pick HTTP.

### Claude Code

```bash title="Terminal"
claude mcp add --transport http realpng \
  https://realpng.com/mcp \
  --header "X-API-Key: rp_live_YOUR_KEY"
```

### Codex

```toml title="~/.codex/config.toml"
[mcp_servers.realpng]
url = "https://realpng.com/mcp"
http_headers = { "X-API-Key" = "rp_live_YOUR_KEY" }
```

### Cursor

[Add to Cursor](https://cursor.com/en/install-mcp?name=realpng&config=eyJ1cmwiOiJodHRwczovL3JlYWxwbmcuY29tL21jcCIsImhlYWRlcnMiOnsiWC1BUEktS2V5IjoicnBfbGl2ZV9ZT1VSX0tFWSJ9fQ%3D%3D)

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "realpng": {
      "url": "https://realpng.com/mcp",
      "headers": {
        "X-API-Key": "rp_live_YOUR_KEY"
      }
    }
  }
}
```

### Claude Desktop

```json title="claude_desktop_config.json"
{
  "mcpServers": {
    "realpng": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://realpng.com/mcp",
        "--header",
        "X-API-Key:${REALPNG_API_KEY}"
      ],
      "env": {
        "REALPNG_API_KEY": "rp_live_YOUR_KEY"
      }
    }
  }
}
```

Replace `rp_live_YOUR_KEY` with your key. Then start a new session or restart the app, since clients load the tool list when they start.

### Where each config goes

- **Claude Code**: run the command in a terminal. It adds realpng to the current project. Add `--scope user` to add it to every project.
- **Codex**: add it to `~/.codex/config.toml`.
- **Cursor**: add it to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for every project. **Add to Cursor** installs the same config with `rp_live_YOUR_KEY` in it, so replace that in Cursor's MCP settings.
- **Claude Desktop**: add it to `claude_desktop_config.json`, opened from Settings, then Developer, then Edit Config. It runs the `mcp-remote` bridge with `npx`, so Node.js must be installed. Put your key in the `REALPNG_API_KEY` entry, then quit and reopen Claude Desktop.

If a JSON file already lists other servers, add the realpng entry beside them.

> [!WARNING]
> Each config holds your key in plain text. Keep `.cursor/mcp.json` and the other config files out
> of shared repos. If a key leaks, revoke it on your [account page](/account#keys).

## Confirm it works

Ask your agent to list its realpng tools. It should name `audit_image`, `request_upload`, `process_image` and `get_processing_result`. Listing the tools spends no credits.

You can also ask it to check an image by URL. That runs a real check and spends its credits, as [Credits and limits](/docs/credits-and-limits) shows.

### If it does not connect

A missing, wrong or revoked key fails before any tool runs, and so do a plan without API access and a failed payment. The agent then shows a failed connection, and some clients, Claude Code among them, may offer to sign in. realpng has no sign in for MCP, so check the key and your plan instead. [Errors](/docs/errors) lists each cause and its fix.

## Credits and limits

MCP spends the same credits as the API and shares its limits, as [Credits and limits](/docs/credits-and-limits#rate-limits) explains. `audit_image` spends a check's credits and `process_image` an optimization's, while `request_upload` and `get_processing_result` spend none.

- [MCP tools](/docs/mcp/tools): The four tools and what each one takes.

- [Upload a local file](/docs/guides/upload-a-local-file): Send a file on disk without putting its bytes through a tool call.

- [Credits and limits](/docs/credits-and-limits): What each call costs and the limits on your plan.