Skip to main content

MCP Server for AI Assistants

The SealMetrics MCP Server lets AI assistants like Claude (Claude Code, Claude Desktop, Claude.ai), ChatGPT, Cursor, Codex, Windsurf, VS Code, and other MCP clients query your SealMetrics analytics — traffic, conversions, campaigns, and more — in plain natural language.

There are two ways to connect, and you only need one:

Remote MCP (hosted)Local MCP (npx)
SetupPaste one URL — no installAdd an npx command with your API key
Runs onSealMetrics serversYour machine
AuthHandled by the endpoint — nothing to pasteSEALMETRICS_API_KEY in the config
Node.js requiredNoYes (v18+)
Best forCodex, Cursor, Claude, ChatGPT and any client that supports remote MCPOffline / air-gapped setups, or pinning a specific version

We recommend the remote MCP for most people — it takes about two minutes per client and there's nothing to install or keep updated. Jump to the remote setup ↓

Don't have an account yet?

Both options assume you already have a SealMetrics account and API key. If you want your AI assistant to create the account for you from the chat (no key, no terminal), use the one-click AI Agentic Package (Claude & Codex) instead.

What is MCP?​

The Model Context Protocol (MCP) is an open standard that allows AI assistants to securely connect to external data sources. The SealMetrics MCP server exposes your analytics — traffic, conversions, campaigns, and more — as tools your assistant can call in plain language, with no SQL and no dashboard. You can run it two ways: as the hosted remote server (SealMetrics runs it; you just point your client at a URL) or as the local server (it runs on your machine via npx).

What can you ask Claude?​

Once connected, you can ask questions like:

  • "Show me an overview of my site for the last 7 days"
  • "What are the top traffic sources this month?"
  • "Compare this month's conversions with last month"
  • "Which landing pages have the highest bounce rate?"
  • "Show me revenue by country for the last quarter"
  • "What devices do my visitors use?"
  • "Analyze my top 3 campaigns and tell me which has the best conversion rate"

The hosted remote server is the fastest way to connect. There's nothing to install and nothing to keep updated — you point your AI client at a single URL and start asking questions. It works with Claude, ChatGPT, Cursor, Codex, VS Code, and any client that supports remote (Streamable HTTP) MCP.

Endpoint:

https://mcp.sealmetrics.com/mcp

Add that URL in your client and the SealMetrics tools become available — no local install and no key to paste. If your client shows an authorization or Connect step when you add the server, follow its prompts to finish linking.

Fewer tools, lower token use

Append ?discovery=progressive to the endpoint (https://mcp.sealmetrics.com/mcp?discovery=progressive) to load tool definitions on demand instead of all at once. Every tool stays callable; your assistant just discovers them as needed, which lowers token usage on clients with tight context limits.

Claude Code​

Add the remote server with the HTTP transport (run inside your project, or add -s user to make it available in every project):

claude mcp add --transport http sealmetrics https://mcp.sealmetrics.com/mcp

Run /mcp inside Claude Code to check the connection. If it shows an authorization step, follow the prompt to finish linking.

Claude.ai & Claude Desktop​

  1. Open Settings → Connectors.
  2. Click Add custom connector.
  3. Name it SealMetrics and paste the URL: https://mcp.sealmetrics.com/mcp
  4. Click Add (then Connect if prompted).

The SealMetrics tools now appear in the connectors menu of any chat.

ChatGPT​

Remote MCP connectors are available on ChatGPT plans that support connectors (and via developer mode).

  1. Open Settings → Connectors (or Settings → Connectors → Advanced → Developer mode).
  2. Click Create / Add custom connector.
  3. Name it SealMetrics and set the MCP Server URL to https://mcp.sealmetrics.com/mcp.
  4. Save (and complete any Connect step the dialog shows).

Once connected, enable the SealMetrics connector in the composer's tools/connectors menu before asking about your data.

Cursor​

Add this to your MCP config (~/.cursor/mcp.json for all projects, or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "sealmetrics": {
      "url": "https://mcp.sealmetrics.com/mcp"
    }
  }
}

Reload Cursor and open Settings → MCP to confirm SealMetrics is listed (click Connect if it prompts you).

Codex (OpenAI)​

Add this to ~/.codex/config.toml:

