> ## 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.

# MCP

> Connect AI clients to your Cevoid workspace through the Cevoid MCP server

## 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](/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](/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:

```text theme={"system"}
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.
* 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

<table>
  <thead>
    <tr>
      <th>Category</th>
      <th>Tool</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td rowSpan="1">Workspace</td>
      <td><code>list-workspaces</code></td>
      <td>List the workspaces this MCP session can access.</td>
    </tr>

    <tr>
      <td rowSpan="9">Analytics</td>
      <td><code>list-reports</code></td>
      <td>List saved analytics reports and curated presets for an authorized workspace.</td>
    </tr>

    <tr>
      <td><code>run-query</code></td>
      <td>Query Cevoid analytics directly with a schema-first query object.</td>
    </tr>

    <tr>
      <td><code>get-query-schema</code></td>
      <td>Inspect the supported analytics query schema for a module.</td>
    </tr>

    <tr>
      <td><code>get-report</code></td>
      <td>Get metadata for a saved analytics report by report ID.</td>
    </tr>

    <tr>
      <td><code>run-report</code></td>
      <td>Execute a saved analytics report by report ID and date range.</td>
    </tr>

    <tr>
      <td><code>list-dimensions</code></td>
      <td>List the currently available analytics dimensions and metadata for a module.</td>
    </tr>

    <tr>
      <td><code>get-filter-values</code></td>
      <td>Get valid values for a specific analytics filter.</td>
    </tr>

    <tr>
      <td><code>create-report</code></td>
      <td>Validate and create a custom analytics report.</td>
    </tr>

    <tr>
      <td><code>update-report</code></td>
      <td>Validate and update a custom analytics report.</td>
    </tr>

    <tr>
      <td rowSpan="4">Dashboard</td>
      <td><code>list-dashboards</code></td>
      <td>List analytics dashboards in a workspace.</td>
    </tr>

    <tr>
      <td><code>get-dashboard</code></td>
      <td>Get a dashboard and its report panels.</td>
    </tr>

    <tr>
      <td><code>create-dashboard</code></td>
      <td>Create a dashboard with validated or automatically placed panels.</td>
    </tr>

    <tr>
      <td><code>update-dashboard</code></td>
      <td>Update a custom dashboard and its panel layout.</td>
    </tr>
  </tbody>
</table>

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.

## Related

* [Analytics overview](/analytics/overview)
* [Authentication](/api-reference/authentication)
* [Developer Docs Overview](./index)