Connect an AI Agent with the MCP Server

The tinyanalytics MCP server lets an AI agent read and manage your analytics directly, using the same API key you already use for the HTTP API. Point your agent at one endpoint and it can answer questions about your traffic, create goals and funnels, and build dashboards — without you writing any HTTP calls.

POST https://dash.tinyanalytics.io/api/mcp

Model Context Protocol (MCP) is an open standard that lets AI applications call external tools. tinyanalytics implements it as a stateless HTTP endpoint, so there’s no session to manage and no software to install on your side.

This page is about giving an agent access to your analytics data. To give an assistant these documentation pages instead — so it can help you write an integration — see Use docs with AI.

What can an agent do through MCP?

The server exposes 47 tools, grouped by what you’d ask for:

You ask for	Tools the agent uses
Traffic questions	Overview totals, metric time series, breakdowns by 18 dimensions, live visitors, landing pages, acquisition, journeys, retention, and revenue
Site health	Core Web Vitals, JavaScript errors, and bot and AI-crawler traffic
Events and people	Custom event names and properties, the raw event log, the data dictionary, user and session lists, and server-side identification
Measurement setup	Goals, funnels (including analysis without saving), custom SQL dashboards, and chart annotations
Anything else	A read-only SQL query over your own event data, with the schema available as a tool
Getting started	Create a site, get its tracking snippet, check whether tracking is live, and get the dashboard link

Every tool runs with your key’s access: the agent sees exactly the sites you can see, and writes are refused unless your organization role allows them.

Which AI clients can connect today?

The requirement is simple: the client must speak Streamable HTTP and let you set a request header. Clients that only support OAuth cannot connect yet.

Client	Status
Claude Code	Connects — the command below is tested against production
Cursor	Connects — supports HTTP servers with custom headers
VS Code	Connects — supports HTTP servers with custom headers
Codex CLI	Connects — supports HTTP servers with custom headers
claude.ai (web)	Not yet — needs OAuth support, which is planned
ChatGPT connectors	Not yet — requires OAuth, which is planned

How do I connect my agent?

Create an API key

In tinyanalytics, open Settings → Account and create a key from the API keys card. Copy it immediately — it’s shown only once.A key inherits its owner’s access, so the agent will reach every site you can reach.

Add the server to your client

Use the configuration for your client below, replacing YOUR_API_KEY with the key you just created.

claude mcp add --transport http tinyanalytics https://dash.tinyanalytics.io/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