[mcp_servers.sealmetrics]
url = "https://mcp.sealmetrics.com/mcp"

Restart Codex — the SealMetrics tools become available on the next session.

VS Code (Copilot) & other MCP clients​

Any client that supports remote MCP uses the same URL. In VS Code, add a .vscode/mcp.json:

{
  "servers": {
    "sealmetrics": {
      "type": "http",
      "url": "https://mcp.sealmetrics.com/mcp"
    }
  }
}
Client only supports local (stdio) servers?

A few older clients can't connect to a remote URL directly. Bridge to it with mcp-remote:

{
  "mcpServers": {
    "sealmetrics": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.sealmetrics.com/mcp"]
    }
  }
}

Verify it works​

Open your assistant and ask:

"List my SealMetrics sites"

It should respond with your sites. If it does, you're all set — skip ahead to Available tools.

Local MCP server (npx)​

Prefer to run the server on your own machine — for offline setups, or to pin a specific version? The local server runs via npx and authenticates with your API key. The steps below cover it end to end.

Step 1: Verify Node.js is installed​

Open your terminal and run:

node --version

You need v18 or higher. If you don't have it, download it from nodejs.org.

Step 2: Get your API Key​

  1. Log in to your SealMetrics dashboard at my.sealmetrics.com
  2. Go to Settings > API Keys (direct link)
  3. Click Create API Key
  4. Give it a name (e.g. "Claude MCP") and click Create
  5. Copy the key — it starts with sm_ (e.g. sm_AbCdEf123...)
Important

The full API key is only shown once. Copy it immediately and store it in a safe place.

Step 3: Find your Site ID​

  1. Go to Settings > Sites (direct link)
  2. Click on the site you want to query
  3. The Site ID is displayed at the top of the site settings page (e.g. my-store)
tip

If you only have one site, you can skip this step — just ask Claude to "list my sites" and it will find it for you.

Step 4: Configure your Claude client​

Choose the client you use:

Claude Code​

Add the server with a single command (run inside your project):

claude mcp add sealmetrics \
  -e SEALMETRICS_API_KEY=sm_your_key_here \
  -e SEALMETRICS_SITE_ID=your-site-id \
  -- npx -y @sealmetrics/mcp

Replace sm_your_key_here with your API key from Step 2, and your-site-id with your Site ID from Step 3.

Global configuration

By default the server is added for the current project. Add -s user to make SealMetrics available in all your projects.

Claude Desktop​

  1. Open Claude Desktop
  2. Go to Settings (gear icon) > Developer > Edit Config
  3. Add the following configuration:
{
  "mcpServers": {
    "sealmetrics": {
      "command": "npx",
      "args": ["-y", "@sealmetrics/mcp"],
      "env": {
        "SEALMETRICS_API_KEY": "sm_your_key_here",
        "SEALMETRICS_SITE_ID": "your-site-id"
      }
    }
  }
}
  1. Save and restart Claude Desktop completely (Cmd+Q on macOS, then reopen)
One-click alternative

You can skip the JSON entirely with the SealMetrics Claude Desktop extension — download, double-click, paste your key. The same extension can also create an account for you if you don't have one yet.

Codex (OpenAI)​

Add this to ~/.codex/config.toml:

[mcp_servers.sealmetrics]
command = "npx"
args = ["-y", "@sealmetrics/mcp"]
env = { SEALMETRICS_API_KEY = "sm_your_key_here", SEALMETRICS_SITE_ID = "your-site-id" }

Restart Codex after saving.

Cursor, Windsurf, VS Code & other MCP clients​

Any MCP-compatible client uses the same server. Add this block to your client's MCP config (in Cursor, ~/.cursor/mcp.json):

{
  "mcpServers": {
    "sealmetrics": {
      "command": "npx",
      "args": ["-y", "@sealmetrics/mcp"],
      "env": {
        "SEALMETRICS_API_KEY": "sm_your_key_here",
        "SEALMETRICS_SITE_ID": "your-site-id"
      }
    }
  }
}

Step 5: Verify it works​

Open Claude and ask:

"List my SealMetrics sites"

Claude should respond with a list of your sites. If it does, you're all set!

Configuration reference​

