> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openrevenue.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Connect ChatGPT, Cursor, Claude, or other MCP clients to OpenRevenue with an API key or OAuth.

> [!NOTE]
>
> Listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=com.openrevenue/mcp) as `com.openrevenue/mcp`. Also powers the [OpenRevenue ChatGPT plugin](https://chatgpt.com/plugins/plugin_asdk_app_6a7ec2575360819190063dd4bcf6bfb5).

## Get started

**Step 1**

For ChatGPT, Claude and Cursor, connect with OAuth (below). For clients that only support API keys, create a key from [Account → API](https://www.openrevenue.com/account/api). Prefer **read-only** unless the agent must change data.

**Step 2**

Add the MCP URL (and Bearer token for API-key clients), or complete OAuth

**Step 3**

Ask about a project by domain (e.g. `example.com`)

## Endpoint

Streamable HTTP (stateless JSON responses) at:

```text theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
https://mcp.openrevenue.com/mcp
```

## Authentication

Pass an account API key (same keys as the REST API), or complete OAuth 2.1:

```http theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
Authorization: Bearer openrevenue_your_api_key_here
```

> [!NOTE]
>
> Session cookies are never accepted on MCP. Keep keys server-side and rotate them from Account → API if exposed. Unauthenticated requests return `WWW-Authenticate` with protected-resource metadata for OAuth discovery.

## Scopes

* `read` — list projects and analytics (default for new read-only keys).
* `write` — create/update projects and funnels; create/delete goals and funnels (implies read).

Keys created before scopes shipped keep full `read write` access until rotated.

## ChatGPT

Install the [OpenRevenue ChatGPT plugin](https://chatgpt.com/plugins/plugin_asdk_app_6a7ec2575360819190063dd4bcf6bfb5) from the Plugins Directory, then connect your account with OAuth. Ask things like “How did example.com do this week?”, “Top referrers for example.com last 30 days”, or “Funnel conversion for signup on example.com”.

For development or custom connectors, enable **Settings → Apps & Connectors → Advanced** developer mode in ChatGPT and paste this MCP URL:

```text theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
https://mcp.openrevenue.com/mcp
```

Complete OAuth when prompted. ChatGPT does not use API keys for this connector.

> [!NOTE]
>
> The ChatGPT listing uses this same Universal MCP URL with OAuth. Create an API key only for other MCP clients that do not support OAuth.

## Cursor

Add OpenRevenue as an MCP server in Cursor. Cursor signs you in with OAuth, so no API key is needed.

**Step 1**

Open `~/.cursor/mcp.json` to use OpenRevenue in every project, or `.cursor/mcp.json` inside one project. Create the file if it does not exist.

**Step 2**

Add the server:

```json theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
{
  "mcpServers": {
    "openrevenue": {
      "url": "https://mcp.openrevenue.com/mcp"
    }
  }
}
```

**Step 3**

Open **Customize** in the Cursor sidebar, enable **openrevenue**, then sign in to OpenRevenue and approve access when Cursor prompts you.

**Step 4**

Ask a question, for example “Top referrers for example.com last 30 days”.

To use an API key instead of OAuth, add an `Authorization` header:

```json theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
{
  "mcpServers": {
    "openrevenue": {
      "url": "https://mcp.openrevenue.com/mcp",
      "headers": {
        "Authorization": "Bearer openrevenue_your_api_key_here"
      }
    }
  }
}
```

## Claude

Add OpenRevenue as a custom connector. It works in Claude on the web, Claude Desktop and Cowork, and you sign in with OAuth, so no API key is needed.

**Step 1**

In Claude, open **Customize → Connectors**, click **Add**, then **Add custom connector**.

**Step 2**

Enter `OpenRevenue` as the name and paste the MCP URL:

```text theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
https://mcp.openrevenue.com/mcp
```

**Step 3**

Keep the detected sign-in settings, finish adding the connector, then sign in to OpenRevenue and approve access.

**Step 4**

Ask a question, for example “How did example.com do this week?”

Claude starts with read access. The first time you ask it to change something, such as creating a goal, it asks you to approve write access.

### Claude Code

Add the server from your terminal, then run `/mcp` in Claude Code to sign in:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
claude mcp add --transport http openrevenue https://mcp.openrevenue.com/mcp
```

To use an API key instead of OAuth:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
claude mcp add --transport http openrevenue https://mcp.openrevenue.com/mcp --header "Authorization: Bearer openrevenue_your_api_key_here"
```

## OAuth

MCP clients that support OAuth discover the authorization server from protected-resource metadata at `https://mcp.openrevenue.com/.well-known/oauth-protected-resource/mcp`. Access tokens are JWTs verified against `https://www.openrevenue.com/api/auth/jwks`. Users always approve access on OpenRevenue's consent screen. Prefer API keys for personal agents; use OAuth when the client cannot store a long-lived key.

* OAuth scope `mcp` (or `read`) grants read tools only.
* Request `write` in addition when the agent must create or change data.
* A read-only token that calls a write tool gets a `403` with `WWW-Authenticate: Bearer error="insufficient_scope"`, so clients that support scope step-up can ask the user for write access and retry.

### Disconnect an app

Apps you connect with OAuth stay connected until you disconnect them. To see and remove them:

1. Open [Account → API](https://www.openrevenue.com/account/api).
2. Under **Connected apps**, find the app. Each entry shows its name and domain, what it can do and when you connected it.
3. Click **Revoke** and confirm.

The app loses access right away: its next MCP request gets a `401` with `WWW-Authenticate: Bearer error="invalid_token"`. To use it again, connect it from the app and approve access on the consent screen. API keys are not affected; delete them under **API keys** on the same page.

## Tools

Read tools cover account profile, projects, stats, timeseries, pages, referrers, geo, devices, browsers, OS, visitors, performance, funnels, and goals. Write tools (owner/admin + write scope) can create/update projects and funnels, and create goals. Deleting a funnel or goal requires `confirm: true` after the user approves.

### Periods

Tools that take a `period` accept only the values below and reject anything else. The default is `30d`.

| Tools | Accepted periods |
| - | - |
| Stats, timeseries, pages, referrers, geo, devices, browsers, OS | `today`, `24h`, `7d`, `30d`, `90d`, `6m`, `12m`, `this_week`, `this_month`, `this_year`, `all` |
| Visitors, performance, funnel reports | `today`, `yesterday`, `24h`, `7d`, `30d`, `6m`, `12m`, `this_week`, `this_month`, `this_year`, `all` |

Not available via MCP (use the dashboard): deleting projects, team invites, billing, or connecting revenue / Search Console credentials.

## Permissions

* Read tools need the `read` scope plus project access (owner or member).
* Write tools need the `write` scope plus owner or team admin.
* Every tool call is written to a durable audit log (user, tool, outcome).
* Rate limits apply separately from the REST API and per user for both API keys and OAuth; write calls are capped more tightly.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.