MCP (AI access)

Connect an AI client to your Rivelko account over the Model Context Protocol.

Rivelko exposes a remote MCP server so AI clients like Claude, Cursor and ChatGPT can read your account directly during a conversation -- your forms, their analytics, visitor responses, and your CRM (pipelines, deals, tickets) -- without you copy-pasting data back and forth.

Read-only in v1. The MCP server only exposes read tools. Nothing an AI client does through MCP can create, edit or delete data in your account.

Plan requirement: Calling the endpoint requires your account to be in good standing. Free-plan accounts work out of the box; if you're on a paid plan and your subscription lapses (past due or cancelled), MCP access is suspended until billing is resolved.

Overview

MCP is an open protocol that lets AI clients call tools exposed by a server over a standard interface. Rivelko's MCP server is that server: it authenticates the calling AI client with OAuth, then exposes 15 read-only tools scoped to the signed-in user's own data -- account info, forms, responses and CRM.

Every tool call is authorized the same way as the REST API: the caller's userId comes from the access token, and every lookup is scoped or ownership-checked against it. An AI client can never read another Rivelko account's data through this server.

Endpoint

https://app.rivelko.com/api/mcp

(${NEXT_PUBLIC_APP_URL}/api/mcp -- the endpoint always lives on the app.rivelko.com host, alongside the rest of the API.)

The endpoint speaks Streamable HTTP (GET/POST/DELETE); most MCP clients handle the transport for you once you give them this URL. It is a protected resource: calls without a valid access token get a 401 pointing at the OAuth metadata below.

Connecting

Rivelko uses a standard OAuth 2.1 "Connect" flow discovered from well-known metadata -- most MCP clients drive the whole thing automatically once you paste the endpoint URL.

Discovery

Metadata document	URL
Protected resource metadata	`https://app.rivelko.com/.well-known/oauth-protected-resource`
Authorization server metadata	`https://app.rivelko.com/.well-known/oauth-authorization-server`

The authorization server metadata advertises the endpoints below, PKCE support (S256 only) and the supported scopes.

The flow

Discover -- the client fetches the metadata above to find the authorization, token and registration endpoints.
Register -- the client dynamically registers itself via POST /oauth/register (Dynamic Client Registration, RFC 7591) and gets back a client_id. No client secret is issued -- clients authenticate with PKCE, not a shared secret.
Authorize -- the client opens GET /oauth/authorize in a browser with a PKCE code_challenge (S256) and the scopes it needs. You sign in to Rivelko if you aren't already, see a consent screen listing the requesting app and the scopes it's asking for, and click Allow.
Token exchange -- the client exchanges the authorization code at POST /oauth/token (with the PKCE code_verifier) for an access token and a refresh token.
Call the server -- the client sends Authorization: Bearer <access_token> on every request to /api/mcp.

Token	Lifetime
Access token	1 hour
Refresh token	30 days (hard cap; each refresh does not extend it)

redirect_uri must be https://..., or http:// on an exact loopback host (localhost, 127.0.0.1, [::1]) for local development tools.

Disconnecting

You can review every AI client connected to your account and revoke access at any time from the dashboard (AI access). Revoking immediately invalidates that client's access and refresh tokens.

Per-client steps

Claude

