# MCP


## Overview
The Report URI MCP endpoint implements the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants and LLM-powered tools to query your account data directly. Once connected, an AI assistant can retrieve reports, inspect Watch findings, check quota usage, and more — all through natural language.

The MCP endpoint uses the same API key as the [REST API](/integrations/api/).


## Getting Your API Key
Visit [API](https://report-uri.com/api/getKey/) in your account to generate an API key. The full key is only shown once — at the moment it is created or rotated. Store it securely; if you lose it you will need to rotate it to get a new one.

Personal account keys are prefixed `ruri_d_`. Team account keys are prefixed `ruri_t_`.


## Endpoint URL
    https://mcp.report-uri.com/


## Authentication
Pass your API key as a Bearer token in the `Authorization` header on every request.

    Authorization: Bearer ruri_d_YOUR_KEY_HERE


## Protocol
The endpoint implements [JSON-RPC 2.0](https://www.jsonrpc.org/specification) over HTTP, using MCP protocol version `2025-03-26`. All requests are `POST` to the endpoint URL with a JSON body.

**Standard MCP methods supported:**

- `initialize` — negotiate protocol version and capabilities
- `tools/list` — enumerate available tools
- `tools/call` — invoke a tool
- `prompts/list` — enumerate available prompts
- `prompts/get` — retrieve a prompt with arguments filled in
- `resources/list` — enumerate available documentation resources
- `resources/read` — read a documentation resource by URI

Notification methods (prefixed `notifications/`) return HTTP `202 Accepted` with no response body.


## Rate Limiting
The MCP endpoint shares the same rate limit as the REST API: **120 requests per 60-second window** per API key. Each tool call counts as one request.


## Connecting an MCP Client

### Claude Desktop
Add the following to your Claude Desktop configuration file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
    "mcpServers": {
        "report-uri": {
            "type": "http",
            "url": "https://mcp.report-uri.com/",
            "headers": {
                "Authorization": "Bearer ruri_d_YOUR_KEY_HERE"
            }
        }
    }
}
```

### Generic MCP client
Any MCP client that supports HTTP transport can connect using:

| Setting | Value |
|---------|-------|
| Transport | HTTP |
| URL | `https://mcp.report-uri.com/` |
| Auth header | `Authorization: Bearer ruri_d_YOUR_KEY_HERE` |
| Protocol version | `2025-03-26` |


## Request & Response Format

**Tool call request**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
        "name": "get_quota_usage"
    }
}
```

**Success response**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "result": {
        "content": [
            {
                "type": "text",
                "text": "{\"used\":142857,\"limit\":1000000}"
            }
        ]
    }
}
```

**Error response**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "error": {
        "code": -32602,
        "message": "Invalid params"
    }
}
```

**JSON-RPC error codes**

| Code | Meaning |
|------|---------|
| `-32700` | Parse error |
| `-32600` | Invalid request |
| `-32601` | Method not found |
| `-32602` | Invalid params |
| `-32603` | Internal error |


---

## Available Tools


### Account & Setup


#### get_account_info
Returns the account type, email address (personal accounts), or team ID and name (team accounts).

**Parameters:** none

**Request**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
        "name": "get_account_info"
    }
}
```

**Response**

```json
{
    "type": "personal",
    "email": "you@example.com"
}
```


#### get_quota_usage
Returns current monthly quota usage against the account limit.

**Parameters:** none

**Request**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
        "name": "get_quota_usage"
    }
}
```

**Response**

```json
{
    "used": 142857,
    "limit": 1000000
}
```


#### get_setup
Returns configured report URIs, Reporting API header value, NEL header value, and email addresses for DMARC and TLS-RPT reporting.

**Parameters:** none

**Request**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
        "name": "get_setup"
    }
}
```

**Response**

```json
{
    "reportUri": {
        "enforce": "https://abc123.report-uri.com/r/d/csp/enforce",
        "reportOnly": "https://abc123.report-uri.com/r/d/csp/reportOnly",
        "wizard": "https://abc123.report-uri.com/r/d/csp/wizard"
    },
    "reportingApi": {
        "group": "default",
        "max_age": 31536000,
        "endpoints": [
            { "url": "https://abc123.report-uri.com/a/d/g" }
        ],
        "include_subdomains": true
    },
    "nel": {
        "report_to": "default",
        "max_age": 31536000,
        "include_subdomains": true
    },
    "dmarc": "abc123@dmarc.report-uri.com",
    "tlsRpt": "abc123@tls-rpt.report-uri.com"
}
```


#### get_plan
Returns your current plan details including quota, data retention, and feature entitlements.

**Parameters:** none