VariableRequiredDescription
SEALMETRICS_API_KEYYesYour API key from Settings > API Keys. Starts with sm_.
SEALMETRICS_SITE_IDNoDefault Site ID from Settings > Sites. If set, you don't need to specify the site in every query.
SEALMETRICS_BASE_URLNoAPI base URL. Default: https://my.sealmetrics.com/api/v1. Only change this for custom deployments.

Available tools​

Claude uses these tools automatically when you ask questions — you never need to call them directly. The server registers 47 tools, grouped below by category.

Sites​

ToolDescription
list_sitesList all sites (web properties) accessible with your API key, with IDs, names, and domains
get_siteGet detailed info about a specific site: name, domains, timezone, configuration, and tracking status

Overview​

ToolDescription
get_overviewDashboard KPIs: pageviews, entrances, bounce rate, conversions, revenue, with time series and optional period comparison

Traffic, sources & campaigns​

ToolDescription
get_traffic_sourcesTraffic by source (utm_source): google, facebook, direct, etc.
get_traffic_mediumsTraffic by medium (utm_medium): organic, cpc, email, referral, social, etc.
get_campaignsPerformance by campaign (utm_campaign) with entrances, conversions, and revenue
get_termsTraffic by UTM term (keyword) with source/medium/campaign/country filters
get_top_sourcesTop traffic sources ranked by entrances (compact, non-paginated)
get_top_campaignsTop campaigns ranked by entrances (compact, non-paginated)
get_top_termsTop UTM terms (keywords) ranked by entrances (compact, non-paginated)
get_top_referrersTop referrer domains ranked by entrances

Pages & content​

ToolDescription
get_pagesMetrics per page URL path: pageviews and entrances, with multi-value filters and include dimensions
get_landing_pagesLanding page performance: entrances, bounce rate, conversions
get_top_pagesTop pages ranked by page views (compact, non-paginated)
get_top_landing_pagesTop landing pages ranked by entrances (compact, non-paginated)
get_landing_pages_by_content_groupLanding page metrics grouped by content grouping
get_content_groupsMetrics grouped by content group (content_grouping)

Conversions​

ToolDescription
get_conversionsConversions by type (purchase, signup) with count, revenue, and average order value
get_microconversionsMicroconversions (add_to_cart, newsletter_signup, etc.) by type with counts
list_microconversion_typesList available microconversion type names for a site
get_microconversion_detailsDetailed breakdown of a microconversion type by source, medium, campaign, country, device, browser, OS

Raw events (event-level)​

ToolDescription
get_conversions_rawRaw conversion rows (one per event) with timestamp_utc/timestamp_local; date range capped at 31 days
get_microconversions_rawRaw microconversion rows (one per event); date range capped at 31 days
get_conversion_items_rawOne row per item inside a conversion (per-product); always includes item properties (sku, price, quantity)

Audience (geo, devices, browsers, OS)​

ToolDescription
get_countriesTraffic by country (ISO 3166-1 alpha-2) with entrances, conversions, and revenue
get_devicesDevice type, browser, and OS breakdown in a single call
get_device_typesTraffic by device type (desktop, mobile, tablet), paginated
get_browsersTraffic by browser (Chrome, Safari, Firefox, Edge...), paginated
get_operating_systemsTraffic by operating system (Windows, macOS, iOS, Android, Linux...), paginated

Channels​

ToolDescription
get_channelsTraffic grouped by channel: Paid Search, Organic, Social, Direct, Email, Referral, etc.
get_top_channelsTop channels ranked by entrances (compact, non-paginated)
list_channel_rulesList channel group rules that classify traffic into channels

Custom properties (custom dimensions)​

ToolDescription
list_property_keysList available custom property keys from conversions and/or microconversions
get_property_valuesProperty values with counts, grouped by a UTM parameter (paginated)
get_property_breakdownComplete property breakdown (pivot-table style) with counts and revenue

Funnel​

ToolDescription
get_funnelFunnel analysis with step-by-step conversion rates and dropoff

Bot detection​

ToolDescription
get_bot_statsBot detection overview: score distribution, top flags, human vs suspected-bot daily trend
get_suspicious_sessionsSessions with high bot-suspicion scores, with detected flags

Segments​

ToolDescription
list_segmentsList all segments (saved filter sets) available for a site
get_segmentGet details of a specific segment, including its filter definition

Alerts​