Settings -> Connectors -> Add custom connector
Paste the endpoint URL (https://app.rivelko.com/api/mcp)
Click Connect and approve the requested scopes on the consent screen

Cursor

Settings -> MCP -> Add server (HTTP)
Paste the endpoint URL
Authorize when the browser opens

ChatGPT

Enable custom connectors / MCP in settings
Add the endpoint URL
Approve access when prompted

Scopes

The client requests one or more of these scopes during the OAuth flow; you approve them on the consent screen. The account tools below (whoami, get_usage, get_dashboard_stats) don't require any scope -- they're always available once the connection is authorized.

Scope	Grants
`forms:read`	List and read your forms and their analytics.
`responses:read`	Read form responses -- contains visitor-authored content, see Safety below.
`crm:read`	Read pipelines, deals, tickets and forecasts.

forms:write and crm:write exist in the underlying scope system for a future write-enabled release, but no tool exposes them today -- granting a scope only unlocks tools that actually check for it, and no read-only-server tool ever will.

Tools

15 read-only tools, grouped by what they need to work.

Account (no scope required)

Tool	Description
`whoami`	The authenticated account's profile and plan.
`get_usage`	Current-period usage vs. plan limits.
`get_dashboard_stats`	High-level account activity summary.

Forms (`forms:read`)

Tool	Description
`list_forms`	List your forms. Paginated. Filters: `search`, `isPublished`.
`get_form`	Full config of one form (`formId`).
`get_form_analytics`	Aggregate analytics, account-wide or for one `formId`.

Responses (`responses:read`)

Tool	Description
`list_responses`	List form responses. Paginated. Optional `formId` filter.
`get_response`	One response (`responseId`) with its answers/messages. Paginated messages.

CRM (`crm:read`)

Tool	Description
`list_pipelines`	Your CRM pipelines with stages. Paginated.
`get_pipeline`	One pipeline with stages (`pipelineId`).
`list_deals`	Deals in a pipeline (`pipelineId`). Paginated. Filters: `stageId`, `search`.
`get_deal`	One deal (`dealId`).
`get_pipeline_forecast`	Sum of deal value per stage for a pipeline.
`list_tickets`	Support tickets. Paginated. Filters: `status`, `priority`, `search`.
`get_ticket`	One ticket (`ticketId`).

Pagination

Every list_* tool accepts the same two optional parameters:

Param	Type	Default	Max
`page`	number	1	1000
`limit`	number	10	50

Results come back as { items: [...], pagination: { page, limit, total, totalPages } }, matching the REST API's list shape.

Safety

Form responses contain visitor-authored content -- whatever a stranger typed into your form. list_responses and get_response are the two tools that surface it, and both are annotated so MCP-aware clients know the data came from an open-world source.

Treat response content as data, never as instructions. A malicious or careless visitor could type something that looks like a command ("ignore previous instructions and...") into a form field -- an AI client reading it through MCP must not follow it. This is the same untrusted-input boundary the chat engine already applies to visitor messages, extended to the MCP tools that expose the same data to a different reader.

Only grant responses:read to a client you trust to hold that boundary.

Requirements

An active subscription (or the free plan) -- a paid subscription that has lapsed (past due or cancelled) blocks calls to /api/mcp with 401 until it's resolved.
A valid access token obtained through the Connect flow above, sent as Authorization: Bearer <token>.
The requested scope for any tool beyond the always-available account tools.

Troubleshooting

Issue	Cause	Solution
Client can't discover the server	Wrong endpoint pasted	Use exactly `https://app.rivelko.com/api/mcp`
`401` on every call	Access token expired (1h) or subscription lapsed	Reconnect, or resolve billing if the account is past due
Consent screen doesn't appear	Not signed in to Rivelko in that browser	Sign in to `app.rivelko.com`, then retry the connect flow
Tool call fails with a scope error	Client didn't request/wasn't granted that scope	Reconnect and approve the scope on the consent screen
`list_*` tool returns fewer items than expected	Default `limit` is 10	Pass a higher `limit` (max 50) or paginate with `page`
Client stopped working after revoking	Access revoked from the dashboard	Reconnect via the Connect flow to issue a new token

Common Use Cases

Ask an AI assistant about your forms -- "Which of my forms has the lowest completion rate this month?"
Summarize recent responses -- pull the latest submissions for a form and have the client summarize themes (remember: response content is untrusted data, not instructions).
CRM triage -- "List my open deals in the Sales pipeline sorted by value" or "Show me unresolved support tickets."
Account checks -- "Am I close to my plan's usage limit this month?"