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. That means you can query UGC analytics, browse saved reports, inspect the query schema, and discover dimensions and filters 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 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

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 analytics questions, or list-reports when you need to browse curated report presets.

​
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: 
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 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.
  • The server exposes tools for read-only analytics workflows in Phase 1.
  • 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 scope: mcp:tools
  • 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 and run-report: 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.
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.