# Overview

Source: https://docs.mirafive.io/mcp

> Connect Claude, Cursor, VS Code, ChatGPT or any MCP client to MIRA FIVE, so an agent can answer questions from your analytics.

The MIRA FIVE MCP server lets an AI agent work with your analytics through the Model Context Protocol. With it, an agent answers questions from your data: where buyers came from, which pages convert, what changed last week, who a person is. With your permission it also sets things up: projects, sources, goals, funnels, segments, insights and dashboards, and feature flags and experiments where your organization has them. For scripts without an agent, use the [REST API](https://docs.mirafive.io/rest-api).

## Server URL

```text
https://app.mirafive.io/mcp
```

The server speaks MCP over Streamable HTTP. Send each JSON-RPC message as its own `POST`. It opens no event stream and keeps no session, so `GET` and `DELETE` answer `405`. It offers tools only: no resources, no prompts. Its instructions tell the agent how to read MIRA FIVE, and [Tools](https://docs.mirafive.io/mcp/tools) lists every tool.

## Connect

Clients that support OAuth need only the URL: they open your browser, you sign in to MIRA FIVE and approve the app. Other clients send an [API key](https://docs.mirafive.io/keys#create-an-api-key).

**Claude Code**

Add the server in a terminal:

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

Then run `/mcp` in Claude Code and choose MIRA FIVE. Your browser opens MIRA FIVE to approve it.

**Claude**

In Claude Desktop or on claude.ai:

1. Open **Settings**, then **Connectors**.
2. Add a custom connector.
3. Name it MIRA FIVE and paste `https://app.mirafive.io/mcp` as the server URL.
4. Approve the connection in MIRA FIVE when Claude asks.

**Cursor**

Add the server to Cursor's configuration:

```json title="~/.cursor/mcp.json"
{
  "mcpServers": {
    "mirafive": {
      "url": "https://app.mirafive.io/mcp"
    }
  }
}
```

Cursor then opens your browser to approve it.

**VS Code**

Add the server to the workspace's MCP configuration:

```json title=".vscode/mcp.json"
{
  "servers": {
    "mirafive": {
      "type": "http",
      "url": "https://app.mirafive.io/mcp"
    }
  }
}
```

Start the server from the file or the MCP servers list. VS Code opens your browser to approve it.

**ChatGPT**

ChatGPT connects to remote MCP servers as custom connectors, in developer mode:

1. In ChatGPT's settings, turn on developer mode.
2. Create a connector named MIRA FIVE with `https://app.mirafive.io/mcp` as the server URL and OAuth as authentication.
3. Approve the connection in MIRA FIVE when ChatGPT opens it.

**Other**

Point any MCP client with Streamable HTTP support at the URL. If it supports OAuth, that is all. Otherwise send an [API key](https://docs.mirafive.io/keys#create-an-api-key) as a bearer token:

```json title="mcp.json"
{
  "mcpServers": {
    "mirafive": {
      "url": "https://app.mirafive.io/mcp",
      "headers": {
        "Authorization": "Bearer mf_pat_…"
      }
    }
  }
}
```

The file name and top-level key differ by client. Keep the key out of files you commit.

To check the connection, ask the agent "Who am I in MIRA FIVE?". It calls `whoami` and names your account, the organizations it reaches and whether it may change setup.

## Authentication

The server accepts two credentials, both as `Authorization: Bearer`. Either one acts as you: it sees what you can see, in every organization you belong to, with your role in each.

### OAuth

MIRA FIVE is an OAuth 2.1 authorization server with PKCE (`S256`) and dynamic client registration (RFC 7591). An MCP client finds everything from the server URL:

1. A call without a token answers `401` with `WWW-Authenticate: Bearer realm="mcp", resource_metadata="https://app.mirafive.io/.well-known/oauth-protected-resource/mcp"`.
2. `GET https://app.mirafive.io/.well-known/oauth-protected-resource/mcp` names the authorization server `https://app.mirafive.io` and the scope `mcp:use`.
3. `GET https://app.mirafive.io/.well-known/oauth-authorization-server` gives the endpoints:

| Endpoint | URL |
| --- | --- |
| Authorization | `https://app.mirafive.io/oauth/authorize` |
| Token | `https://app.mirafive.io/oauth/token` |
| Registration | `https://app.mirafive.io/oauth/register` |

4. The client registers with `POST /oauth/register` (`client_name`, `redirect_uris`) and becomes a public client, without a secret.
5. You sign in to MIRA FIVE, with a confirmed email address, and approve the app on the consent screen, which names where it sends you back.
6. The client exchanges the code for tokens (grant types `authorization_code` and `refresh_token`). Access tokens last 1 hour, refresh tokens 30 days.

Redirect URIs must use `https`, or `http` only to `localhost`, `127.0.0.1` or `[::1]`, or the app schemes `cursor`, `vscode`, `vscode-insiders` and `windsurf`. Anything else is refused with `400` and `{"error": "invalid_redirect_uri"}`. A network may register 10 clients an hour. Registrations nobody approves are removed after a week.

Approved apps are listed under **Connected apps** on the **API & MCP** page. **Disconnect** revokes all of an app's tokens.

### API key

Create a personal API key as described in [Keys](https://docs.mirafive.io/keys#create-an-api-key) and send it as `Authorization: Bearer mf_pat_…`. Use it for clients without OAuth, and for agents that run unattended. The same key also reads the [REST API](https://docs.mirafive.io/rest-api).

## Permissions

Every credential, each API key and each connected app, has two switches on the **API & MCP** page. Both are off by default.

| Switch | Allows |
| --- | --- |
| **May change setup** | The setup tools: create projects and sources, actions and goals, funnels, segments, insights, dashboards, flags and experiments. |
| **May turn flags on and off** | Changes to what live traffic sees: `set_flag_state`, `update_flag` on a flag that is on, `start_experiment`, and `end_experiment` when it changes what people get. Needs **May change setup** too, and shows only where your organization has feature flags. |

With both off, the credential only reads. A setup tool then answers with the switch to turn on and where. The agent can check with `whoami`, which returns `mayChangeSetup` and `mayChangeLiveFlags`.

The switches never go beyond your role. A change also needs the role that allows it in the dashboard:

| Role | May set up through the agent |
| --- | --- |
| `owner`, `admin` | Everything: projects, sources, definitions, flags and experiments. |
| `member` | Definitions: actions, goals, funnels, segments, insights, dashboards, flags, experiments. Not projects or sources. |
| `viewer` | Nothing. Reads only. |

## Rate limits

- 120 calls per minute per person, on a budget separate from the REST API. Every answer carries `RateLimit-Policy: "mcp";q=120;w=60` and `RateLimit: "mcp";r=…;t=…`. Past the limit the answer is `429` with `Retry-After`.
- 30 setup changes per minute per person. Past that, the tool answers `Too many setup changes in a minute. Try again in N seconds.`
- 60 refused tokens per minute from one network, as on the REST API.

## Audit trail

Every tool call is recorded under **API & MCP** as recent access: the tool, the credential, the project and how the call ended. Arguments are never stored, since they can name people. Every setup change is also written to the audit log, naming the app or key that made it on your behalf.

## Example prompts

- "Which channels brought the most buyers to Nordlicht Shop last month, first touch?"
- "Compare this week's revenue with last week's and tell me what changed."
- "Where do people drop off between viewing a product, starting checkout and completing the order?"
- "Find lena.hoffmann@example.com and tell me how she found us and what she bought."
- "Is tracking still working on the shop? Show me the last events from the past hour."
- "Set up a purchase goal for our `order_completed` event, a funnel from product page to purchase, and a dashboard with both."

## Troubleshooting

| Symptom | Cause and fix |
| --- | --- |
| The client says it cannot authenticate, or loops back to sign-in | The client does not support OAuth for remote servers. Send an API key in the `Authorization` header instead. |
| `401` with `This API key was revoked or has expired. Create a new one on the API & MCP page.` | Create a new key and put it in the client's configuration. |
| `400 invalid_redirect_uri` when connecting | The client registered a redirect URI that is not `https`, loopback `http` or one of the allowed app schemes. Use an API key. |
| `403` when connecting | The account has not confirmed its email address, or is blocked. |
| `405` with `This endpoint answers POST only` | The client expects an event stream. Use Streamable HTTP with plain `POST` requests. |
| The agent says it may read but not change setup | Turn on **May change setup** for this key or app on the **API & MCP** page. |
| The agent may create a flag but not turn it on | Turn on **May turn flags on and off** too, or turn the flag on yourself in MIRA FIVE. |
| `No project with that id is yours to see. Call list_projects for the ids you can use.` | The agent passed a name or slug as `project_id`. It must call `list_projects` first. |
| `That question reads more data than one call may. Ask over a shorter period or with filters.` | Ask over a shorter period or with filters. |
| No flag or experiment tools | Feature flags are not enabled for your organization. |