# Tinylytics MCP

Connect Grok, Claude, Cursor, Codex, or any MCP client to your Tinylytics account with the same API keys you already use.

**Endpoint**

`https://tinylytics.app/mcp`

This is a hosted Streamable HTTP server on the main Tinylytics host. There is no separate `mcp.` subdomain.

<span id="quick-start"></span>
## 1. Quick Start

The easiest path is browser connect: add the server URL, then sign in and create a key marked **MCP**. The agent receives that key automatically. You can still paste a key yourself.

The server uses the same rate limit as the HTTP API: 1000 requests per hour per key. Clients must send `Accept: application/json, text/event-stream`. Most MCP clients do this automatically.

<span id="set-up-in-your-agent"></span>
## 2. Set up in your agent

<span id="grok"></span>
### Grok

```bash
grok mcp add --transport http tinylytics https://tinylytics.app/mcp
```

Or add this to `~/.grok/config.toml`:

```toml
[mcp_servers.tinylytics]
url = "https://tinylytics.app/mcp"
```

Reload with `/mcps` and press `r`. Grok will open a browser so you can sign in and create an MCP key. That key appears on Account Settings → API Access with an **MCP** badge.

To skip the browser and use an existing key:

```bash
export TINYLYTICS_API_KEY="tly-ro-your-api-key"
grok mcp add --transport http tinylytics https://tinylytics.app/mcp \
  --header "Authorization: Bearer ${TINYLYTICS_API_KEY}"
```

<span id="cursor"></span>
### Cursor

Add the server URL. Cursor will open a browser to sign in and create an MCP key.

```json
{
  "mcpServers": {
    "tinylytics": {
      "url": "https://tinylytics.app/mcp"
    }
  }
}
```

Put that in `.cursor/mcp.json` or `~/.cursor/mcp.json`. To skip the browser, add an `Authorization` header with an existing key.

<span id="claude-code"></span>
### Claude Code

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

Claude opens a browser so you can sign in and create an MCP key. Add `--header "Authorization: Bearer ${TINYLYTICS_API_KEY}"` only if you want to skip that.

<span id="claude-desktop"></span>
### Claude Desktop

If your Claude Desktop build accepts a remote HTTP server, use the same JSON as Cursor in:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

If it only launches local stdio servers, bridge to the hosted endpoint:

```json
{
  "mcpServers": {
    "tinylytics": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://tinylytics.app/mcp",
        "--header",
        "Authorization: Bearer ${TINYLYTICS_API_KEY}"
      ]
    }
  }
}
```

Restart Claude Desktop. Look for the MCP tools icon to confirm the connection.

<span id="codex"></span>
### Codex

```toml
[mcp_servers.tinylytics]
url = "https://tinylytics.app/mcp"
```

Add that to `~/.codex/config.toml`. Codex should prompt you to sign in and create an MCP key. Use a header only if you already have a key.

<span id="generic"></span>
### Any other MCP client

Point the client at `https://tinylytics.app/mcp` with no header. If it supports MCP OAuth, it will open `/oauth/authorize`. If it only supports static headers, create a key under API Access and send `Authorization: Bearer tly-ro-…`.

## 3. Team accounts

API keys stay personal. Tools that act on sites or groups accept optional `account_id`.

1. Call `list_accounts` (or `get_me`) to see personal and team accounts.
2. Pass a team `id` as `account_id` on later tools.
3. Omit `account_id` to stay on the personal account.

Team viewers can read the owner's sites and groups. Team admins can create, update, and delete the owner's sites. Team owners can also create, update, and delete the owner's groups.

This MCP server is for your own Tinylytics sites. It does not include sites provisioned through [Analytics for SaaS](/analytics-for-saas), the separate product for embedding Tinylytics in your own app. Those tenant sites have their own API.

## 4. Tools

Each tool maps to one API v1 endpoint.

| Tool | API |
| --- | --- |
| `get_me` | `GET /api/v1/me` |
| `list_accounts` | `GET /api/v1/accounts` |
| `list_sites` / `get_site` / `create_site` / `update_site` / `delete_site` | sites |
| `update_site_features` | `PATCH /api/v1/sites/:id/features` |
| `list_hits` / `create_hit` | hits |
| `create_event` | events |
| `create_kudo` / `delete_kudo` | kudos |
| `list_insights` | insights |
| `get_uptime` | uptime |
| `list_groups` / `get_group` / `create_group` / `update_group` / `delete_group` | groups |

Use `site_id` and `group_id` in tools instead of putting ids in the URL path.

Full request fields and response shapes match the [HTTP API](/docs/api).