MCP agent setup

Set up analytics with your agent

Connect once, log in through your browser, and ask your coding agent to add analytics to each website. Slimlytics returns the site’s tracker and first-party proxy configuration for your agent to install.

1. Connect your agent

Create a Slimlytics account, then pick your agent. Every client uses the same Streamable HTTP endpoint with browser OAuth:

url

https://slimlytics.com/api/mcp

Claude Code

Add the server from your project directory:

claude mcp add --transport http slimlytics https://slimlytics.com/api/mcp

Start claude, run /mcp, select slimlytics, and choose Authenticate. Your browser opens the Slimlytics consent screen; after you approve, the tools load in the current session. Check the connection any time with claude mcp list or claude mcp get slimlytics.

By default the server is available only in the current project. Use --scope user to make it available everywhere you run Claude Code:

claude mcp add --transport http --scope user slimlytics https://slimlytics.com/api/mcp

To share the connection with your team, commit a .mcp.json at the repository root (or run the add command with --scope project). It contains only the URL — each teammate authenticates with their own Slimlytics login.

json

{
  "mcpServers": {
    "slimlytics": {
      "type": "http",
      "url": "https://slimlytics.com/api/mcp"
    }
  }
}

Pre-approve the read-only reporting tools in .claude/settings.json so routine questions do not prompt for permission. Leave setup_site on manual approval.

json

{
  "permissions": {
    "allow": [
      "mcp__slimlytics__list_sites",
      "mcp__slimlytics__analytics_summary",
      "mcp__slimlytics__dimension_report",
      "mcp__slimlytics__marketing_brief"
    ]
  }
}

Run reports non-interactively in scripts or CI-style jobs with print mode. Authenticate interactively once first; the stored OAuth token is reused. --allowedTools only pre-approves the reporting tools; --disallowedTools blocks setup_site even if your settings already allow it.

claude -p "Summarize last week's traffic for shop.example.com \
  with the Slimlytics MCP server. Compare it with the week before." \
  --allowedTools "mcp__slimlytics__list_sites,mcp__slimlytics__analytics_summary,mcp__slimlytics__dimension_report,mcp__slimlytics__marketing_brief" \
  --disallowedTools "mcp__slimlytics__setup_site"

For unattended jobs that must never change sites, also connect with a personal API token limited to sites:read analytics:read (see other clients). Slimlytics then rejects site setup regardless of client permissions.

Codex

Run these commands with the Codex CLI:

codex mcp add slimlytics --url https://slimlytics.com/api/mcp
codex mcp login slimlytics

The browser shows the agent name and requested permissions. Enter your Slimlytics login and select Log in and authorize. Restart your agent session to load the tools. Your password stays in the browser login flow.

In the Codex IDE, add a Streamable HTTP server in MCP settings and select Authenticate. See the official MCP guide for more connection details.

Hermes Agent

Add Slimlytics to ~/.hermes/config.yaml:

yaml

mcp_servers:
  slimlytics:
    url: "https://slimlytics.com/api/mcp"
    auth: oauth

Then authorize and test the connection. Hermes prints an authorize URL, opens your browser, and waits for the OAuth callback on a local loopback port. Inside a running session, use /reload-mcp to pick up config changes.

hermes mcp login slimlytics
hermes mcp test slimlytics

For an analyst-style assistant that should never create or change sites, expose only the reporting tools. Pair this with read-only scopes (see permissions).

yaml

mcp_servers:
  slimlytics:
    url: "https://slimlytics.com/api/mcp"
    auth: oauth
    tools:
      include: [list_sites, analytics_summary, dimension_report, marketing_brief]

Other clients

Any agent that supports remote MCP OAuth with dynamic client registration can use the same endpoint. Clients that support only static bearer tokens can send a scoped personal API token instead — for example, in Claude Code:

claude mcp add --transport http slimlytics https://slimlytics.com/api/mcp \
  --header "Authorization: Bearer $SLIMLYTICS_TOKEN"

For your own Slimlytics deployment, replace https://slimlytics.com with its public HTTPS origin.

2. Ask for analytics installation

Open your website project in the agent and provide its production domain and hosting setup:

Set up Slimlytics analytics for this website at https://shop.example.com. Use first-party anti-adblock delivery. This app runs behind Nginx. Install the routes and tracker, preserve the site’s consent policy, and verify collection.

The setup_site tool creates or reuses the site by domain. It returns a script tag, exact proxy routes, and verification URLs. The default proxy type is Caddy; your agent can choose Nginx or Apache. Repeating setup reuses the same site.

Your agent applies the returned configuration to the website using its normal repository and deployment tools. It needs access to your hosting configuration to finish deployment. Slimlytics does not independently deploy an unrelated website.