ToolDescription
list_alertsList alert rules: name, metric, condition, threshold, and status
get_alert_historyHistory of triggered alerts: when they fired, status, and triggering rule
get_alert_statsAlert statistics: total rules, active alerts, resolved count, acknowledgement rate

Webhooks​

ToolDescription
list_webhooksList webhook endpoints: URL, subscribed event types, and active status
list_webhook_deliveriesDelivery attempts for an endpoint: HTTP status, response time, success/failure
get_webhook_statsDelivery statistics for an endpoint: total, success rate, avg response time, failures

Tracking code​

ToolDescription
get_tracking_codeTracking pixel <script> tag plus the full JS API reference and implementation examples

Common parameters​

ParameterValuesDefaultDescription
site_idstring$SEALMETRICS_SITE_IDSite to query
periodtoday, yesterday, 7d, 30d, 90d, this_month, last_month, this_year, etc.30dTime period
compareprevious, yoynoneCompare with previous period or year-over-year
limit1-10020Max rows returned
pagenumber1Page number for paginated results
sort_byvaries per toolvariesSort field
sort_orderasc, descdescSort direction

All period values​

These are the only accepted period values (the full set is validated by the server):

PeriodDescription
todayToday
yesterdayYesterday
7d, 30d, 90dLast 7 / 30 / 90 days
12mLast 12 months
this_week, this_month, this_quarter, this_yearCurrent period
wtd, mtd, qtd, ytdPeriod to date (week / month / quarter / year)
last_week, last_month, last_quarter, last_yearPrevious period

Troubleshooting​

Remote MCP: the client doesn't show the SealMetrics tools​

Double-check the URL is exactly https://mcp.sealmetrics.com/mcp, then reload the client (or restart it). If the client shows a Connect or authorization step next to SealMetrics, complete it. In Claude Code, run /mcp to re-check the connection.

Remote MCP: connected, but "access denied" to a site​

Ask "list my sites" to confirm which sites are available, then query one of those. If a site you expect is missing, check its permissions in Settings > Sites.

Remote MCP: client won't accept a URL​

Some older clients only support local (stdio) servers. Bridge to the remote endpoint with mcp-remote — see the note above.

Local MCP: Claude doesn't see the SealMetrics tools​

  1. Claude Code: Make sure .mcp.json is in your project root and restart Claude Code
  2. Claude Desktop: Save the config file and restart the app completely (Cmd+Q on macOS)
  3. Verify Node.js 18+ is installed: node --version

"Invalid API key"​

Your API key is incorrect or expired. Go to Settings > API Keys and generate a new one.

"site_id is required"​

Either set SEALMETRICS_SITE_ID in your config, or ask Claude to "list my sites" first, then specify the site in your question.

"Access denied to site X"​

Your API key doesn't have permission for that site. Check your token permissions in Settings > API Keys.

"npx: command not found"​

Install Node.js from nodejs.org. npx is bundled with Node.js.

Test the server manually​

You can verify the server starts correctly from your terminal:

SEALMETRICS_API_KEY="sm_your_key_here" npx -y @sealmetrics/mcp

If it starts without errors, the server is working. Press Ctrl+C to stop it.

How it works​

Remote server: SealMetrics hosts the MCP server at https://mcp.sealmetrics.com/mcp. Your client connects to it over HTTPS (Streamable HTTP) and the SealMetrics tools become available — nothing runs on your machine and there's nothing to install or update.

Local server: the MCP server runs on your machine via npx and communicates with the SealMetrics API over HTTPS. No analytics data is stored locally.

Your machine                             SealMetrics cloud
┌──────────────────────────┐            ┌──────────────────────┐
│                          │            │                      │
│  Claude Code / Desktop   │            │  my.sealmetrics.com  │
│          |               │            │                      │
│  @sealmetrics/mcp  │─ HTTPS ─>│  /api/v1/*          │
│  (runs locally via npx)  │<── JSON ───│                      │
│          |               │            │                      │
│  Claude reads the data   │            └──────────────────────┘
│  and answers your query  │
│                          │
└──────────────────────────┘
  • Authenticated via X-API-Key header (your key never leaves your machine)
  • Automatic retries with exponential backoff on rate limits
  • 30-second timeout per request
  • No data stored locally

Resources​

Need help?​

Last updated on