# Tinylytics MCP

Connect Grok, Claude, Cursor, Codex, ChatGPT, or any MCP client to your Tinylytics account.

If the owner does not have an account yet, follow the [instructions for agents](/docs/agent_signup) and wait for them to activate before connecting here.

**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: paste the server URL into your agent or a custom connector, then sign in and pick an access level. The agent receives a key automatically. You can still paste a manual API key yourself.

Connected agents show up under Account Settings → **Connections**. Revoke one there to cut off that agent. Manual keys stay under API Access.

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-connectors"></span>
### Grok, Claude.ai, and ChatGPT connectors

On [Grok Connectors](https://grok.com/connectors), Claude.ai custom connectors, or ChatGPT custom connectors:

1. Add a custom connector.
2. Paste `https://tinylytics.app/mcp` as the server URL.
3. Sign in to Tinylytics when the browser opens, pick read only or full access, and connect.

Manage that session later under Account Settings → Connections.

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

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

That writes `~/.grok/config.toml`. It does not sign in.

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

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

The owner authenticates in Grok. They run `/mcps`, select tinylytics, and press `i`. They sign in and pick Full access if they need to create a site.

Then reload (`/mcps`, then `r`) or start a new session. Do that before calling tools. That connection appears under Account Settings → Connections.

To skip OAuth 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 so you can sign in. That connection appears under Connections.

```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. That connection appears under Connections. 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. That connection appears under Connections. 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`. Connected agents appear under Connections. 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 |
| `list_agent_visits` / `create_agent_visit` | AI crawler visits |
| `list_spam_hits` / `delete_spam_hits` | site spam analysis |
| `list_events` / `create_event` | events |
| `create_kudo` / `delete_kudo` | kudos |
| `list_insights` | insights |
| `get_uptime` | uptime |
| `get_content` | content |
| `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.

`list_spam_hits` and `delete_spam_hits` use the same 14-day analysis as the site Spam page. Filter with `score_filter`: `all`, `review`, `high_risk`, or `very_high_risk`. `delete_spam_hits` needs a full-access key; pass `score_filter` and/or `hit_ids`. Only hits currently flagged as spam are removed.

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