MCP server

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.

Open Customize → Connectors

In Claude, on the web or in the desktop app, go to Customize → Connectors.

Add a custom connector

Click +, then Add custom connector, and enter the URL of the Bevits remote MCP server:

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.

Connect your organization

Click Connect, sign in to Bevits in the browser, choose the organization, and approve read-only access.

Turn the connector on in a chat

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 always has the latest steps.

Connect in the terminal (Claude Code and Codex)

Add Bevits to your client

Run the command in your terminal. The exact commands are also available in Settings → MCP.

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

codex mcp add bevits --url https://api.bevits.com/mcp

Authorize your organization

Start OAuth, sign in to Bevits in the browser, choose the organization, and approve read-only access.

/mcp

codex mcp login bevits

Confirm the connection

Check that the server is connected and that all 20 tools were loaded.

claude mcp list

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

CRM and customers

Find customers by email, phone, tag, segment, or free-text search, and read contact details, tags, attributes, default address, and spending metrics.

Purchases and revenue

List and inspect orders, and aggregate revenue, average ticket, and unique customers in one call — ranked by UTM, platform, status, or day.

Segments

Look up segments by name, see how large each one is, and list their customers sorted by last update or total spent.

Sales recovery

Measure an abandoned-cart flow: recovery rate, recovered revenue, and conversions per message in the sequence.

Campaigns

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

Read-only

The catalog exposes no write operation. The agent cannot create, edit, or delete customers, orders, flows, or campaigns.

Scoped to one organization

The token carries the organization chosen at sign-in. No tool accepts an organization ID, so another account can never be queried.

No key in the config

Authentication is OAuth 2.1 with a local callback. No Bevits API key is written to the agent’s configuration files.

Rate limit

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 or contact support.

Getting started

Fundamentals

Reference

Connect in Claude (claude.ai and desktop app)

Connect in the terminal (Claude Code and Codex)

What you can do

CRM and customers

Purchases and revenue

Segments

Sales recovery

Campaigns

Tool catalog

Identity

Customers

Purchases

Segments

Tags and attributes

Flows and campaigns

Available filters

`bevits_list_customers`

`bevits_list_purchases`

`bevits_get_purchase_stats`

Sales recovery metrics

Security and limits

Read-only

Scoped to one organization

No key in the config

Rate limit

Errors

Troubleshooting

​Connect in Claude (claude.ai and desktop app)

​Connect in the terminal (Claude Code and Codex)

​What you can do

CRM and customers

Purchases and revenue

Segments

Sales recovery

Campaigns

​Tool catalog

​Identity

​Customers

​Purchases

​Segments

​Tags and attributes

​Flows and campaigns

​Available filters

​bevits_list_customers

​bevits_list_purchases

​bevits_get_purchase_stats

​Sales recovery metrics

​Pagination

​Security and limits

Read-only

Scoped to one organization

No key in the config

Rate limit

​Errors

​Troubleshooting

Connect in Claude (claude.ai and desktop app)

Connect in the terminal (Claude Code and Codex)

What you can do

Tool catalog

Identity

Customers

Purchases

Segments

Tags and attributes

Flows and campaigns

Available filters

`bevits_list_customers`

`bevits_list_purchases`

`bevits_get_purchase_stats`

Sales recovery metrics

Pagination

Security and limits

Errors

Troubleshooting