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 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.

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.

2. Set up in your agent

Grok, Claude.ai, and ChatGPT connectors

On Grok 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.

Grok CLI

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:

[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:

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}"

Cursor

Add the server URL. Cursor will open a browser so you can sign in. That connection appears under Connections.

{
  "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.

Claude Code

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.

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:

{
  "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.

Codex

[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.

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, 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.

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.