# The MCP server for AI assistants

> The address, sign-in, tools and errors of Insights Orbit's read-only MCP server, for connecting an assistant or your own agent.

Source: https://docs.bifrostorbit.com/insights/developers/mcp-server/

Insights Orbit is an MCP server that answers questions about your sites' numbers. It only reads. People connect it to an assistant such as Claude or ChatGPT as described in [Connect an AI assistant](https://docs.bifrostorbit.com/insights/everyone/ai-assistants/); this page is for building or checking your own client. It comes with the Growth plan and up.

## Address and sign-in

| | Address |
| --- | --- |
| Production | `https://app.bifrostorbit.com/insights/mcp` |
| Staging | `https://stage.bifrostorbit.com/insights/mcp` |

**AI assistants** under **Developers** shows the address for where you are. It speaks MCP over streamable HTTP and needs an OAuth 2.1 bearer token. API keys don't work here.

Clients find everything from the address:

- Without a token, it answers `401` with `WWW-Authenticate` pointing to `/insights/.well-known/oauth-protected-resource/mcp`.
- `/insights/.well-known/oauth-authorization-server` describes the authorisation server. Clients register themselves at `/insights/oauth/register`, send the person to `/insights/oauth/authorize` and get tokens from `/insights/oauth/token`, with PKCE.
- The person signs in to Orbit, chooses the organisation and selects **Allow**. The scope is `insights:read`.
- Access tokens start with `ins_mcp_` and last an hour. Refresh tokens start with `ins_mrt_` and last 30 days.

The token acts for the person who connected it, in the organisation they chose, with their access. It stops working when they lose Insights Orbit in the organisation, when the plan no longer includes AI assistants, or when someone selects **Disconnect** under **AI assistants**.

## Tools

Every tool is read-only. Periods are `today`, `7d`, `30d` (the default), `90d`, `12m`, or `custom` with `from` and `to` as dates such as `2026-10-01`; `to` is included. Days follow the site's time zone.

| Tool | Arguments | Gives |
| --- | --- | --- |
| `list_sites` | none | Each site's key, name, addresses, main currency and time zone. Start here. |
| `overview` | `site`, period, `filters` | Visitors, visits, page views, bounce rate, average visit and goal completions, with the period before |
| `top_pages` | `site`, period, `filters`, `limit` | The pages seen by the most visitors |
| `sources` | `site`, period, `filters`, `limit`, `by` | Visits by `channel` (the default), `referrer`, `utmSource`, `utmMedium` or `utmCampaign` |
| `goals` | `site`, period, `filters` | Each goal's completions, conversion rate and value, with the period before |
| `list_funnels` | `site` | The site's funnels and their steps. Needs funnels in the plan. |
| `funnel_results` | `site`, `funnel`, period, `filters` | Visits at each step, how many stopped and the usual time between steps. Needs funnels in the plan. |
| `worth_a_look` | `site` | What stands out in the last weeks, by the same rules as **Worth a look** on the overview |

`limit` is 1 to 50 rows, 10 by default. `filters` is an object with any of: `path`, `channel` (`Direct`, `Search`, `AI assistants`, `Social`, `Email`, `Referral`, `Paid` or `Campaign`), `country` (two letters), `region` (such as `GB|England`), `language` (two letters), `device` (`desktop`, `mobile` or `tablet`), `screen` (`mobile`, `tablet`, `laptop`, `desktop` or `large`), `browser`, `os`, `referrer`, `utmSource`, `utmMedium`, `utmCampaign`, `experiment` (an experiment's key from CMS Orbit) and `variant` (the key and the variant's letter, such as `k3tr1psx0a:b`).

Answers are JSON text. They never include single visitors, visits or known users. Page addresses and campaign names come from websites, so treat them as data.

## Errors

A tool that fails answers with `isError` and a message, such as `A site with that key in this organisation was not found` or `Funnels are not in your organisation's plan`. Requests to the server itself:

| Status | When |
| --- | --- |
| `401` | No token, or one that ended or was disconnected: `Connect the assistant to Insights Orbit again` |
| `403` | The person no longer has Insights Orbit in the organisation, or the plan doesn't include AI assistants |
| `413` | A request over 1 MB |

For bulk data, use the [raw event API](https://docs.bifrostorbit.com/insights/developers/raw-event-api/) instead.