For framework or edge hosting, have your agent implement the equivalent two exact server routes. Forward to the fixed Slimlytics origin, preserve the method, body, content type, Origin, Referer, and User-Agent, strip Cookie and Authorization, and remove upstream Set-Cookie. On the collection route, send the visitor’s IP as X-Slimlytics-Client-IP and the site’s proxy key as X-Slimlytics-Proxy-Key, or locations and visitor counts will reflect your web server instead of your visitors. The returned configuration reads the key from the SLIMLYTICS_PROXY_KEY environment variable; copy the key from the site’s Anti-adblock tracking settings into your server’s private environment. tracking_setup never returns the key itself, and setup_site returns it only once, for a site it has just created. Keep the proxy key out of repositories; it is a server-side secret. Avoid caching collection responses or accepting arbitrary upstream URLs.

Prompt library

These work the same in Claude Code, Codex, and Hermes once the server is connected.

Install on a framework or edge host

Add Slimlytics to this SvelteKit app deployed on Vercel. Call setup_site for https://blog.example.com, implement the two returned proxy paths as server routes that forward to the fixed Slimlytics origin, add the script tag to the root layout, and verify both test URLs after deploying a preview.

Weekly traffic summary

Using Slimlytics, summarize traffic for shop.example.com from last Monday through Sunday. Compare it with the previous week and call out the three pages and three referrers with the biggest change.

Campaign check

Pull the campaigns report for shop.example.com for the last 14 days. Which utm_campaign values brought visitors who reached the signup goal, and which ones only produced bounces?

Daily marketing brief

Get yesterday’s marketing_brief for shop.example.com. Turn it into three concrete actions for the content team, citing the supporting numbers.

Search Console gaps

Compare search_console_report queries with the pages report for the last 28 days. List queries with many impressions but a low click-through rate, and suggest title or description changes for the matching pages.

Fleet audit

List every Slimlytics site I can access. For each one, fetch tracking_setup and check the scriptTestUrl and beaconTestUrl. Report any site whose first-party routes are missing or failing.

3. Verify first-party delivery

Install both proxy routes before adding the returned script tag. Validate the server configuration and reload it.
Open scriptTestUrl; expect JavaScript with HTTP 200.
Open beaconTestUrl; expect HTTP 200 with {"status":"ok"}. This check does not insert an event.
Load a website page and confirm the tracker and collection requests use your website’s own origin.
Confirm a page view in the dashboard or MCP reports, then check consent, SPA navigation, and unrelated application routes.

First-party anti-adblock delivery improves reliability while preserving consent, DNT, and GPC. It remains cookieless and cannot guarantee that every blocker permits tracking. For consent-controlled websites, insert the script after consent using the site’s existing consent mechanism.

Available tools

Tool	Use
`setup_site`	Create or reuse a site and get installation artifacts. Accepts name, domain, timezone, allowedOrigins, retentionDays, and serverType.
`tracking_setup`	Get the current installation configuration for an existing siteId. The proxy key is referenced as `SLIMLYTICS_PROXY_KEY`, not returned.
`list_sites`	Find the sites your account can access.
`analytics_summary`	Inspect metrics and comparisons with an explicit siteId and inclusive from/to dates.
`dimension_report`	Inspect pages, referrers, countries, devices, and campaigns.
`marketing_brief`	Get a completed-day marketing summary and supporting evidence.
`search_console_report`	Read connected Search Console data with integrations:read permission.

Keep setup predictable

Add this instruction to your website’s AGENTS.md (read by Codex and Hermes) or CLAUDE.md (read by Claude Code):

When asked to add analytics, use the Slimlytics MCP server.
Call setup_site with the production domain, name, timezone,
and available proxy serverType. Install both same-origin routes
and the returned script. Preserve consent, DNT, and GPC.
Verify both test URLs and a page view. Reuse the site on retries.
Keep account tokens and server ingestion keys out of browser code.
Report any deployment step that still needs operator access.

Permissions and reconnecting

Default permissions are sites:read sites:write analytics:read. Site setup also requires owner or administrator access. Read-only agents can request sites:read analytics:read; they cannot create or configure sites.

OAuth connections appear as MCP OAuth agent in your account’s API token settings. Revoke one there to disconnect it immediately. Access tokens last one hour and refresh automatically, so a connection stays active until you revoke it or after 90 days without use. Then reconnect with /mcp in Claude Code, codex mcp login slimlytics, or hermes mcp login slimlytics.

Clients that support only static bearer tokens can use scoped personal API tokens. Keep account tokens, passwords, and server ingestion keys out of committed configuration and browser code. Collection keys in the proxy configuration grant ingestion access only.

Self-hosting and troubleshooting

Deploy the backend and frontend together, and set SLIMLYTICS_BASE_URL to the public HTTPS origin. Database migrations run at backend startup. The included Caddy configurations route OAuth discovery to the backend.

With another proxy, route /api/*, /.well-known/oauth-authorization-server, and /.well-known/oauth-protected-resource* to the backend. Keep /p/* on the frontend for the tracker bootstrap. A 404 from OAuth discovery means the deployment or proxy routes need updating.

From a source checkout, ./scripts/connect-agent.sh https://your-analytics-domain runs the Codex connection commands. The server uses stateless Streamable HTTP; an unauthenticated POST advertises browser OAuth with HTTP 401. GET returns 405 because server-to-client SSE is not offered.