{"title":"SuperMCP Server Documentation","format":"markdown","content":"<img src=\"smlogo.svg\" alt=\"Supermetrics\" width=\"300\"/>\n\n# Supermetrics MCP Server — Connect AI Agents to Marketing Data\n\n## Overview\n\nSupermetrics MCP Server is a Model Context Protocol server that lets AI agents and coding assistants — like Claude, Cursor, or GitHub Copilot — query live marketing data directly from Supermetrics. Connect your AI tools to 150+ platforms including Google Ads, Meta Ads, LinkedIn Ads, Google Analytics, TikTok Ads, Microsoft Ads, Pinterest Ads, Snapchat Ads, HubSpot, Salesforce, and more. A 14-day free trial is created automatically on first login.\n\n## Compatible AI Clients\n\nSupermetrics MCP works with any MCP-compatible AI client, including:\n- Claude (Anthropic)\n- Cursor\n- Windsurf\n- Cline\n- GitHub Copilot extensions\n- n8n\n- Microsoft Power Automate\n- Azure Logic Apps\n- Power Apps\n- Any application built on the MCP open standard\n\n## Features\n\n### Available Tools\n\n- **Data Source Discovery** (`data_source_discovery`): Browse available data sources and their capabilities\n- **Field Discovery** (`field_discovery`): Explore available fields and metrics for each data source\n- **Account Discovery** (`accounts_discovery`): Manage and validate connected accounts across data sources\n- **Data Query** (`data_query`): Execute data queries with real-time status updates and progress monitoring\n- **Async Query Results** (`get_async_query_results`): Retrieve results of data queries using schedule_id\n- **User Information** (`user_info`): Retrieve authenticated user profile, team information, and license details\n- **Get Today** (`get_today`): Get current date information for query parameters\n- **Contact Supermetrics** (`contact_supermetrics`): Send product feedback or create a support ticket or sales enquiry\n\n## What Can You Do With Supermetrics MCP?\n\n- Ask an AI assistant to pull last month's Google Ads spend and compare it to the previous period\n- Let a coding agent build a live marketing dashboard by querying Meta Ads and Google Analytics simultaneously\n- Automate campaign performance reporting by integrating Supermetrics into your AI workflow\n- Explore available metrics and dimensions across platforms before writing a single line of code\n- Validate account connections and troubleshoot data access issues directly from your AI client\n\n\n## Setup Instructions\n\n### Prerequisites\n\n- MCP-compatible client or development environment\n- Authentication with Supermetrics API key or OAuth\n- Supermetrics subscription — a 14-day free trial is created automatically on your first login, no credit card required\n\n### Server Endpoints\n\n- **MCP protocol**: `POST /mcp` - JSON-RPC 2.0 MCP endpoint\n- **Direct tool access**: `POST /mcp/{tool_name}` - Direct tool invocation\n- **[Health check](/health)**: `GET /health` - Server status verification\n- **[Docs (this page)](/docs)**: `GET /docs` - Server documentation\n- **[Change log](/changelog)**: `GET /changelog` - Release history and changes\n- **[Available data sources](/datasources)**: `GET /datasources` - Listing of data sources\n- **[OpenAPI 3.1.0](/openapi.json)**: `GET /openapi.json` - OpenAPI specification\n- **[Swagger 2.0](/swagger.json)**: `GET /swagger.json` - Swagger specification\n\n\n## Tool Descriptions\n\n### Data Source Discovery Tool (`data_source_discovery`)\n\nDiscover available data sources and their capabilities including supported metrics and dimensions.\n\n**Key Features:**\n- Complete data source catalog browsing\n- Capability assessment for each source\n- Integration requirement identification\n- Account type compatibility checking\n\n**Use Cases:**\n- Explore available integrations\n- Assess data source capabilities before setup\n- Plan multi-source reporting strategies\n- Validate account compatibility\n\n### Field Discovery Tool (`field_discovery`)\n\nExplore available fields, metrics, and dimensions for specific data sources with intelligent recommendations.\n\n**Key Features:**\n- Complete field catalog with descriptions\n- Field compatibility assessment\n- Custom field support detection\n\n**Use Cases:**\n- Design custom reports with appropriate fields\n- Understand available metrics before querying\n- Validate field availability for specific data sources\n\n### Account Discovery Tool (`accounts_discovery`)\n\nDiscover and validate connected accounts for specific data sources.\n\n**Key Features:**\n- Account discovery and validation\n- Credential verification\n- Account-specific capability assessment\n- Multi-account management support\n\n**Use Cases:**\n- Validate account connections\n- Discover available accounts for reporting\n- Troubleshoot account access issues\n- Manage account permissions and access\n\n### Data Query Tool (`data_query`)\n\nExecute asynchronous data queries against the Supermetrics API with comprehensive status monitoring.\n\n**Key Features:**\n- Real-time query progress tracking\n- Automatic retry logic for transient failures\n- Support for complex date ranges and filtering\n- Multi-account query support\n\n**Use Cases:**\n- Retrieve marketing performance data\n- Generate custom reports across multiple accounts\n- Export data for analysis and visualization\n- Monitor campaign metrics in real-time\n\n### Async Query Results Tool (`get_async_query_results`)\n\nRetrieve results of data queries using schedule_id for asynchronous data processing.\n\n**Key Features:**\n- Query result retrieval by schedule ID\n- Real-time status monitoring\n- Progress tracking for long-running queries\n- Automatic result formatting\n\n**Use Cases:**\n- Check completion status of async queries\n- Retrieve processed data results\n- Monitor query execution progress\n- Handle large dataset downloads\n\n### Get Today Tool (`get_today`)\n\nUtility tool providing current date information in various formats for query parameters.\n\n**Key Features:**\n- Multiple date format support\n- Timezone handling\n- Relative date calculations\n- Query parameter formatting\n\n**Use Cases:**\n- Generate dynamic date ranges for queries\n- Ensure consistent date formatting across requests\n- Handle timezone-specific reporting requirements\n\n### User Information Tool (`user_info`)\n\nRetrieve comprehensive user profile information including personal details, team information, and license status.\n\n**Key Features:**\n- Complete user profile data (name, email, user ID)\n- Team information and permissions\n- License details including status, expiration, and days remaining\n- Product information and subscription details\n- Account validation and authentication verification\n\n**Use Cases:**\n- Verify user authentication and account status\n- Check validity trial or paid license and expiration dates\n- Display user context information in applications\n- Monitor subscription status and renewal dates\n- Troubleshoot account access issues\n\n## Authentication\n\nSupermetrics MCP Server supports secure authentication through bearer tokens:\n\n### API Keys\nFormat: `Authorization: Bearer api_*`\n- Use for server-to-server authentication\n- Requires valid Supermetrics API key\n- Provides full API access based on key permissions\n\n### User Tokens (OAuth)\nFormat: `Authorization: Bearer otok_*`\n- Use for user-specific authentication via OAuth flow\n- Required for `user_info` tool to access profile and license data\n- Access limited to user's account permissions\n- URLs:\n  - MCP server: https://mcp.supermetrics.com/mcp\n  - OAuth authorization: https://api.supermetrics.com/oauth/authorize\n  - OAuth token: https://api.supermetrics.com/oauth/token\n  - OAuth refresh: https://api.supermetrics.com/oauth/token\n- We support dynamic client registration (DCR) for OAuth applications.\n\n## Troubleshooting Guide\n\n### Common Setup Issues\n\n**Authentication Failures**\n- Verify API key format starts with `api_` or `otok_`\n- Check API key has necessary permissions in Supermetrics\n- Ensure Authorization header includes `Bearer` prefix\n- Validate token hasn't expired or been revoked\n\n### Tool Execution Issues\n\n**Data Query Failures**\n- Verify account permissions for requested data sources\n- Check date range parameters are valid\n- Ensure field names match data source schema\n- Review query complexity and rate limits\n\n**Field Discovery Problems**\n- Confirm data source ID is correct and supported\n- Check account has access to specified data source\n- Verify API credentials have field discovery permissions\n- Review data source documentation for field availability\n\n**Account Management Issues**\n- Validate account IDs exist and are accessible\n- Check account permissions match requested operations\n- Ensure credentials provide account management access\n- Verify account status in Supermetrics dashboard\n\n### Performance Issues\n\n**Slow Query Responses**\n- Review query complexity and data volume\n- Consider breaking large queries into smaller chunks\n- Check network connectivity to Supermetrics MCP Server\n\n**Timeout Errors**\n- Increase client timeout settings for large queries\n- Implement proper retry logic with exponential backoff\n\n### Getting Additional Help\n\n1. **API Documentation**: Review Supermetrics API documentation for endpoint details\n2. **Network Connectivity**: Test direct API connectivity to isolate network issues\n3. **Account Validation**: Verify account status and permissions in Supermetrics dashboard\n4. **Client Configuration**: Review MCP client setup and configuration files\n\nFor persistent issues, ensure your Supermetrics account has the necessary permissions and that all authentication\ncredentials are valid and current.\n\nFor customer support, please contact dev-rnd@supermetrics.com\n\n### Links\n\n- [Supermetrics Hub](https://hub.supermetrics.com/)\n- [Knowledge base and support](https://docs.supermetrics.com/)\n- [Data source documentation](https://docs.supermetrics.com/docs/connect)\n- [Terms of service and data processing agreement](https://supermetrics.com/terms-of-service)\n- [Privacy policy](https://supermetrics.com/privacy-policy)\n","last_updated":1774991942.0,"status":"publicly_accessible","api_specs":{"openapi":"/openapi.json","swagger":"/swagger.json"}}