{
  "mcpServers": {
    "tinyanalytics": {
      "url": "https://dash.tinyanalytics.io/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

{
  "servers": {
    "tinyanalytics": {
      "type": "http",
      "url": "https://dash.tinyanalytics.io/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

[mcp_servers.tinyanalytics]
url = "https://dash.tinyanalytics.io/api/mcp"
http_headers = { Authorization = "Bearer YOUR_API_KEY" }

Cursor reads ~/.cursor/mcp.json (or .cursor/mcp.json in a project), VS Code reads .vscode/mcp.json, and Codex CLI reads ~/.codex/config.toml.

Keep the key out of your repository

If the configuration file is committed, read the key from your environment instead of pasting it. In Claude Code, a project .mcp.json supports ${env:VAR}:

.mcp.json

{
  "mcpServers": {
    "tinyanalytics": {
      "type": "http",
      "url": "https://dash.tinyanalytics.io/api/mcp",
      "headers": { "Authorization": "Bearer ${env:TINYANALYTICS_API_KEY}" }
    }
  }
}

Ask your agent to list your sites

Start a new session so the client picks up the server, then ask:

List my tinyanalytics sites.

The agent returns your organization and its sites, each with a numeric site ID. That ID is what every other tool uses, so a successful list_sites call confirms both the connection and the key.

What should I ask first?

Once connected, ask in plain language — the agent picks the tool:

“What were my top pages last week?”
“How much traffic came from AI assistants this month?”
“Which pages do people land on and immediately leave?”
“Create a goal for anyone who reaches /pricing.”
“Build me a dashboard of signups per day.”

Do I need to give dates?

Yes, for anything over a date range. Every date-ranged report requires a start and end date in YYYY-MM-DD, read in the time zone you pass (UTC by default). Agents supply these automatically from your question — “last week” becomes concrete dates — but there is no relative range like 7d, and there is no “all time” shortcut. For all of your history, ask for a range starting before the site existed. Live visitors, saved funnels, saved dashboards, and annotations don’t take dates.

How many requests can an agent make?

MCP calls are limited to 120 requests per minute per API key. Beyond that the server returns 429 Too Many Requests with a Retry-After header, and the agent should wait for the window to reset. That budget suits normal agent work: building a dashboard, where each card is previewed before saving, is typically 30–60 calls over a couple of minutes. This limit is separate from the server-side ingestion limit on POST /api/track.

Is it safe to connect an agent?

Connecting an agent gives it your key’s access. Understand these four points before you do.

Your key is your identity. An agent connected with your key can do anything you can do through the API, for every site your account reaches. There are no read-only keys yet.
Deletion is not available. The tools that permanently delete a site, goal, funnel, dashboard, annotation, or a person’s data are not offered on tinyanalytics cloud, and neither is changing a site’s tracking configuration. An agent cannot destroy your data or silently switch off collection.
Analytics text is untrusted input. Page titles, referrers, and event names come from anonymous visitors to your site, which makes them a channel for prompt injection. tinyanalytics strips control and bidirectional characters from every value it returns and tells the model explicitly that returned text is data, never instructions. Keep that assumption in your own prompts too.
Revoke a key any time. Deleting the key in your account settings cuts off the agent immediately.

Treat the key in your MCP configuration like a password. Prefer a per-machine key you can revoke on its own, keep it out of committed files, and revoke it if a laptop or configuration file is ever exposed.

Troubleshooting

What you see	What it means
Your client tries to log you in, or reports a failed connection mentioning OAuth or an unexpected `<!DOCTYPE html>` response	The `Authorization` header is missing. The server answers `401`, and clients that see no header attempt an OAuth flow that doesn’t exist yet. Add the header.
`The API key was not recognized`	Stray whitespace, a wrapped line, or a missing `Bearer` prefix in the header.
`This API key has expired` or `is disabled`	Create a new key from the API keys card under Settings → Account.
A tool returns `403`	Your key’s user can’t access that site, or the action needs a higher organization role. Ask the agent to list your sites to see what the key reaches.
A tool returns `404` for an ID	The ID is wrong. Ask the agent to list goals, funnels, dashboards, or annotations to get valid IDs.
`Wrong path. The MCP endpoint is POST /api/mcp`	The URL has a trailing slash or an extra segment. Use exactly `https://dash.tinyanalytics.io/api/mcp`.
`Rate limit reached for this API key`	You’ve passed 120 requests in a minute. Wait for the window, then ask for fewer, more aggregated results.
`The MCP endpoint is temporarily disabled`	The endpoint is switched off on that deployment. On self-hosted instances, check `MCP_ENABLED`.

Frequently asked questions

What is the tinyanalytics MCP server?

It’s an endpoint at https://dash.tinyanalytics.io/api/mcp that exposes your analytics to AI agents as 47 callable tools over the Model Context Protocol. You connect a client such as Claude Code, Cursor, VS Code, or Codex CLI with your API key, then ask questions in plain language instead of writing HTTP requests.

Do I need a special key or a paid plan for MCP?

No. MCP uses the same API key as the rest of the API, created under Settings → Account, and it reaches exactly the sites that key’s owner can reach.

Can I connect claude.ai or ChatGPT?

Not yet. Both require OAuth for custom connectors, and the tinyanalytics MCP server currently authenticates with an API key sent as a request header. Support for OAuth is planned. Today the endpoint works with developer clients that let you set a header: Claude Code, Cursor, VS Code, and Codex CLI.

Can an agent delete my analytics data?

No. On tinyanalytics cloud the delete tools aren’t offered at all, and neither is changing a site’s tracking configuration — so the actions that can’t be undone are unavailable to an agent. An agent can still create and update goals, funnels, dashboards, and annotations, and those changes are visible to your whole team.

How is this different from Ask AI inside tinyanalytics?

Ask AI lives in the tinyanalytics dashboard and answers questions there. The MCP server brings the same data into the AI tool you already work in, so an agent can combine your analytics with your codebase — for example, checking whether a page you just changed is losing visitors.

Do I still need the HTTP API?

Only if you’re writing code. MCP is for AI agents working on your behalf; the HTTP API is for applications and scripts you build. Both use the same key and return the same data.

API keys

Create the key your agent will use.

API reference

The HTTP API behind every MCP tool.

Ask AI

Ask questions inside the tinyanalytics dashboard.

Use docs with AI

Give an assistant these documentation pages.

Rate limits & CORS

The other limits that apply to API traffic.

SQL query API

The read-only SQL an agent runs for you.

Start here

Core API

Authentication & tools

Endpoint reference

Connect an AI Agent with the MCP Server

What can an agent do through MCP?

Which AI clients can connect today?

How do I connect my agent?

What should I ask first?

Do I need to give dates?

How many requests can an agent make?

Is it safe to connect an agent?

Troubleshooting

Frequently asked questions

API keys

API reference

Ask AI

Use docs with AI

Rate limits & CORS

SQL query API

​What can an agent do through MCP?

​Which AI clients can connect today?

​How do I connect my agent?

​What should I ask first?

​Do I need to give dates?

​How many requests can an agent make?

​Is it safe to connect an agent?

​Troubleshooting

​Frequently asked questions

​Related

API keys

API reference

Ask AI

Use docs with AI

Rate limits & CORS

SQL query API

What can an agent do through MCP?

Which AI clients can connect today?

How do I connect my agent?

What should I ask first?

Do I need to give dates?

How many requests can an agent make?

Is it safe to connect an agent?

Troubleshooting

Frequently asked questions

Related