# Connect AI Assistants

Query your Kopai traces, logs and metrics from Claude, Claude Code and other MCP hosts

The Kopai connector lets you ask about your workspace's traces, logs and metrics from inside the AI assistant you already use. Ask "what is the error rate by service in the last hour?" and the assistant queries Kopai and answers with a table or a chart.

The connector is an [MCP](https://modelcontextprotocol.io) server at `https://api.kopai.app/v2/mcp`:

- **Read-only.** It can read the telemetry of your workspace and nothing else. It cannot change data, members, billing or settings.
- **No key to copy.** You sign in with your Kopai portal login and approve the assistant once. The assistant's access refreshes on its own until you revoke it.
- **Two tools.** `metrics_discover` and `query`, described under [Tools](#tools).

If you would rather have your coding agent use the Kopai CLI, see [AI Agent Skills](/docs/skills/).

## Use cases

You ask in plain language; the assistant turns the question into Kopai queries and follows up on what it finds. Some things to ask:

- **Triage an incident.** "Which services started returning errors in the last 30 minutes, and what are the most common error messages?" The assistant compares error rates by service, then reads the matching traces and logs.
- **Find slow endpoints.** "What are the slowest routes in the checkout service today, by p95 latency?"
- **Follow a request.** "Show me the logs for trace `4bf92f3577b34da6a3ce929d0e0e4736`." Logs carry the trace ID of the request that wrote them, so the assistant can line them up with its spans.
- **Debug while you code.** In [Claude Code](#claude-code), ask "why is this handler slow in production?" next to the code. The assistant reads the handler's traces and can point at the call that takes the time.
- **Explore what you collect.** "Which metrics do we have, and which attributes can I break them down by?" This is what `metrics_discover` answers.
- **Get a report on a schedule.** In claude.ai, create a [scheduled task](https://support.claude.com/en/articles/13854387-schedule-recurring-tasks-in-claude-cowork) with the Kopai connector and a connector for wherever the report should go, such as Gmail or Slack. Give it a prompt like: "Check error rate and p95 latency by service over the last 24 hours in Kopai, and email me a short summary. Call out anything worse than the day before." To send it somewhere else, say where: "…and post a short summary in #ops." Claude runs it at the cadence you pick, even while your computer is off. Anything Kopai stores can go in the report: slow routes, new errors, a metric drifting past a threshold. Each run queries Kopai through your connector, so [revoking it](#manage-access) also cuts the report off from your data.
- **Keep a chart current.** In Claude Code, ask to "keep an eye on error rate by service in Claude" and it publishes a [live page](#live-pages-in-claude-code) that re-queries Kopai each time someone opens it, so the team looks at the same numbers without re-asking.

Each answer is bounded to what fits in a reply; see [Limits](#limits).

## Before you start

- You need a Kopai account with a workspace. If you haven't finished setting up your workspace, do that first; an account without one cannot approve a connection.
- **Sign in to the portal at [app.kopai.app](https://app.kopai.app) first.** The connection request waits only ten minutes for your approval, which may not be enough if you also have to sign in by email link.

## Claude (claude.ai and Claude Desktop)

<LinkButton
  href="https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Kopai&connectorUrl=https%3A%2F%2Fapi.kopai.app%2Fv2%2Fmcp"
  icon="external"
>
  Add Kopai to Claude

The button opens claude.ai's **Add custom connector** dialog with the name and URL filled in. To add it by hand instead:

1. In claude.ai, open **Customize › Connectors** and choose **Add custom connector**.
2. Enter the name `Kopai` and the URL `https://api.kopai.app/v2/mcp`.
3. Add the connector, then choose **Connect** on it.

Connectors you add on claude.ai are also available in Claude Desktop.

:::caution[Name it exactly "Kopai"]
[Live pages](#live-pages-in-claude-code) find the connector by its name. If yours is named anything other than `Kopai`, a page someone shares with you asks you to add the connector instead of showing your data.
:::

**Claude Team and Enterprise:** an organization owner can add the connector once for everyone under **Organization settings › Connectors**. Each member still connects it and approves access for themselves.

### Approve the connection

When you choose **Connect**, Claude sends you to the Kopai portal:

1. If you aren't signed in, sign in with your password or an email link. You come back to the same request afterwards.
2. The consent page shows the app asking for access, the host you'll be sent back to (`claude.ai` for Claude) and the name of your workspace.
3. Check that you started this from an app you trust, then choose **Approve**.

Claude now holds a read-only token for your workspace. You won't be asked again unless you revoke it.

## Claude Code

Add Kopai once for all your projects:

```bash
claude mcp add --transport http --callback-port 3118 --scope user kopai https://api.kopai.app/v2/mcp
```

Then run `/mcp` inside Claude Code, select `kopai` and authenticate. Your browser opens the Kopai consent page; [approve the connection](#approve-the-connection) as above.

- `--callback-port` fixes the local port Claude Code listens on for the sign-in redirect. Kopai's sign-in server accepts only the exact redirect address Claude Code registered, so the port must stay the same between sign-ins. Any free port works; `3118` is an example.
- `--scope user` makes the server available in every project. Leave it out to add Kopai to the current project only.

### With a CLI token instead

When a browser sign-in isn't possible, for example on a remote machine, Claude Code can send a [CLI token](/docs/authentication/#cli-authentication) instead. Creating one needs the admin or owner role.

Add Kopai to the project's `.mcp.json`:

```json title=".mcp.json"
{
  "mcpServers": {
    "kopai": {
      "type": "http",
      "url": "https://api.kopai.app/v2/mcp",
      "headers": {
        "Authorization": "Bearer ${KOPAI_TOKEN}"
      }
    }
  }
}
```

Claude Code replaces `${KOPAI_TOKEN}` with the value of that environment variable when it starts, so the file holds no secret and you can commit it. Everyone who works in the repository sets `KOPAI_TOKEN` to their own CLI token, for example in their shell profile or an `.envrc` or `.env` file.

:::caution[Keep the token out of files you share]
A CLI token is a long-lived credential (90 days by default). Keep whatever file sets `KOPAI_TOKEN` out of version control (add it to `.gitignore`), and never write the token itself into `.mcp.json` or pass it with `claude mcp add --header`; both leave it in a plain-text file.
:::

### Live pages in Claude Code

A live page is a page Claude Code publishes to claude.ai that charts your telemetry and keeps it current: each time someone opens it, it queries Kopai through **their own** connector. The page stores queries, never data. Install the `create-live-page` [skill](/docs/skills/), then ask Claude Code something like "keep an eye on error rate by service in Claude".

- **The page calls the claude.ai connector, by name.** A Kopai server configured in Claude Code, by sign-in or by token, can feed the page while Claude Code builds it, but the published page calls only connectors on claude.ai accounts. The author and every viewer need Kopai [added on claude.ai](#claude-claudeai-and-claude-desktop), named exactly `Kopai`; the skill refuses to publish otherwise.
- **Each viewer approves the page once.** The first query asks the viewer for permission. A viewer who declines sees the page without its live sections until they reload it.
- **Who can open it.** Live pages need Claude Code 2.1.209 or later to build, and a Pro, Max, Team or Enterprise plan to view. They are never public; on Team and Enterprise they can be shared inside the organization.
- **Refresh.** The page refreshes about as often as its chart's time buckets change, no more than every 30 seconds, and pauses while it is hidden.

## Local app

[`@kopai/app`](https://www.npmjs.com/package/@kopai/app), the local Kopai backend, serves the same MCP server at `http://localhost:8000/mcp` for the telemetry on your own machine. It requires `@kopai/app` 0.15.0 or later.

Start the app with `npx @kopai/app start`, then add it to Claude Code:

```bash
claude mcp add --transport http local-kopai http://localhost:8000/mcp
```

There is no sign-in, and `local-kopai` can sit next to the hosted `kopai` server. claude.ai and Claude Desktop connectors run through Anthropic's servers and cannot reach `localhost`, so this works with Claude Code and other MCP clients on your machine. See the [package README](https://github.com/kopai-app/kopai-mono/tree/main/packages/app#mcp) for ports, network access and security.

## Other MCP hosts

Any MCP host that supports remote servers with OAuth sign-in can add `https://api.kopai.app/v2/mcp` and connect through the same consent page.

## Manage access

**Account › Connected apps** in the [Kopai portal](https://app.kopai.app/account?tab=connected-apps) lists every app you have approved. Choose **Revoke** next to an app to remove its access; it stops working within 30 seconds. Revoking Claude removes access from claude.ai and Claude Desktop together. To use an app again, connect it again from the app.

Revoking an app doesn't affect CLI tokens. Those are managed under **Access tokens**.

## Tools

The connector has two tools, both read-only. Your assistant picks the tool and writes the query; you ask in plain language.

| Tool | Input | Returns |
| --- | --- | --- |
| `metrics_discover` | none | The metrics in your workspace, with their attributes |
| `query` | one query under `query` | Traces, logs or metrics, as raw rows or aggregates |

A `query` picks a `signal` (`traces`, `logs` or `metrics`) and a `mode` (`raw` rows or `aggregate`), and always carries a time window. "What is the error rate by service in the last hour?" becomes:

```json
{
  "query": {
    "signal": "traces",
    "mode": "aggregate",
    "measures": [{ "op": "ERROR_RATE", "as": "error_rate" }],
    "dimensions": ["service.name"],
    "timeDimension": { "type": "relative", "lookback": "1h" },
    "orderBy": [{ "type": "measure", "alias": "error_rate", "direction": "desc" }],
    "output": { "type": "summary" }
  }
}
```

The tools return the same JSON as Kopai's query API and CLI.

## Where your data goes

Your telemetry is stored in the EU, at Hetzner in Germany and Finland, and the connector doesn't move it. When you ask a question, the query runs in the EU and only its result, at most a few hundred rows, goes to your AI host, which shows it to you. For Claude, that host backend is Anthropic's, in the US. Nothing is sent unless someone asks, and the host's own data policies apply to what it receives.

The connector reads one workspace and nothing else, and you can [revoke it](#manage-access) at any time.

## Limits

Every query is bounded so a result fits in the assistant's reply:

| | `raw` | `aggregate` |
| --- | --- | --- |
| Rows when `limit` is not set | 100 | 500 |
| Highest `limit` | 200 | 500 |

- **A time window is required.** Either relative (`"lookback": "1h"`, units `s`, `m`, `h`, `d`, `w`) or absolute (`startTime` and `endTime` in ISO 8601 UTC).
- **A `limit` above the maximum is rejected** with `invalid_input`; it is not lowered silently.
- **Raw results page.** When more rows match, the result carries a cursor for the next page.
- **Too-large results are refused, not cut short.** An aggregate that matches more rows than its `limit`, or any result over 150,000 characters, returns `result_too_large` with no rows. The error lists the remedies that fit the query: for an aggregate, raising `limit` up to 500, grouping by fewer dimensions, a coarser `granularity`, a `summary` instead of a time series, or a narrower window; for an oversized result, a lower `limit`, a narrower window or a coarser `granularity`.

## Troubleshooting

**Claude says "Couldn't reach the MCP server".**
Kopai refused the request. Check that your workspace setup is finished in the portal. Your workspace may also not be fully provisioned yet, or Kopai may be briefly unavailable. Try again in a few minutes and [contact us](#privacy-and-support) if it persists.

**The consent page says you can't approve.**
Your account has no workspace, or setup isn't finished. If setup is pending, choose **Complete setup** on that page, then start the connection again from your app. If your account has no workspace, ask a workspace admin to invite you.

**The request expired before you approved it.**
A connection request lasts ten minutes. Sign in to the portal first, then connect again from your app.

**Claude Code sign-in fails after upgrading Claude Code.**
Some Claude Code releases changed the local address they register for the sign-in redirect between `localhost` and `127.0.0.1`, and Kopai's sign-in server matches it exactly. Remove the server with `claude mcp remove kopai` and add it again with the same `--callback-port`.

**Claude Code with a CLI token gets 401 or 403.**
The token has expired, was revoked, or isn't a CLI token. Create a new CLI token under **Access tokens** and update `KOPAI_TOKEN`.

**A shared live page asks you to add the `Kopai` connector.**
Your Kopai connector isn't named exactly `Kopai`, or you haven't connected it on your claude.ai account. [Add it](#claude-claudeai-and-claude-desktop) with the name `Kopai`.

**The assistant reports `result_too_large`, or `invalid_input` on `limit`.**
The query asked for more than one reply can hold. See [Limits](#limits); asking for a shorter window or a coarser breakdown usually fixes it.

## Privacy and support

- [Privacy policy](/privacy/)
- Support: [hello@kopai.app](mailto:hello@kopai.app)