Permissions & Limits

This page covers how access control, rate limiting, and error handling work for the Zenovay MCP integration.

API Key Types

When creating an API key, you choose the access scope:

Site-scoped keys cannot query, modify, or even see other websites in the team. Every tool that takes a website_id parameter validates access before executing.

MCP Modes

Each API key can be configured with an MCP access mode:

Write-Protected Tools

The following tools require Read & Write mode. They will return an error if the key is in Read Only mode:

• create_goal — Create a custom conversion goal
• update_goal — Update an existing goal
• delete_goal — Delete a goal
• toggle_goal — Enable or disable a goal
• manage_funnel — Create or update a conversion funnel
• delete_funnel — Delete a funnel
• update_website_settings — Modify website configuration
• toggle_public_dashboard — Enable or disable public dashboard sharing
• toggle_cookieless_tracking — Enable or disable cookieless tracking mode
• regenerate_tracking_code — Generate a new tracking code (invalidates the old one)
• delete_website — Permanently delete a website and all its data
• add_ip_exclusion — Add an IP address to the exclusion list
• remove_ip_exclusion — Remove an IP from the exclusion list
• add_path_exclusion — Add a URL path pattern to exclude from tracking
• remove_path_exclusion — Remove a path exclusion
• update_notification_settings — Modify notification preferences
• invite_team_member — Invite a new member to the team
• remove_team_member — Remove a member from the team
• create_api_key — Create a new API key
• revoke_api_key — Revoke an API key
• update_api_key_permissions — Update API key MCP permissions
• create_uptime_monitor — Create a new uptime monitor
• delete_uptime_monitor — Delete an uptime monitor
• update_website_name — Update website display name
• update_website_timezone — Update website timezone
• update_website_domain — Update website domain
• pause_tracking — Pause analytics tracking
• resume_tracking — Resume analytics tracking
• schedule_report — Schedule a recurring report
• cancel_report — Cancel a scheduled report
• set_revenue_currency — Set the revenue display currency
• add_allowed_domain — Add a domain to the CORS whitelist
• remove_allowed_domain — Remove a domain from the CORS whitelist
• request_data_deletion — Delete visitor data for GDPR compliance

All other tools work in both modes.

Feature Group Permissions

MCP tools are organized into 8 feature groups. Each group can be enabled or disabled independently per API key:

When a feature group is disabled, its tools will not appear in tools/list and calls to them will return an error.

API Key Scope Requirements

Some tools have additional restrictions based on your API key type:

Plan-Gated Features

Certain tools are tied to features that require specific subscription plans:

Plan Enforcement

Zenovay MCP enforces plan limits at the server level. This section covers feature gating, data retention windows, and resource quotas.

Feature-Gated Tools

The following tools require a Pro or higher subscription plan. Free plan users calling these tools receive error code -32002 with the message: "This feature requires a paid plan."

Data Retention Limits

Analytics queries are automatically clamped to your plan's data retention window. If your query requests data older than your plan allows, the server adjusts the date range and includes a note in the response.

For example, a Free plan user can only query the last 30 days of data. Requesting a longer time_range is automatically clamped, and the response includes a retention_note field explaining the limitation.

Quota Limits

Resource creation is limited by plan. Attempting to exceed these limits returns error code -32002.

Rate Limits

Daily Query Limit

Each team has a daily MCP query budget based on their subscription plan:

Important: The daily limit is per team, not per API key. All API keys in the same team share the daily quota.

Usage resets at 00:00 UTC every day.

Query Cost

Most tools cost 1 query. The exception:

Per-Minute Rate Limit

In addition to the daily limit, there is a per-minute rate limit of 20 requests per minute per API key to prevent abuse.

Checking Your Usage

Use the get_api_usage tool to check remaining quota at any time:

{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
  "name": "get_api_usage",
  "arguments": {}
}
}

The response includes mcp.queries_today, mcp.queries_limit, and mcp.reset_at.

Error Codes

MCP uses standard JSON-RPC 2.0 error codes plus custom Zenovay error codes:

Standard JSON-RPC Errors

Zenovay MCP Errors

Error Response Format

{
"jsonrpc": "2.0",
"id": 1,
"error": {
  "code": -32003,
  "message": "Daily query limit exceeded. Upgrade at https://app.zenovay.com/settings"
}
}

Common Error Scenarios

Security Best Practices

1. Use site-scoped keys when you only need to monitor a single website
2. Keep keys in Read Only mode unless you need to create goals or funnels
3. Disable unused feature groups to minimize the attack surface
4. Rotate keys regularly — delete old keys and create new ones from the dashboard
5. Never commit API keys to source control — use environment variables or secrets managers
6. Monitor usage — check get_api_usage periodically for unexpected activity