**Request**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
        "name": "get_plan"
    }
}
```

**Response**

```json
{
    "plan": "ultimate2025",
    "name": "Ultimate",
    "status": "active",
    "reportQuota": 2000000,
    "collectHosts": 5,
    "dataRetentionDays": 90,
    "features": {
        "support": true,
        "teams": true,
        "blockedWatch": ["scriptWatch", "dataWatch", "frameWatch", "policyWatch"],
        "webhooks": true,
        "clientReputationFilter": true,
        "threatIntelligence": true,
        "integrityFeatures": ["cspIntegrity", "integrityPolicy"],
        "pciDss": false,
        "wildcardDomains": false
    }
}
```

The `status` field is one of `active`, `canceled`, `past_due`, or `inactive`. The `blockedWatch` and `integrityFeatures` fields list the specific products enabled on the plan, or an empty array if the feature is not included.


#### get_filters
Returns the current filter configuration including global filters, advanced filters, Certificate Transparency filters, and sampling rates.

**Parameters:** none

**Request**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
        "name": "get_filters"
    }
}
```


#### get_team_info
Returns team name, member list with roles, quota limit, and 2FA configuration. Only available when authenticated with a team key.

**Parameters:** none

**Request**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
        "name": "get_team_info"
    }
}
```

**Response**

```json
{
    "name": "Acme Security",
    "quotaLimit": 10000000,
    "twoFaRequired": true,
    "members": [
        { "email": "alice@example.com", "role": "owner" },
        { "email": "bob@example.com", "role": "member" }
    ]
}
```


#### get_audit_log
Returns a log of account activity including API key operations and other account events.

**Parameters:** none

**Request**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
        "name": "get_audit_log"
    }
}
```

**Response**

```json
{
    "events": [
        {
            "date": "2026-03-20T11:42:00+00:00",
            "event": "api_key_created",
            "actor": "you@example.com"
        }
    ]
}
```


---

### Reports & Analytics


#### get_report_types
Returns all valid report type identifiers and their display labels.

**Parameters:** none

**Request**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
        "name": "get_report_types"
    }
}
```

**Response**

```json
{
    "types": [
        { "type": "csp", "label": "CSP" },
        { "type": "nel", "label": "NEL" },
        { "type": "dmarc", "label": "DMARC" }
    ]
}
```


#### get_reports
Returns individual report records for a given report type and time period. Results are subject to your plan's retention limit.

**Parameters**

| Parameter | Required | Description |
|-----------|----------|-------------|
| `type` | Yes | Report type — see `get_report_types` for valid values |
| `unit` | Yes | `hours`, `days`, or `months` |
| `date` | Yes | Period date: `2026-03-23T14` (hours), `2026-03-23` (days), `2026-03` (months) |
| `action` | No | CSP action: `enforced` or `reportOnly` |
| `hostnames` | No | Page hostname filter (comma-separated, wildcards supported) |
| `paths` | No | Page path filter |
| `effectiveDirective` | No | CSP directive name |
| `blockedHostnames` | No | Blocked resource hostname filter |
| `blockedPaths` | No | Blocked resource path filter |
| `subresourceHostnames` | No | CSP Integrity subresource hostname |
| `subresourcePaths` | No | CSP Integrity subresource path |
| `subresourceHashes` | No | CSP Integrity subresource hash |
| `browser` | No | Browser name |
| `platform` | No | OS/platform name |
| `nelType` | No | NEL error type (only applies to `nel` reports) |
| `phase` | No | NEL phase |
| `disposition` | No | Permissions Policy disposition |
| `organisation` | No | AS organisation name |
| `id` | No | Specific report ID |
| `certType` | No | Certificate Transparency cert type |
| `issuer` | No | Certificate issuer |
| `sha256Spki` | No | Certificate SHA-256 SPKI hash |
| `policyId` | No | CSP policy ID |
| `message` | No | Deprecation or Intervention message |
| `policy` | No | Policy Watch policy text |
| `property` | No | Permissions Policy property |
| `destination` | No | Integrity Policy destination |
| `ioc` | No | `true` to return only threat intelligence matches. Requires the Threat Intelligence plan |
| `generatedDomain` | No | `true` to return only algorithmically generated domains (CSP reports only). Requires the Threat Intelligence plan |
| `newlyRegisteredDomain` | No | `true` to return only newly registered domains. Requires the Threat Intelligence plan |
| `domainReputationScore` | No | Maximum domain reputation score (integer). Requires the Threat Intelligence plan |
| `anyThreatIntel` | No | `true` to return only reports matching any threat-intelligence signal. Overrides the individual threat-intel filters above. Requires the Threat Intelligence plan |

**Request**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
        "name": "get_reports",
        "arguments": {
            "type": "csp",
            "unit": "days",
            "date": "2026-03-23",
            "action": "enforced",
            "blockedHostnames": "evil.com"
        }
    }
}
```

