# Connect an AI assistant (MCP)

> Connect Claude, ChatGPT, Cursor, VS Code, Codex or any MCP client to mrkr at https://mrkr.app/mcp. Sign in with OAuth, choose the sites and permissions to share, and revoke access any time.

Section: AI assistants (MCP). Canonical page: https://mrkr.app/docs/integrations/mcp. Last updated: 2026-10-05.

mrkr's MCP server lets an AI assistant read your analytics and, if you allow it, configure events and site settings. You choose exactly which sites and permissions each assistant gets.

## Server details

| Setting | Value |
| --- | --- |
| Server URL | `https://mrkr.app/mcp` |
| Transport | Streamable HTTP (stateless, JSON responses). One JSON-RPC message per POST. |
| Authentication | OAuth 2.1 with PKCE, through your mrkr account. No API keys. |
| Resource metadata | `https://mrkr.app/.well-known/oauth-protected-resource/mcp` |
| Authorization server | `https://clerk.mrkr.app` (metadata also at `https://mrkr.app/.well-known/oauth-authorization-server`) |
| Client registration | Dynamic client registration and client ID metadata documents are both supported. |
| Tools | 32. See the [tool reference](https://mrkr.app/docs/integrations/mcp-tools). |

You need a mrkr account with at least one site. The assistant can only reach sites you can reach in mrkr.

## Quick start

1. **Add the server to your assistant**
   Use the server URL `https://mrkr.app/mcp`. Copy-ready setup for each client is below.

2. **Sign in and choose access**
   Your assistant opens a browser window. Sign in to mrkr, then pick the sites and permissions to share. Read analytics is selected by default.

3. **Ask a question**
   Try: "Using mrkr, compare visitors and revenue by source for last month in USD." The assistant lists your approved sites first, then queries the one you mean.

## Set up your client

Each client below uses the same URL and opens the same sign-in. Menu names in third-party apps change often; if one does not match, follow the linked vendor guide.

### Claude (web and desktop app)

Open **Settings → Connectors**, choose **Add custom connector**, name it `mrkr` and paste the server URL. Then select **Connect** and sign in. On Team and Enterprise plans an owner may need to add the connector for the organization first. See [Anthropic's custom connector guide](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp).

Server URL:

```text
https://mrkr.app/mcp
```

If your Claude Desktop build has no custom connectors, bridge the remote server through `claude_desktop_config.json` with the community `mcp-remote` package (needs Node.js). It opens the same browser sign-in.

claude_desktop_config.json:

```json
{
  "mcpServers": {
    "mrkr": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mrkr.app/mcp"
      ]
    }
  }
}
```

### Claude Code

Terminal:

```bash
claude mcp add --transport http mrkr https://mrkr.app/mcp
```

Add `--scope user` to use it in every project. Then run `/mcp` inside Claude Code, select `mrkr` and choose **Authenticate**. To share the server with a repository, commit a `.mcp.json` instead. See [Claude Code's MCP guide](https://code.claude.com/docs/en/mcp).

.mcp.json:

```json
{
  "mcpServers": {
    "mrkr": {
      "type": "http",
      "url": "https://mrkr.app/mcp"
    }
  }
}
```

### Cursor

~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

```json
{
  "mcpServers": {
    "mrkr": {
      "url": "https://mrkr.app/mcp"
    }
  }
}
```

Open Cursor's MCP settings, find `mrkr` and select the login prompt to start OAuth. See [Cursor's MCP documentation](https://cursor.com/docs/mcp).

### VS Code

.vscode/mcp.json:

```json
{
  "servers": {
    "mrkr": {
      "type": "http",
      "url": "https://mrkr.app/mcp"
    }
  }
}
```

Start the server from the file or the MCP servers list, then allow the sign-in. Tools appear in Copilot's agent mode. See [VS Code's MCP guide](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).

### ChatGPT

Where your plan and workspace allow custom connectors, turn on **Developer mode** under **Settings → Apps & Connectors → Advanced settings**, then create a connector with the server URL and OAuth authentication. Workspace admins may need to enable or publish it. See [OpenAI's developer mode guide](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt).

### Codex

Terminal:

```bash
codex mcp add mrkr --url https://mrkr.app/mcp
codex mcp login mrkr
```

In the IDE extension, add a Streamable HTTP server with the same URL and authenticate. See the [Codex MCP guide](https://developers.openai.com/codex/mcp).

### Other MCP clients

Any client that supports remote Streamable HTTP servers with OAuth works. Point it at the server URL and let it discover the rest. A request without a token returns `401` with a `WWW-Authenticate` header that names the resource metadata URL. Request the scopes you need from the list below, send `resource=https://mrkr.app/mcp` on the authorization and token requests, and use PKCE with `S256`.

Check discovery:

```bash
curl https://mrkr.app/.well-known/oauth-protected-resource/mcp
curl -i -X POST https://mrkr.app/mcp   # expect 401 and a WWW-Authenticate header
```

## Authentication

mrkr uses OAuth. Your assistant never sees your password, and there is no API key to leak. The flow:

1. The assistant registers itself and opens mrkr's sign-in page in your browser.
2. After sign-in, the mrkr consent screen shows the app's name and the address it will return to. Check both.
3. Choose the sites (1 to 100) and the permissions to grant. Only permissions the app requested are offered.
4. Select **Allow**. The assistant receives an access token that works only for `https://mrkr.app/mcp`.

Every tool call is checked again against your saved choices, your current workspace role and your access to that site. If you lose access to a site in mrkr, the assistant loses it too, immediately.

### Permissions (scopes)

| Scope | Allows | Tools | Who can grant it |
| --- | --- | --- | --- |
| `analytics:read` | Traffic, sources, pages, revenue, AI traffic and live totals. | `get_overview`, `get_timeseries`, `get_breakdown`, `get_sources`, `get_realtime`, `get_ai_referrals`, `get_ai_crawlers`, `get_outbound_links`, `get_web_vitals`, `get_journeys`, `list_funnels`, `get_funnel_report`, `list_annotations`, `list_campaign_links` | Any member with access to the site |
| `analytics:write` | Create, edit and delete funnels, chart annotations and campaign links. Never changes collected data. | `create_funnel`, `update_funnel`, `delete_funnel`, `create_annotation`, `delete_annotation`, `create_campaign_link`, `delete_campaign_link` | Owners and admins only |
| `visitors:read` | Individual visitors, sessions and conversion timing. | `list_live_visitors`, `list_visitors`, `get_visitor` | Any member with access to the site |
| `events:read` | Event definitions, properties and conversion performance. | `list_events`, `get_event`, `get_conversions`, `list_event_configs` | Any member with access to the site |
| `events:write` | Create and update event labels, conversions and revenue properties. | `configure_event` | Owners and admins only |
| `settings:read` | Site configuration, tracking and exclusion rules. No credentials. | `get_settings` | Any member with access to the site |
| `settings:write` | Update the site name, session replay and excluded paths. No tracking mode, billing, deletion or team changes. | `update_settings` | Owners and admins only |

`list_sites` needs no scope. Write scopes need owner or admin on every selected site.

Start with `analytics:read`. Add `visitors:read` only if the assistant should see individual visitors, and `events:read` only if you are comfortable sharing the event properties your site sends. Grant write scopes only to assistants that should change configuration.

> **A permission is greyed out:** The consent screen only offers permissions the app asked for. Write permissions are also disabled unless you are an owner or admin of every selected site. To get a missing permission, reconnect from a client that requests it.

### Read vs write access

Read scopes only return data. Write scopes change saved configuration on the live site. Nothing an assistant does through MCP changes or deletes collected analytics data.

| Write scope | What it can change | Tools |
| --- | --- | --- |
| `analytics:write` (Edit reports) | Saved funnels, chart annotations and campaign links. | `create_funnel`, `update_funnel`, `delete_funnel`, `create_annotation`, `delete_annotation`, `create_campaign_link`, `delete_campaign_link` |
| `events:write` (Configure events) | Event labels, conversion (goal) flags, targets and revenue properties. | `configure_event` |
| `settings:write` (Change settings) | Site name, session replay, replay sample rate and excluded paths. Not tracking mode, billing, team or deletion. | `update_settings` |

- **Off by default.** Write permissions are unchecked on the consent screen. Tick them only for assistants that should make changes.
- **Owner or admin only.** You can grant a write permission only if you are an owner or admin of every selected site, and each write is checked against your current role. The public demo site is never writable.
- **Audited.** Every write records the tool, site, app, user and the names of the changed fields. Values you sent and access tokens are never stored.
- **Exact ids for deletes.** `delete_funnel`, `delete_annotation` and `delete_campaign_link` take the exact id from the matching list tool. There is no name matching and no undo.
- **Confirm first.** Write tools are marked destructive, so well-behaved clients ask before calling them. Updates, deletes, `configure_event` and `update_settings` are safe to retry. `create_funnel`, `create_annotation` and `create_campaign_link` are not: a retry saves a second copy.
- **Grant later, revoke any time.** To add write access to an existing connection, reconnect the client and tick the permission. To remove it, edit the connection or revoke it (below).

### Change or revoke access

Open [Settings → Your account → AI connections](https://mrkr.app/dashboard/settings?tab=mcp). Each connected app is listed with its sites and permissions.

- **Edit** removes sites or permissions. The change applies to the next tool call.
- **Revoke** disconnects the app. Its tokens stop working on the next request. To use it again, connect it from scratch.
- Adding a permission the app never had needs a new connection, not an edit.

## Next steps

- [Tool reference](https://mrkr.app/docs/integrations/mcp-tools): Every tool, parameter, default and example result.
- [Prompts and workflows](https://mrkr.app/docs/integrations/mcp-workflows): Questions that work well and the tool calls behind them.
- [Limits, privacy and errors](https://mrkr.app/docs/integrations/mcp-troubleshooting): Rate limits, what is never shared, and how to fix common errors.
- [Custom events](https://mrkr.app/docs/tracking/custom-events): Send the events your assistant will analyze.
