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 full-access or restricted API key as the HTTP API. Point your agent at one endpoint and it can answer traffic questions, create goals and funnels, and build dashboards without you writing 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. To teach an agent the procedure for setting up and operating TinyAnalytics, see Agent Skills, which pair well with this server.

What can an agent do through MCP?

The complete server catalog contains 57 tools in nine domains. A full-access key receives the 50 default tools. A restricted key receives only the tools allowed by its selected resources; an explicit matching write grant can also expose the catalog’s gated configuration or delete tool for that resource.

You ask for	Tools the agent uses
Traffic questions	Overview totals, metric time series (or one sessions series per value of a dimension — `get_timeseries` with `dimension`, for example `ai_assistant` to see which assistant is rising), breakdowns by 18 dimensions (with an optional `first_seen` date per value), 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, user-trait reads (`get_user_traits`: keys, values of one key, or users matching key=value), and profile-trait management (`merge_user_traits` sets only the keys you send; `update_user_traits` replaces all traits)
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 — optionally probing for an `identify()` trait key with `check_tracking`’s `trait_key` argument — and get the dashboard link

The analytics-report tools also accept a trait:<key> filter — for example “breakdown by page for users whose plan is pro” — which scopes the report to identified users by a trait’s current value. Trait filters need a key with Users: Read and never match anonymous traffic. Every tool runs with both your key’s scopes and your account access. The agent sees only the sites you can see, a restricted key sees only granted tools, and writes are refused unless your organization role also 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. For least privilege, turn on Restrict permissions and grant only what the agent needs. A traffic-reading agent usually starts with Sites: Read and Analytics: Read; add Sessions, Events, Users, Goals, Funnels, Dashboards, or Custom SQL only for those tasks.Copy the key immediately—it is shown only once. The key can never reach a site that its owner cannot access.

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 AI assistant is growing fastest — chart sessions per assistant by week.” (get_timeseries with dimension: "ai_assistant"; with a dimension set, the metric must be sessions and compare is not accepted — the tool returns an error rather than silently ignoring either)
“When did Perplexity first send us traffic?” (get_breakdown with first_seen: true, which adds each value’s all-time first appearance; session dimensions only)
“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. Browser tracking uses the keyless client API and is separate from the MCP request budget.

Is it safe to connect an agent?

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

Prefer a restricted key. Grant only the resources and read/write actions the agent needs. The MCP tool list and direct REST calls enforce the same scopes, while your organization and team permissions remain an additional boundary.
Write scopes can include permanent actions. A restricted key with an explicit matching write grant can receive configuration or delete tools for Sites, Goals, Funnels, Dashboards, Annotations, or Users. Do not grant those write scopes to an agent that only needs reads. The 50 tools on a full-access key omit these seven gated actions by default.
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`	The key lacks the required resource scope — the message names it (for example `users:read` when an agent reads user traits or applies a `trait:<key>` filter, `users:write` when it merges traits) — its owner can’t access the site, or the action needs a higher organization role. Review the key’s permissions and ask the agent to list your sites.
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 hosted endpoint is temporarily unavailable. Try again later or contact support.

Frequently asked questions

What is the TinyAnalytics MCP server?

It’s an endpoint at https://dash.tinyanalytics.io/api/mcp that exposes a 57-tool catalog over the Model Context Protocol. A full-access key receives 50 default tools; a restricted key receives the subset allowed by its scopes and may receive matching gated actions when you explicitly grant write access. Connect Claude Code, Cursor, VS Code, or Codex CLI with your API key, then ask questions in plain language.

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?

Only if you explicitly give a restricted key the matching write scope. For example, Sites: Write can expose site configuration and deletion, while Users: Write can expose user erasure. A full-access key receives 50 default tools that omit the seven gated configuration/delete actions. Use a restricted read-only key for analysis-only agents.

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.

API access and CORS

Browser-origin rules and documented API limits.

SQL query API

The read-only SQL an agent runs for you.

Start here

Browser APIs

Data 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

API access and 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

API access and 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