**Response**

```json
{
    "reports": [
        {
            "action": "Enforced",
            "date": "2026-03-23T14:32:01+00:00",
            "uri": "https://example.com/checkout",
            "directive": "script-src",
            "blockedUri": "https://evil.com/tracker.js",
            "raw": "{\"csp-report\":{...}}",
            "count": 3,
            "browser": "chrome",
            "platform": "windows",
            "generatedDomain": 0,
            "indicatorOfCompromise": 1,
            "recentlyRegisteredDomain": 0,
            "lowReputationDomain": 0,
            "policyIocHosts": ["evil.com"],
            "policyConcernHosts": []
        }
    ],
    "truncated": false
}
```

The `truncated` field is `true` when the result set has been capped. Narrow the time period or apply filters to retrieve a complete result.

The `policyIocHosts` and `policyConcernHosts` fields list the hostnames in the report's `original-policy` (script-execution directives) that are flagged as Indicators of Compromise or Policy Concern respectively. Both are arrays of strings and are present for all accounts; they are empty arrays when no hosts are flagged or when the Threat Intelligence feature is not included on the plan.


#### get_last_seven_days
Returns daily report totals for the last seven days, broken down by report type.

**Parameters:** none

**Request**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
        "name": "get_last_seven_days"
    }
}
```

**Response**

```json
{
    "days": [
        { "date": "2026-03-17", "reports": { "csp": 8201, "nel": 412, "dmarc": 0 } },
        { "date": "2026-03-18", "reports": { "csp": 7953, "nel": 388, "dmarc": 3 } }
    ]
}
```


#### get_monthly_breakdown
Returns the current month's report count broken down by type.

**Parameters:** none

**Request**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
        "name": "get_monthly_breakdown"
    }
}
```

**Response**

```json
{
    "breakdown": [
        { "type": "csp", "label": "CSP", "accepted": 241892 },
        { "type": "nel", "label": "NEL", "accepted": 18443 },
        { "type": "dmarc", "label": "DMARC", "accepted": 72 }
    ]
}
```


#### get_usage_metrics
Returns report counts broken down by type and action (accepted, filtered, sampled, rejected).

**Parameters:** none

**Request**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
        "name": "get_usage_metrics"
    }
}
```

**Response**

```json
{
    "metrics": [
        {
            "type": "csp",
            "accepted": 241892,
            "filtered": 18320,
            "sampled": 0,
            "rejected": 441
        }
    ]
}
```


#### get_graphs
Returns report counts broken down by period for a given report type and time range. Periods greater than one week require a paid plan.

**Parameters**

| Parameter | Required | Description |
|-----------|----------|-------------|
| `type` | Yes | Report type — see `get_report_types` for valid values |
| `unit` | Yes | `weeks` or `months` |
| `amount` | Yes | For weeks: `1`, `2`, `3`, or `4`. For months: `3`, `6`, or `12` |

**Request**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
        "name": "get_graphs",
        "arguments": {
            "type": "csp",
            "unit": "weeks",
            "amount": 2
        }
    }
}
```

**Response**

```json
{
    "type": "csp",
    "unit": "weeks",
    "amount": 2,
    "periods": [
        {
            "date": "2026-03-23",
            "total": 9142,
            "directives": {
                "script-src": 6201,
                "style-src": 1488,
                "img-src": 903,
                "connect-src": 550,
                "unknown": 0
            }
        }
    ]
}
```


---

### Policies


#### get_csp_policies
Returns all saved CSP policies for the account.

**Parameters:** none

**Request**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
        "name": "get_csp_policies"
    }
}
```

**Response**

```json
{
    "policies": [
        {
            "id": "policy-abc123",
            "name": "Main site",
            "policy": "default-src 'none'; script-src 'self'; style-src 'self'"
        }
    ]
}
```


#### get_csp_policy
Returns a single saved CSP policy by ID.

**Parameters**

| Parameter | Required | Description |
|-----------|----------|-------------|
| `id` | Yes | Policy ID from `get_csp_policies` |

**Request**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
        "name": "get_csp_policy",
        "arguments": {
            "id": "policy-abc123"
        }
    }
}
```

**Response**

```json
{
    "id": "policy-abc123",
    "name": "Main site",
    "policy": "default-src 'none'; script-src 'self'; style-src 'self'"
}
```


#### get_csp_wizard
Returns the current state of the CSP Wizard for the account.

**Parameters:** none

