Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cevoid.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Cevoid MCP server connects AI clients to your Cevoid workspace. Use it to query UGC analytics reports, discover saved reports, and inspect available metrics through natural language in clients such as Claude, Cursor, and ChatGPT that support MCP. The server currently provides analytics tools for UGC data. Authentication uses workspace-scoped OAuth 2.1 tokens. Use this page when you want to connect an MCP-compatible client to Cevoid and understand the current analytics-focused MCP surface. If you need direct REST integrations from your own application code, use the API Reference instead.

​
When to use MCP

Use MCP when you want an AI client to query Cevoid analytics data or discover available reports without building your own API layer first. Use the API Reference instead when you want direct REST integrations from your own application code.

​
Connect

Point your MCP client to the public endpoint: 
https://mcp.cevoid.com/mcp
Your client must support OAuth 2.1 and present a valid workspace access token with each request.

​
Quickstart

  1. Open an MCP-compatible client such as Claude, Cursor, or ChatGPT.
  2. Point it at https://mcp.cevoid.com/mcp.
  3. Complete the OAuth flow for the Cevoid workspace you want to query.
  4. Start with search-reports when you need to discover the right analytics report.

​
Verify the connection

Your first successful result should be a report-discovery response from search-reports. Try a prompt like: 
Which report should I use for widget engagement?
If the connection works, your MCP client should return one or more report matches instead of a generic model-only answer.

​
Authentication

The Cevoid MCP server uses OAuth 2.1. Access tokens carry both principal and workspace identity. Refresh tokens are not supported. When your client connects, it must include a valid access token scoped to the workspace you want to query. The token authorizes both the user and the workspace context for all tool calls.

​
Available tools

​
Analytics

The analytics group provides tools for querying UGC performance data. These are the currently available tools in the Cevoid MCP server.

​
search-reports

Search workspace and default saved analytics reports by natural-language query. Use this first whenever you need to discover or select a report. If you want actual analytics results, call search-reports to find the best match, then immediately call run-report with the returned reportId. When to use it:
  • User asks “which report should I use for widget engagement?”
  • User asks about report-based analytics and you do not already have a reportId
  • User wants discovery only
Inputs:
  • query (string, required): Natural-language analytics question or short report-search query
  • limit (number, optional, default 10): Maximum number of ranked report matches to return
Example input: 
{
  "query": "top performing campaign",
  "limit": 10
}
Response shape: Returns a flat array of report matches. Each result includes reportId, name, description, module, group, metrics, optional dimensions, and type.

​
get-report

Retrieve metadata for a saved report by ID. Use this when you have a reportId and need to inspect configuration, metrics, dimensions, or filters before execution. When to use it:
  • You have a reportId and need to see what the report measures
  • You want to confirm dimensions or filters before running
Inputs:
  • reportId (string, required): Saved report ID
Example input: 
{
  "reportId": "rpt_abc123"
}
Response shape: Returns a report object with reportId, name, description, module, group, metrics, optional dimensions, filters, and type.

​
run-report

Execute a saved analytics report by report ID and date range. Use this after search-reports when you want actual metrics, performance results, rankings, trends, comparisons, or totals for a time period. Always use a reportId returned by search-reports. Do not invent values. For result questions, choose the best semantic match and run the report directly if you already have a usable date range. When to use it:
  • User wants performance numbers, rankings, comparisons, trends, or totals
  • You already have a strong report match from search-reports
Inputs:
  • reportId (string, required): Saved report ID returned by search-reports
  • dateRange (union, required): Date range override. Use a preset (LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS, LAST_365_DAYS) or an object with from and to in YYYY-MM-DD format
Example input: 
{
  "reportId": "rpt_abc123",
  "dateRange": "LAST_30_DAYS"
}

{
  "reportId": "rpt_abc123",
  "dateRange": {
    "from": "2026-04-01",
    "to": "2026-04-15"
  }
}
Response shape: Returns an object with report, dateRange, and data. The response can also include optional comparisonData and meta fields. Preset date ranges are validated before execution.

​
list-metrics

List the currently available UGC analytics metrics and metadata. Use this for capability and metric-catalog questions such as “what can you track?”, “which metrics exist?”, or “what conversion metrics do you have?”. Call this directly for metric questions. Do not use it for report execution or result questions. When to use it:
  • User asks “what can you track?”
  • User wants to know which metrics exist
  • User asks about conversion metrics or other capability questions
Inputs:
  • module (string, optional, default ugc): Analytics module filter. Phase 1 only supports ugc
Example input: 
{
  "module": "ugc"
}
Response shape: Returns a flat array of metric objects. Each metric includes key, name, description, type, baseUnit, category, and module.

​
Example prompts

Use prompts like these to route naturally to the available tools:
  • Discovery: “Which report should I use for widget engagement?” → search-reports
  • Result: “Show me top performing campaigns in the last 30 days” → search-reports then run-report
  • Capability: “What conversion metrics do you have?” → list-metrics
When you ask for actual analytics results, the assistant will search for the best matching report and run it immediately with an appropriate date range. You do not need to choose between search results for result questions.