Skip to main content

​
Overview

Use this page when you want to connect an MCP-compatible client to Cevoid and understand the current analytics-focused MCP surface. The Cevoid MCP server is Cevoid’s hosted MCP server for connecting AI clients to your Cevoid workspaces. You can use it to give tools like Claude, Cursor, and ChatGPT secure access to Cevoid context through a single MCP endpoint. The current MCP surface is Analytics. You can query UGC, Loyalty, and Profiles analytics; inspect shared metrics, dimensions, and filters; and manage reports and dashboards without leaving your AI tool. 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 analytics or set up reports and dashboards without building your own API layer first. Use the API Reference instead when you want direct REST integrations from your own application code.

​
Connect

Use https://mcp.cevoid.com/mcp as the MCP server URL. Use a client that supports MCP over streamable HTTP and OAuth-based authentication, such as Claude, Cursor, or ChatGPT.

​
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 or workspaces you want to query.
  4. Start with run-query for direct questions, list-reports for discovery, or create-report to save a setup.

​
Verify the connection

Your first successful result should be a schema-first analytics answer from run-query or a report catalog response from list-reports. Try a prompt like:
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 for authentication. Access tokens are short-lived, resource-bound to the Cevoid MCP endpoint, and carry both principal and authorized workspace identity. Clients can maintain sessions with rotating refresh tokens.
  • Access is scoped to the workspace or workspaces selected during authorization.
  • Read tools require analytics:read. This can include entity and profile labels used in analytics dimensions and intentional filter searches. Report and dashboard writes require explicit analytics:write consent. The connect page shows the requested scopes and lets you grant a subset.
  • Clients should use the advertised Protected Resource Metadata and include the Cevoid MCP endpoint as the OAuth resource.
  • Clients can identify themselves with OAuth Client ID Metadata Documents or Dynamic Client Registration.

​
Client implementer details

Use the discovery documents instead of hard-coding OAuth endpoints where your client supports discovery.
  • MCP endpoint: https://mcp.cevoid.com/mcp
  • OAuth resource: https://mcp.cevoid.com/mcp
  • OAuth scopes: analytics:read; request analytics:write as well when the client should manage reports or dashboards
  • Protected Resource Metadata: https://mcp.cevoid.com/.well-known/oauth-protected-resource/mcp
  • Authorization Server Metadata: https://mcp.cevoid.com/.well-known/oauth-authorization-server
  • Client identification: OAuth Client ID Metadata Documents are supported. Dynamic Client Registration is available as a fallback.
  • Token revocation: supported through the advertised OAuth revocation endpoint.
Access tokens expire after 15 minutes. Refresh tokens rotate on every use and expire 30 days after the latest refresh. If a connection is not used before the refresh token expires, the client needs to reconnect through OAuth.

​
Rate limits

The main analytics tool calls are rate limited per authenticated principal.
  • run-query, run-report, and report/dashboard writes: 20 requests per minute.
  • list-reports, get-query-schema, list-dimensions, and get-filter-values: 60 requests per minute.
Rate-limited responses include rate-limit headers and a Retry-After header when the client should wait before retrying.

​
Available tools

CategoryToolDescription
Workspacelist-workspacesList the workspaces this MCP session can access.
Analyticslist-reportsList saved analytics reports and curated presets for an authorized workspace.
run-queryQuery Cevoid analytics directly with a schema-first query object.
get-query-schemaInspect the supported analytics query schema for a module.
get-reportGet metadata for a saved analytics report by report ID.
run-reportExecute a saved analytics report by report ID and date range.
list-dimensionsList the currently available analytics dimensions and metadata for a module.
get-filter-valuesGet valid values for a specific analytics filter.
create-reportValidate and create a custom analytics report.
update-reportValidate and update a custom analytics report.
Dashboardlist-dashboardsList analytics dashboards in a workspace.
get-dashboardGet a dashboard and its report panels.
create-dashboardCreate a dashboard with validated or automatically placed panels.
update-dashboardUpdate a custom dashboard and its panel layout.
Workspace IDs are returned by list-workspaces; reuse them unchanged. Report IDs use the public rpt_… format and dashboard IDs use dsh_…. Treat these IDs as opaque and reuse returned values for later get, run, update, and dashboard-panel operations. Analytics filter values are a separate contract. A returned value is an opaque token valid for that filter and authorized workspace; its format may vary. Reuse it unchanged and do not treat it as a resource ID. Profile filter discovery requires at least two search characters and returns no more than 20 minimal label/token pairs. List tools return compact selection summaries; matching get tools return complete public definitions. Result counts use returnedRowCount, meaning rows actually returned after limits. run-report.executedQuery records the effective execution settings needed to interpret saved-report results. Available resources:
  • cevoid://analytics/query-schema
  • cevoid://analytics/dimensions
  • cevoid://analytics/filters
  • cevoid://analytics/filter-values
  • cevoid://analytics/reports
  • cevoid://analytics/capabilities

​
Example prompts

  • “What reports do I already have for UGC performance?” Starts with list-reports.
  • “Show me the top performing posts for the last 30 days.” Routes to run-query.
  • “What types of analytics queries can you run for UGC?” Uses get-query-schema.
  • “Which workspaces can I access in this MCP session?” Uses list-workspaces.
  • “Create a monthly performance report and add it to a dashboard.” Uses the report and dashboard write tools after write-scope consent.