# MCP server

Ranetrace hosts an MCP server, so an AI agent can read your errors, your website's monitor verdicts and your notification rules, and, if you allow it, change error states, notes and rules. The server runs on Ranetrace: there is nothing to install or run in your application.

- **Endpoint:** `https://api.ranetrace.com/mcp`
- **Transport:** Streamable HTTP
- **Authentication:** OAuth only

## How a connection is approved

You give your MCP client the server URL and nothing else. The client registers itself, opens your browser at Ranetrace's approval screen, and comes back with a credential of its own. There is no token to copy or paste.

The approval screen asks you two things:

- **Which website.** The connection reaches that one website and nothing else in your account.
- **Whether the agent may write.** Writes are off unless you turn them on. A read-only connection can look at the website's errors, notes and monitors, and your notification rules. Logs, events, traffic and website settings stay out of reach either way.

## Connect your client

### Claude on the web, desktop and mobile

Add Ranetrace as a custom connector and paste this URL. There is no header to fill in.

```text
https://api.ranetrace.com/mcp
```

### Claude Code

Run this in your terminal:

```bash
claude mcp add --transport http ranetrace https://api.ranetrace.com/mcp
```

The first time the agent uses the server, it opens your browser and asks you to approve the connection.

### ChatGPT

Turn on developer mode in ChatGPT's settings, create a connector, paste this URL and choose OAuth:

```text
https://api.ranetrace.com/mcp
```

Developer mode is on the Plus, Pro, Business, Enterprise and Edu plans, and on Business or Enterprise an admin may need to allow custom connectors first. ChatGPT asks you to confirm each change before it makes it.

### Codex

Run these in your terminal, in order:

```bash
codex mcp add ranetrace --url https://api.ranetrace.com/mcp
codex mcp login ranetrace
```

The login opens your browser to approve the connection. The Codex IDE extension reads the same config, so one setup covers both.

### Cursor

Add this to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a project:

```json
{
  "mcpServers": {
    "ranetrace": {
      "url": "https://api.ranetrace.com/mcp"
    }
  }
}
```

### VS Code

Add this to `.vscode/mcp.json` in a workspace, or to the `mcp.json` in your user profile. VS Code's own format uses a `servers` key with an `http` type:

```json
{
  "servers": {
    "ranetrace": {
      "type": "http",
      "url": "https://api.ranetrace.com/mcp"
    }
  }
}
```

Neither carries an `Authorization` header, because both clients run the approval for you.

### Gemini CLI

Run this in your terminal:

```bash
gemini mcp add --scope user --transport http ranetrace https://api.ranetrace.com/mcp
```

Then run `/mcp auth ranetrace` inside Gemini CLI to approve the connection.

### A machine with no browser

A script or custom agent on a server can ask for a device connection instead, through the OAuth device authorization grant. It shows you a short code, and you enter it at `https://app.ranetrace.com/oauth/device` on a device you are signed in on, where the same approval screen appears.

Each account has one device connection: approving a second device replaces the first. Today's MCP clients use the browser flow above.

## Manage your connections

Every connection is listed in your Ranetrace account under agent connections, at `https://app.ranetrace.com/user/profile/connections`. You can revoke any of them there. The same page carries these connect instructions.

## What the tools cover

Tools are named on the wire in kebab case, as listed below.

### Monitors

These work for any website Ranetrace monitors. No SDK is needed.

| Tool | What it answers |
|---|---|
| `get-monitor-status-tool` | Which of your monitors needs a look: every enabled monitor with its verdict, DNS included |
| `get-uptime-status-tool` | Up or down right now, uptime over the last 24 hours, and the recent outages |
| `get-performance-stats-tool` | The 24-hour average response time and where that time goes |
| `get-lighthouse-audit-tool` | The latest Lighthouse scores, metrics, trend and ranked opportunities |
| `get-certificate-status-tool` | HTTPS, whether browsers trust the certificate, and days until it expires |
| `get-domain-status-tool` | Registrar, registration expiry, DNSSEC and registrar locks |
| `get-broken-links-tool` | Broken links from the latest site audit, each with the page it was found on |

