> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bevits.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP server
> Connect Claude Code, Codex, and other agents to your organization's data through MCP.
The Bevits **MCP (Model Context Protocol)** server lets your agent query your
organization's data directly, without copying spreadsheets or pasting API
responses into the chat. Instead of teaching the agent how to use the REST API,
you connect once and it sees customers, purchases, segments, tags, attributes,
flows, and email campaigns as native tools.
**Endpoint:** `https://api.bevits.com/mcp` · **Transport:** Streamable HTTP ·
**Authentication:** OAuth 2.1 · **Access:** read-only · **20 tools**
The connection uses OAuth, so no API key is pasted into the agent's
configuration. You sign in to Bevits in the browser, pick the organization, and
approve access. The resulting token is bound to a **single organization** and
carries only the `mcp:read` scope.
## Connect in Claude (claude.ai and desktop app)
This is the no-terminal path. Claude reaches the Bevits server from Anthropic's
cloud, so all you need is the public endpoint address.
In Claude, on the web or in the desktop app, go to
**Customize → Connectors**.
Click **+**, then **Add custom connector**, and enter the URL of the Bevits
remote MCP server:
```text theme={null}
https://api.bevits.com/mcp
```
Leave **Advanced settings** empty: the Bevits server publishes its own OAuth
metadata, so no Client ID or Client Secret is needed. Click **Add**.
Click **Connect**, sign in to Bevits in the browser, choose the organization,
and approve read-only access.
In the chat, open the **+** button, pick **Connectors**, and enable
**Bevits**. Then just ask away — for example, "which email campaigns had the
highest open rate?"
On **Team** and **Enterprise** accounts, an owner adds the connector under
**Organization settings → Connectors**, and each person then clicks **Connect**
to authenticate with their own Bevits account — everyone sees only the data of
the organization they authorized. Menu names may change as Claude is updated;
the
[custom connectors documentation](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)
always has the latest steps.
## Connect in the terminal (Claude Code and Codex)
Run the command in your terminal. The exact commands are also available in
[Settings → MCP](https://app.bevits.com/settings/mcp).
```bash Claude Code theme={null}
claude mcp add --transport http --scope user \
--client-id https://app.bevits.com/.well-known/oauth-client/claude-code \
--callback-port 3118 \
bevits https://api.bevits.com/mcp
```
```bash Codex theme={null}
codex mcp add bevits --url https://api.bevits.com/mcp
```
Start OAuth, sign in to Bevits in the browser, choose the organization, and
approve read-only access.
```text Claude Code theme={null}
/mcp
```
```bash Codex theme={null}
codex mcp login bevits
```
Check that the server is connected and that all 20 tools were loaded.
```bash Claude Code theme={null}
claude mcp list
```
```bash Codex theme={null}
codex mcp list
```
Any client that supports MCP over Streamable HTTP with OAuth 2.1 can connect to
the same endpoint. Claude Code and Codex are simply the documented paths.
## What you can do
Find customers by email, phone, tag, segment, or free-text search, and read
contact details, tags, attributes, default address, and spending metrics.
List and inspect orders, and aggregate revenue, average ticket, and unique
customers in one call — ranked by UTM, platform, status, or day.
Look up segments by name, see how large each one is, and list their customers
sorted by last update or total spent.
Measure an abandoned-cart flow: recovery rate, recovered revenue, and
conversions per message in the sequence.
Email campaigns with sent, delivered, opened, and clicked; WhatsApp and SMS
campaigns with recipients, delivered, read, and failed per template.
Questions the agent can answer on its own once connected:
* “Which UTMs drove the most sales in the last 7 days?”
* “What is the recovery rate and recovered revenue of my abandoned-cart flow?”
* “Which message in the recovery sequence converts best?”
* “What was this month's average ticket compared to last month?”
* “Who are the top 20 spenders in the VIP segment and what did they buy?”
* “Which WhatsApp template had the worst delivery rate?”
* “Is this customer subscribed? Which tags and attributes do they have?”
* “Which flows are active and how many times has each one run?”
## Tool catalog
Every tool is read-only (`readOnlyHint`) and idempotent. None of them create,
change, or delete data, and none accept an organization ID — the scope always
comes from the token.
### Identity
| Tool | What it does |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `bevits_get_identity` | Returns the organization and credential behind the connection. A good first call to confirm which account the agent is in. |
### Customers
| Tool | What it does |
| -------------------------------- | ---------------------------------------------------------------------------------------------- |
| `bevits_list_customers` | Lists customers with CRM filters and cursor pagination. |
| `bevits_get_customer` | Returns one customer by `customer_id` (`cus_...`), with tags, attributes, and default address. |
| `bevits_list_customer_purchases` | Lists the purchases of a specific customer. |
### Purchases
| Tool | What it does |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `bevits_list_purchases` | Lists purchases with commerce filters and cursor pagination. |
| `bevits_get_purchase` | Returns one purchase by `purchase_id` (`pur_...`). |
| `bevits_get_purchase_stats` | Aggregates purchases: orders, revenue, average ticket, and unique customers, with optional ranking by UTM, platform, status, currency, or day. |
### Segments
| Tool | What it does |
| ------------------------------- | -------------------------------------------------------- |
| `bevits_list_segments` | Lists segments, with optional name search (`q`). |
| `bevits_get_segment` | Returns one segment by `segment_id` (`seg_...`). |
| `bevits_list_segment_customers` | Lists the customers of a segment, with optional sorting. |
### Tags and attributes
| Tool | What it does |
| ------------------------ | ------------------------------------------------- |
| `bevits_list_tags` | Lists the organization's customer tags. |
| `bevits_get_tag` | Returns one tag by `tag_id` (`tag_...`). |
| `bevits_list_attributes` | Lists custom customer attributes and their types. |
### Flows and campaigns
| Tool | What it does |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `bevits_list_flows` | Lists the organization's automations. |
| `bevits_get_flow` | Returns one flow by `flow_id` (`flw_...`). |
| `bevits_get_flow_metrics` | Flow performance for a period: entries, sends, conversions, conversion rate, recovered revenue, and the same breakdown per message node. |
| `bevits_list_email_campaigns` | Lists email campaigns. |
| `bevits_get_email_campaign` | Returns one campaign by `email_campaign_id` (`emc_...`). |
| `bevits_list_template_campaigns` | Lists WhatsApp and SMS campaigns built from a template. |
| `bevits_get_template_campaign` | Returns one WhatsApp or SMS campaign by `template_campaign_id` (`tcp_...`), with every template variation it used and its delivery metrics. |
## Available filters
### `bevits_list_customers`
| Parameter | Type | Description |
| --------------------------------- | -------------------------- | ----------------------------------------------- |
| `q` | text | Free-text search across name, email, and phone. |
| `email` | email | Exact email lookup. |
| `phone` | text | Phone lookup. |
| `tag_id` | `tag_...` | Only customers with the tag. |
| `segment_id` | `seg_...` | Only customers in the segment. |
| `is_subscribed` | boolean | Filter by subscription status. |
| `created_since` / `created_until` | ISO 8601 date | Customer creation window. |
| `updated_since` | ISO 8601 date | Updated on or after the date. |
| `sort` | `updated` \| `total_spent` | Result ordering. |
### `bevits_list_purchases`
| Parameter | Type | Description |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------- |
| `customer_id` | `cus_...` | Purchases of one customer. |
| `status` | `any`, `pending`, `authorized`, `paid`, `abandoned`, `refunded`, `voided` | Order status. |
| `platform` | `nuvemshop`, `shopify`, `woocommerce`, `bling`, `instagram`, `popup` | Order origin. |
| `created_since` / `created_until` | ISO 8601 date | Order window. |
| `min_value_in_cents` / `max_value_in_cents` | integer | Value range, in cents. |
| `utm_source` / `utm_medium` / `utm_campaign` / `utm_content` / `utm_term` | text | Filters by the order's marketing attribution. |
### `bevits_get_purchase_stats`
Takes exactly the same filters as `bevits_list_purchases` (UTM included), plus
two parameters:
| Parameter | Type | Description |
| ------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `group_by` | `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `platform`, `status`, `currency`, `day` | Groups the result and returns that dimension's ranking. |
| `group_limit` | integer | Maximum groups returned. Defaults to `10`, maximum `50`. |
The response carries the totals for the period (`purchase_count`,
`customer_count`, `revenue_in_cents`, `average_ticket_in_cents`) and, when
`group_by` is set, a `groups` list ordered by revenue — orders without that UTM
show up as `key: null`. `groups_truncated` tells you when more groups exist
beyond `group_limit`.
If the store has orders in more than one currency, `currency` comes back
`null` and `mixed_currencies` is `true`: the totals are then a raw sum of
different currencies. Split by currency (`group_by: "currency"`) before
comparing.
`bevits_list_segments` accepts `q`, and `bevits_list_segment_customers` accepts
`sort` (`updated` or `total_spent`).
Dates must be ISO 8601 with an offset (for example `2026-01-01T00:00:00-03:00`),
and monetary values are always integers in cents.
## Sales recovery metrics
`bevits_get_flow_metrics` answers the cart-recovery questions from the
attribution Bevits already writes on every send:
| Field | What it means |
| ------------------------------- | ------------------------------------------------------------------------------------------------ |
| `entries` | Distinct abandoned checkouts messaged in the period. |
| `sent` / `delivered` / `failed` | Message volume for the flow in the period. |
| `conversions` | Paid orders attributed to the flow (counted once, even across several touches). |
| `conversion_rate` | `conversions ÷ entries` — the recovery rate. |
| `revenue_in_cents` | Revenue recovered in the period. |
| `average_ticket_in_cents` | Average ticket of the recovered orders. |
| `nodes[]` | The same cut per message node, so you can compare the 1st, 2nd, and 3rd message of the sequence. |
The window defaults to 30 days and is capped at 366; use `since` and `until` for
another period. The numbers match the **Performance** mode inside the flow
builder.
Attribution is **last-touch, 7-day window, abandoned-checkout scope**: only
flows with an abandonment trigger (`eligibility: "recovery"`) record
conversions. Paid **Nuvemshop** and **Shopify** orders feed that attribution.
Every other flow returns `eligibility: "engagement_only"` and should be read for
deliverability only.
## Pagination
Every list tool uses cursor pagination:
* `limit` — items per page. Defaults to `25`, maximum `50`.
* `starting_after` — ID of the last item on the previous page.
* The response carries `data`, `has_more`, and `next_cursor` when more pages
exist.
The agent keeps reading by passing `next_cursor` as `starting_after`. Because the
page size is capped, "give me everything" questions make the agent paginate many
times; use filters to get faster answers.
## Security and limits
The catalog exposes no write operation. The agent cannot create, edit, or
delete customers, orders, flows, or campaigns.
The token carries the organization chosen at sign-in. No tool accepts an
organization ID, so another account can never be queried.
Authentication is OAuth 2.1 with a local callback. No Bevits API key is
written to the agent's configuration files.
Calls are limited per client, token, and operation (120 per minute by
default). Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`,
`X-RateLimit-Reset`, and `Retry-After`.
Only owners and administrators can open the MCP settings page and authorize the
connection. Review who has access to the machine the agent runs on: anyone
using the connected agent sees the same read-only data you do.
### Errors
When a tool fails, the agent receives a structured error with a `code` and, when
available, `request_id` and `retry_after`.
| Code | Meaning |
| ---------------------- | ----------------------------------------------------------------------------- |
| `authentication_error` | Invalid or expired token, or missing read scope. Sign in through OAuth again. |
| `permission_denied` | The credential lacks permission for the resource. |
| `not_found` | The provided ID does not exist in this organization. |
| `validation_error` | A parameter was rejected (wrong ID prefix, invalid date, inverted range). |
| `rate_limited` | Rate limit reached. Wait for `retry_after`. |
| `upstream_unavailable` | The Bevits API timed out or is unavailable. |
| `request_cancelled` | The call was cancelled by the client. |
When contacting support, include the `request_id` from the error — it points to
the exact call.
## Troubleshooting
**The agent does not list the tools.** Confirm the server shows as connected
(`claude mcp list` or `codex mcp list`) and run the OAuth authorization again.
**I connected the wrong organization.** Remove the server from the client, add
it again, and pick the correct organization on the sign-in screen.
**I need writes or another integration.** MCP is read-only in this version. For
other flows, use the [REST API](/en/api-reference/overview) or contact support.