**Request**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
        "name": "get_csp_wizard"
    }
}
```

**Response**

```json
{
    "enabled": true,
    "policy": { "id": "2b4ec5e86f0ee0cf6aa8d910a72654d1", "name": "Main site wizard" },
    "new": [
        { "directive": "script-src-elem", "uri": "cdn.example.com", "lastSeen": "2026-03-20T14:32:01+00:00" }
    ],
    "allowed": [],
    "blocked": []
}
```

When the wizard is not configured, returns `{ "enabled": false }`.


---

### Watch Products


#### get_script_watch_list
#### get_data_watch_list
#### get_frame_watch_list
#### get_policy_watch_list
Returns the list of domains enrolled in the respective Watch product, along with alert configuration.

**Parameters:** none

**Request**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
        "name": "get_script_watch_list"
    }
}
```

**Response**

```json
{
    "watches": [
        {
            "site": "example.com",
            "emailAlertsEnabled": true,
            "webhookEnabled": true,
            "webhookTarget": "https://hooks.slack.com/services/...",
            "alertThreshold": 3,
            "created": "2025-08-14T08:41:13+00:00",
            "atRisk": false,
            "atRiskSince": null,
            "broken": false,
            "brokenSince": null
        }
    ]
}
```


#### get_script_watch_findings
#### get_data_watch_findings
#### get_frame_watch_findings
Returns blocked resource findings for the given domain, sorted by most recently seen.

**Parameters**

| Parameter | Required | Description |
|-----------|----------|-------------|
| `domain` | Yes | Domain enrolled in the Watch product |

**Request**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
        "name": "get_script_watch_findings",
        "arguments": {
            "domain": "example.com"
        }
    }
}
```

**Response**

```json
{
    "findings": [
        {
            "uri": "https://cdn.evil.com/tracker.js",
            "count": 142,
            "firstSeen": "2026-03-01T09:14:22+00:00",
            "lastSeen": "2026-03-23T14:55:01+00:00",
            "source": "csp"
        }
    ]
}
```

The `source` field indicates how the item was detected: `csp`, `csp_integrity`, or `integrity_policy`.


#### get_policy_watch_findings
Returns observed CSP policies for the given domain.

**Parameters**

| Parameter | Required | Description |
|-----------|----------|-------------|
| `domain` | Yes | Domain enrolled in Policy Watch |

**Request**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
        "name": "get_policy_watch_findings",
        "arguments": {
            "domain": "example.com"
        }
    }
}
```

**Response**

```json
{
    "findings": [
        {
            "policy": "default-src 'none'; script-src 'self'",
            "enforced": true,
            "count": 8821,
            "firstSeen": "2026-01-15T10:00:00+00:00",
            "lastSeen": "2026-03-23T14:00:00+00:00"
        }
    ]
}
```


---

### Certificates


#### get_ct_certificate
Returns the raw PEM-encoded certificate for a given SHA-256 hash observed in your Certificate Transparency reports.

**Parameters**

| Parameter | Required | Description |
|-----------|----------|-------------|
| `sha256` | Yes | SHA-256 hash of the certificate |

**Request**

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
        "name": "get_ct_certificate",
        "arguments": {
            "sha256": "abc123def456..."
        }
    }
}
```

**Response**

```json
{
    "pem": "-----BEGIN CERTIFICATE-----\nMIIE....\n-----END CERTIFICATE-----\n"
}
```


---

## Prompts

Prompts are pre-built conversation starters that guide an AI assistant through a specific investigation or task using your account data. MCP clients that support prompts can surface these as slash commands or quick actions.

Use `prompts/list` to enumerate available prompts and `prompts/get` to retrieve a prompt with any arguments filled in, ready to send as a user message.


### review_csp_health
Review recent CSP violations, report volume trends, and saved policies to assess your CSP security posture.

**Arguments:** none


### investigate_domain
Investigate Blocked Watch findings across all watch types (Script, Data, Frame, Policy) for a specific domain.

**Arguments**

| Argument | Required | Description |
|----------|----------|-------------|
| `domain` | Yes | The domain to investigate (e.g. `www.example.com`) |


### generate_security_headers
Generate the report-uri endpoint URLs and header values needed to implement security reporting for a website.

**Arguments:** none


### account_overview
Summarise your plan, quota usage, subscription status, and recent report activity across all report types.

**Arguments:** none


### csp_wizard_review
Review the CSP Wizard's current policy-in-progress, summarise what has been learned so far, and suggest next steps.

**Arguments:** none


---

## Resources

The MCP endpoint exposes Report URI documentation as resources. MCP clients that support resources can fetch and read documentation pages directly.

Use `resources/list` to enumerate all available resources. Each resource has a canonical URI at `docs.report-uri.com`. Use `resources/read` with an exact URI from the list to retrieve the content.

Available resources include an `llms.txt` documentation index and all documentation pages as Markdown files.