Every monitor tool answers verdict first: what was found, why it matters and what to do, the same guidance you read on the dashboard, followed by the raw measurements. A monitor that is switched off is reported as disabled rather than answered with old figures.

The connection already scopes each call to one website, so the monitor tools take no parameters. The exception is `get-broken-links-tool`: it lists 100 links per call and can be narrowed with `status_code` and `source_page`, walked with `cursor`, and switched with `redirects` to list internal links that redirect instead of broken ones. Its verdict and counts always describe the whole audit.

### Errors and notes

These answer only for an application that sends its errors to Ranetrace through one of the SDKs, [Laravel](/docs/installation) or [PHP](/docs/php-installation). JavaScript errors from a site's frontend come in through the same SDKs.

| Tool | What it answers |
|---|---|
| `latest-errors-tool` | The most recent PHP errors, open ones by default |
| `search-errors-tool` | Errors filtered by type, state and more, with free-text `query` over the message, class and file |
| `get-error-tool` | One PHP error in full, laid out for fixing it |
| `error-stats-tool` | PHP error statistics and trend over a period |
| `get-error-activity-tool` | The state history of one error: who resolved, ignored or snoozed it, and when |
| `list-notes-tool` | The investigation notes on an error |
| `get-note-tool` | One note in full |

### Notification rules

| Tool | What it answers |
|---|---|
| `get-notification-rules-tool` | Your notification rules, verdict first: it flags a key alert, such as website down, that is switched off |

Notification rules are account-wide. One set governs all your websites, so a change made through one website's connection affects every website you have.

### Write tools

A connection that may write can also use these:

| Tool | What it changes |
|---|---|
| `resolve-error-tool`, `reopen-error-tool` | Resolve an error, or reopen it |
| `ignore-error-tool`, `unignore-error-tool` | Ignore an error, or stop ignoring it |
| `snooze-error-tool`, `unsnooze-error-tool` | Snooze an error for a while, or end the snooze |
| `delete-error-tool`, `restore-error-tool` | Archive an error, or bring it back |
| `bulk-resolve-errors-tool`, `bulk-reopen-errors-tool`, `bulk-ignore-errors-tool`, `bulk-delete-errors-tool`, `bulk-restore-errors-tool` | The same for up to 50 errors at once, all or nothing |
| `create-note-tool`, `create-notes-tool` | Add one note, or up to 10, to an error |
| `update-note-tool`, `delete-note-tool` | Edit or archive a note an agent wrote. A note a person wrote is refused |
| `update-notification-rules-tool` | Change your notification rules, for all your websites |

## Changing something: search, then execute

The read tools are listed directly, and an agent calls them by name. The write tools are not listed one by one. They sit in a catalog behind two tools that a write-enabled connection lists next to the reads:

- `search_tools` takes a `query` and answers with the matching tools, each with its exact name and input schema. An empty query browses the whole catalog.
- `execute_tools` takes `calls`, a list of up to 10 tool calls by those exact names, and runs them in order, stopping at the first error.

Resolving an error, for example, is a search:

```json
{"query": "resolve error"}
```

and then an execute with the name the search returned:

```json
{"calls": [{"name": "resolve-error-tool", "arguments": {"error_id": "err_123", "type": "php"}}]}
```

A read-only connection lists the read tools only. It has no `search_tools` or `execute_tools`, so there is nothing for it to find or run.

## The ingest key is not an MCP credential

`RANETRACE_KEY` is the ingest key. It writes captured telemetry into Ranetrace and lives in your application's `.env`. It never reads data back out.

Sending it to the MCP endpoint, or sending an old static MCP token, returns a `401` with `error_code: MCP_OAUTH_REQUIRED`, and the message says how to reconnect over OAuth.

Nothing MCP-related goes in `.env`. If your application still has `RANETRACE_MCP_TOKEN` there, it is on a retired setup: connect your client as shown above and delete the variable.