# MCP

> Connect AI clients such as Claude, Cursor and ChatGPT to your Cevoid workspace through the hosted Cevoid MCP server.

Updated: 2026-10-18
Docs index: https://docs.cevoid.com/developers/llms.txt

The Cevoid MCP server is Cevoid's hosted [Model Context Protocol](https://modelcontextprotocol.io) server. It gives AI clients such as Claude, Cursor and ChatGPT secure access to your Cevoid workspaces through a single endpoint.

Through it, a client can query UGC, Loyalty and Profiles analytics, manage reports and dashboards, and edit, preview and publish the BrandKit that reviews and emails use: styling, color schemes, fonts and custom SVG icons.

## When to use MCP

Use MCP when you want an AI client to query analytics, set up reports and dashboards or update your brand styling, without building your own API layer first.

Use the [Cevoid API](https://docs.cevoid.com/developers/api.md) instead for direct REST integrations from your own application code. For the brand team's guide to connecting an AI assistant and what it can do in the platform, see [MCP server](https://docs.cevoid.com/mcp.md) in the Help Center.

## Connect

The MCP server URL is `https://mcp.cevoid.com/mcp`. Use a client that supports MCP over streamable HTTP with OAuth, such as Claude, Cursor or ChatGPT.

## Quickstart

1. Open an MCP client such as Claude, Cursor or ChatGPT
2. Point it at `https://mcp.cevoid.com/mcp`
3. Complete the OAuth flow and choose which workspaces and permissions to grant
4. Ask your client to list your workspaces with `list-workspaces` and find the tools you need with `tool-search`
5. The client calls a discovered tool with `execute-tool` and the schema `tool-search` returned. Independent reads can run together with `execute-batch`; writes always run one at a time

## Verify the connection

Ask your client which workspaces and tools your connection can use, for example:

```text title="Prompt"
Which Cevoid workspaces and tools can I access?
```

If the connection works, the client answers with your authorized workspaces and tool categories instead of a generic answer from the model alone.

## Authentication

The Cevoid MCP server uses OAuth 2.1. Access tokens are short-lived, bound to the Cevoid MCP endpoint and carry both the principal and the authorized workspaces. Clients keep sessions alive with rotating refresh tokens.

- Access is limited to the workspaces selected during authorization.
- Analytics reads require `analytics:read`, including the entity and profile labels used in analytics dimensions and filter searches. Report and dashboard writes require `analytics:write`.
- BrandKit reads, previews, font discovery and icon discovery require `brandkit:read`. Styling changes, color scheme changes, font uploads and imports, icon overrides and publishing require `brandkit:write`.
- The connect page lets you choose which permissions to grant, and discovery only returns the tools your connection allows. Reconnect an existing client to grant BrandKit permissions.

## Client implementer details

Use the discovery documents instead of hard-coding OAuth endpoints when your client supports discovery.

| Item | Value |
| --- | --- |
| MCP endpoint | `https://mcp.cevoid.com/mcp` |
| OAuth resource | `https://mcp.cevoid.com/mcp` |
| OAuth scopes | `analytics:read`, `analytics:write`, `brandkit:read`, `brandkit:write` |
| 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, with Dynamic Client Registration as a fallback |
| Token revocation | The advertised OAuth revocation endpoint |

Request only the scopes your client needs, and send the MCP endpoint as the OAuth `resource`. Access tokens expire after 15 minutes. Refresh tokens rotate on every use and expire 30 days after the latest refresh; a client that is not used before then needs to reconnect through OAuth.

## Rate limits

Tool calls are rate limited per authenticated principal and tool:

| Tools | Limit |
| --- | --- |
| Analytics queries, report execution, BrandKit previews, and all analytics and BrandKit writes | 20 requests per minute |
| Other analytics reads, BrandKit reads, and the four discovery and execution tools | 60 requests per minute |

Calls through `execute-tool` or `execute-batch` also count toward the limit of the tool they invoke.

## Available tools

Your client finds domain tools with `tool-search` and calls them by their canonical ID through `execute-tool`. Search without a query to browse the categories.

| Category | Tool | Description |
| --- | --- | --- |
| Workspace | `list-workspaces` | List the workspaces this MCP session can access. |
| Discovery and execution | `tool-search` | Discover authorized tools and their input schemas. |
| Discovery and execution | `execute-tool` | Run a discovered tool by its canonical ID. |
| Discovery and execution | `execute-batch` | Run independent read-only calls together. Writes and previews are not accepted. |
| Analytics | `analytics.list-reports` | List saved analytics reports and curated presets for an authorized workspace. |
| Analytics | `analytics.run-query` | Query Cevoid analytics directly with a schema-first query object. |
| Analytics | `analytics.get-query-schema` | Inspect the supported analytics query schema for a module. |
| Analytics | `analytics.get-report` | Get the metadata of a saved analytics report by report ID. |
| Analytics | `analytics.run-report` | Run a saved analytics report for a report ID and date range. |
| Analytics | `analytics.list-dimensions` | List the analytics dimensions and their metadata for a module. |
| Analytics | `analytics.get-filter-values` | Get valid values for an analytics filter. |
| Analytics | `analytics.create-report` | Validate and create a custom analytics report. |
| Analytics | `analytics.update-report` | Validate and update a custom analytics report. |
| Dashboard | `analytics.list-dashboards` | List the analytics dashboards in a workspace. |
| Dashboard | `analytics.get-dashboard` | Get a dashboard and its report panels. |
| Dashboard | `analytics.create-dashboard` | Create a dashboard with validated or automatically placed panels. |
| Dashboard | `analytics.update-dashboard` | Update a custom dashboard and its panel layout. |
| BrandKit | `brandkit.get` | Read your BrandKit draft settings and draft revision. |
| BrandKit | `brandkit.update` | Update styling, typography and font or icon pack assignments in the draft. |
| BrandKit | `brandkit.preview` | Render real widgets with sample content as images, from the draft or the published BrandKit. |
| BrandKit | `brandkit.publish` | Publish the reviewed draft to live widgets and emails. |
| BrandKit | `brandkit.create-color-scheme` | Create a named color scheme, optionally as a copy of an existing one. |
| BrandKit | `brandkit.rename-color-scheme` | Rename a color scheme in the draft. Published references change when the BrandKit is published. |
| BrandKit | `brandkit.delete-color-scheme` | Delete a color scheme. At least one scheme must remain; change any popup or email assignment first. Review assignments return to their defaults when the BrandKit is published. |
| BrandKit | `brandkit.list-fonts` | Browse default and workspace fonts. |
| BrandKit | `brandkit.prepare-font-upload` | Prepare the upload of a local font file. |
| BrandKit | `brandkit.complete-font-upload` | Validate and register an uploaded font. |
| BrandKit | `brandkit.import-font-from-url` | Import a font from a public file URL. |
| BrandKit | `brandkit.list-icon-packs` | Browse the available icon packs. |
| BrandKit | `brandkit.list-icons` | Inspect the editable icon slots and their current SVGs. |
| BrandKit | `brandkit.set-icons` | Replace existing icon slots with custom SVGs. |
| BrandKit | `brandkit.reset-icons` | Restore selected icons to their icon pack or bundled defaults. |

### IDs and filter values

Workspace IDs come from `list-workspaces`; reuse them unchanged. Report IDs use the public `rpt_…` format and dashboard IDs use `dsh_…`. Treat these IDs as opaque, and reuse the 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, and its format may vary. Reuse it unchanged and never treat it as a resource ID. Profile filter discovery needs at least two search characters and returns at most 20 label and token pairs.

List tools return compact summaries for choosing an item; the matching get tools return complete public definitions. Result counts use `returnedRowCount`, the rows actually returned after limits. `analytics.run-report.executedQuery` records the execution settings you need to interpret the results of a saved report.

### BrandKit changes

BrandKit tools edit a shared draft. Each change saves right away, updates open BrandKit editors and replaces unsaved edits there, but live widgets and emails keep the published BrandKit until the draft is published, with `brandkit.publish` or in the BrandKit editor. The tools tell clients to publish only when you ask for it.

- **Publishing:** pass the draft revision from `brandkit.get` or from the last draft edit. A stale revision is rejected; review the changed draft, then publish again.
- **Previews:** `brandkit.preview` renders up to three components per call as images, from the draft by default or from the published BrandKit. It does not edit or publish anything.
- **Writes:** settings, scheme and icon writes do not take a revision, so a later write can overwrite an earlier one. A write that collides with another draft save is rejected with `draft_changed`; read the draft again and retry. Omitted settings stay unchanged, and `null` resets a setting to its default or inherited value. Dimensions are in pixels, line height is a multiplier and letter spacing is in em.
- **Fonts:** for a local font, prepare the upload, send the file to the returned URL, then complete the registration. You can also import a public WOFF2, WOFF, TTF or OTF file of up to 10 MB; URL redirects are rejected. Assign the returned font ID to typography or buttons with `brandkit.update`.
- **Icons:** custom icons replace existing editable slots. Supply a complete monochrome SVG with a `viewBox`, up to 16 KiB per icon; active content and external resources are rejected. Icons inherit the theme color, and rating stars use the BrandKit star design setting. Reuse font and icon pack IDs from discovery unchanged.

### Resources

These analytics resources require `analytics:read`:

- `cevoid://analytics/query-schema`
- `cevoid://analytics/dimensions`
- `cevoid://analytics/filters`
- `cevoid://analytics/filter-values`
- `cevoid://analytics/reports`
- `cevoid://analytics/capabilities`

## Example prompts

The client discovers the relevant tool before it runs it.

| Prompt | Tools |
| --- | --- |
| "What reports do I already have for UGC performance?" | Starts with `analytics.list-reports` |
| "Show me the top performing posts for the last 30 days." | `analytics.run-query` |
| "What types of analytics queries can you run for UGC?" | `analytics.get-query-schema` |
| "Which workspaces can I access in this MCP session?" | `list-workspaces` |
| "Create a monthly performance report and add it to a dashboard." | The report and dashboard write tools, after write-scope consent |
| "Set my BrandKit accent color to green and make buttons rounder." | `brandkit.get` and `brandkit.update`, after BrandKit write-scope consent |
| "Import this font file and use it for headings." | The BrandKit font tools, then `brandkit.update` to assign the font |
| "Generate a simple close icon and apply it to my BrandKit." | `brandkit.list-icons`, then `brandkit.set-icons` |
| "Preview my BrandKit draft on mobile, then publish it." | `brandkit.preview`, then `brandkit.publish` after BrandKit write-scope consent |

## Related

- [MCP server](https://docs.cevoid.com/mcp.md): connect an AI assistant to ask about analytics, build reports and dashboards and edit the BrandKit, explained for the brand's team.
- [Cevoid API](https://docs.cevoid.com/developers/api.md): REST integrations with scoped secret keys.

**Recent changes**

- [Full access and read-only presets for API keys and MCP connections](https://docs.cevoid.com/developers/changelog.md#2026-10-09-access-presets) (Added, 2026-10-09): API keys and MCP connections can be granted Full access (\*) or Read only (\*:read), which also cover scopes added later, and their access can now be edited instead of revoked and recreated.
- [MCP authorization metadata at the path-suffixed URL](https://docs.cevoid.com/developers/changelog.md#2026-10-08-mcp-authorization-metadata) (Fixed, 2026-10-08): The MCP server also serves its OAuth authorization server metadata at /.well-known/oauth-authorization-server/mcp, the RFC 8414 location clients such as Claude Code look up, and clients with a stale token can authorize again.
- [MCP clients can edit BrandKit](https://docs.cevoid.com/developers/changelog.md#2026-09-29-brandkit-tools-in-mcp) (Added, 2026-09-29): New BrandKit tools let an MCP client read and change the styling, color schemes, fonts and icons that reviews and emails use, behind the new brandkit:read and brandkit:write scopes.

[All MCP changes in the changelog](https://docs.cevoid.com/developers/changelog.md)

---

Canonical: https://docs.cevoid.com/developers/mcp