MCP Integration

The Model Context Protocol (MCP) lets AI assistants query your Zenovay analytics directly. Ask questions like "How many visitors did I get this week?" or "What are my top pages?" and get live data from your dashboard — without leaving your IDE or chat.

Quick Start

Connecting takes under a minute. Just add the server URL to your MCP client — OAuth handles the rest.

1. Add the MCP Server

Add the Zenovay server URL to your AI client. No API key or manual configuration required.

{
"mcpServers": {
  "zenovay-analytics": {
    "url": "https://api.zenovay.com/mcp"
  }
}
}

{
"mcpServers": {
  "zenovay-analytics": {
    "url": "https://api.zenovay.com/mcp"
  }
}
}

{
"servers": {
  "zenovay-analytics": {
    "type": "http",
    "url": "https://api.zenovay.com/mcp"
  }
}
}

{
"mcpServers": {
  "zenovay-analytics": {
    "serverUrl": "https://api.zenovay.com/mcp"
  }
}
}

You can also add it via the Claude Code CLI:

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

2. Authorize Access

When you first connect, your MCP client will open a browser window showing the Zenovay authorization page. Here you can:

• Select your team (if you belong to multiple teams)
• Set permissions for each tool category (None / Read / Write)
• Click Authorize to grant access

This is a one-time setup. Your MCP client stores the OAuth token and refreshes it automatically.

3. Start Querying

Once authorized, you can ask your AI assistant questions like:

• "List my websites"
• "How many visitors did zenovay.com get this week?"
• "What are the top 10 pages by traffic?"
• "Compare this week's bounce rate to last week"
• "Show me any anomalies in my traffic"
• "Export the last 30 days of analytics as CSV"
• "Create a new goal for my signup page"
• "Show me all my goals and their conversion rates"
• "Add an IP exclusion for our office network"

How OAuth Authorization Works

When your MCP client connects to https://api.zenovay.com/mcp, the following happens automatically:

1. Discovery — The client fetches OAuth metadata from /.well-known/oauth-authorization-server
2. Registration — The client registers itself (one-time) via Dynamic Client Registration
3. Authorization — A browser window opens showing the Zenovay consent page
4. Token Exchange — After you authorize, the client exchanges the code for an access token
5. Connected — All MCP requests use the OAuth token. It refreshes automatically when it expires.

You can view and revoke connected applications in Settings > Usage in your Zenovay Dashboard.

Connection Details

Permissions

During authorization, you choose the access level for each tool category:

Tool Categories

Rate Limits

Daily query limits are per team (shared across all connected applications):

Most tools cost 1 query. The query_analytics natural language tool costs 3 queries due to its AI processing.

Usage resets daily at 00:00 UTC. Check your remaining quota anytime with the get_api_usage tool, or in Settings > Usage in your dashboard.

Plan Enforcement

Some MCP tools are gated behind paid plans. Tools like get_session_replays, get_heatmap_data, get_revenue, and get_retention_data require a Pro or higher subscription, while export_data requires Scale or higher. Analytics queries are automatically clamped to your plan's data retention window (e.g., 1 year for Free, 2 years for Pro).

{
"jsonrpc": "2.0",
"id": 1,
"error": {
  "code": -32002,
  "message": "This feature requires a paid plan. Upgrade at https://app.zenovay.com/plans"
}
}

Managing Connected Applications

You can view and revoke OAuth tokens for connected MCP clients:

1. Go to Settings > Usage in your Zenovay Dashboard
2. Scroll to the MCP Requests section
3. View daily usage, rate limits, and connected application count
4. To revoke access, go to API Keys and manage tokens from there

Revoking a token immediately disconnects the MCP client. The client will need to re-authorize to reconnect.

Error Handling

When something goes wrong, the server returns a JSON-RPC error:

Troubleshooting

"Needs authentication" in Claude Code

This means the OAuth flow hasn't completed yet. Run claude mcp list to check status, then start a new session — it will prompt you to authorize in the browser.

Browser doesn't open for authorization

Make sure your MCP client supports OAuth 2.1. If using an older client, check for updates. The server URL alone (https://api.zenovay.com/mcp) should trigger automatic OAuth discovery.

"Invalid or expired OAuth token"

Your token has expired and automatic refresh failed. Remove the server and re-add it:

claude mcp remove zenovay-analytics
claude mcp add --transport http zenovay-analytics https://api.zenovay.com/mcp

Rate limit errors

Check your current usage with get_api_usage or in Settings > Usage. The query_analytics tool costs 3 queries — use specific tools like get_visitors (1 query) when possible.

Prompt for AI Assistants

If your AI assistant doesn't automatically detect the MCP server, you can paste this prompt to help it connect:

Connect to the Zenovay Analytics MCP server at https://api.zenovay.com/mcp

Authentication: OAuth 2.1 (automatic). When you first connect, a browser window will open for me to authorize access. No API key is needed.

Setup:
- Server URL: https://api.zenovay.com/mcp
- Transport: HTTP (Streamable HTTP, JSON-RPC 2.0)
- OAuth discovery: https://api.zenovay.com/.well-known/oauth-authorization-server

After connecting, call list_websites first to get my website IDs — every analytics tool requires a website_id parameter.

Available tool categories:
- Analytics (8 tools): visitors, pages, traffic sources, geographic data, real-time
- Advanced (13 tools): funnels, goals, sessions, heatmaps, errors, revenue, uptime
- AI Insights (4 tools): AI-generated insights, anomalies, weekly digest, recommendations
- Management (29 tools): website settings, goals, funnels, tracking, reports
- Settings (16 tools): IP exclusions, notifications, team members, domains
- Webhooks (6 tools): webhook CRUD, deliveries, automation rules

Rate limits: Free 25/day, Pro 100/day, Scale 500/day, Enterprise 10,000/day. The query_analytics tool costs 3 queries; all others cost 1.

Next Steps

• Tools Reference — Full documentation of all tools with parameters and examples
• Permissions & Limits — Access modes, rate limits, and error codes