# Cuprice MCP Server — Full Reference

> Public API tools for integrating Cuprice pricing widgets via Model Context Protocol.

Endpoint: POST https://mcp.cuprice.io/mcp
Docs: https://docs.cuprice.io/mcp
Website: https://cuprice.io

---

## What is Cuprice?

Cuprice lets you build feature-based pricing pages and embed them on any website. Users can pick a plan, customize features, and pay via Stripe — all without leaving your site.

## What is this MCP server?

This server exposes Cuprice's public APIs as MCP tools. AI assistants can fetch pricing data, generate embed code, look up purchase receipts, and get CSS class names for customization.

## Setup

### Remote (no install)

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "cuprice": {
      "url": "https://mcp.cuprice.io/mcp"
    }
  }
}
```

---

## Tools Reference

### get-pricing

Get public pricing data for a project — plans, features, prices, and theme settings.

**Input:**
- `shareId` (string, required) — The project's Share ID (e.g. "nTZ7axXQHU")

**Output:** Project object with name, description, currency, annualDiscount, plans (with features and limits), and themeSettings.

**Public endpoint used:** `GET /api/share/{shareId}`

---

### get-embed-code

Get a ready-to-use code snippet to embed a Cuprice pricing table.

**Input:**
- `shareId` (string, required) — The project's Share ID
- `framework` (string, optional) — "html", "nextjs", or "react". Default: "html"

**Output:** Code snippet for the specified framework.

**HTML output example:**
```html
<div data-cuprice-id="YOUR_SHARE_ID"></div>
<script src="https://app.cuprice.io/embed.js" async></script>
```

---

### get-receipt

Get purchase details from a Stripe checkout session.

**Input:**
- `sessionId` (string, required) — Stripe Checkout session ID (from the redirect URL after payment)
- `shareId` (string, required) — The project's Share ID

**Output:** Receipt with planName, customPlan (boolean), total, currency, customer email, billingInterval, subscriptionId, and metadata containing purchased feature details.

**Public endpoint used:** `GET /api/stripe/receipt?session_id=...&shareId=...`

**Feature extraction from metadata:**
- Regular plans: `metadata.planId` — look up features via get-pricing tool
- Custom plans: `metadata.featureDetails_0`, `featureDetails_1`, etc. — join and parse as JSON

---

### get-css-classes

Get all CSS class names available for customizing the Cuprice pricing widget.

**Input:** none

**Output:** Array of objects with `selector` and `description`:

| Selector | Description |
|----------|-------------|
| `.cuprice-pricing-card` | Each plan card |
| `.cuprice-pricing-button` | "Choose Plan" buttons |
| `.cuprice-pricing-badge` | "Most Popular" badge |
| `.cuprice-billing-toggle` | Monthly/Annual toggle |
| `.cuprice-pricing-header` | Page title and description |
| `.cuprice-custom-plan-card` | Custom plan card |
| `.cuprice-custom-plan-button` | "Create Now" button |
| `.cuprice-custom-plan-badge` | "Custom" badge |
| `.cuprice-custom-plan-title` | Custom card title |
| `.cuprice-custom-plan-feature-text` | Feature bullet text |

Use `!important` on all CSS properties to override scoped widget styles.

---

## Embed Widget

Add to any HTML page:

```html
<div data-cuprice-id="YOUR_SHARE_ID"></div>
<script src="https://app.cuprice.io/embed.js" async></script>
```

The widget auto-resizes, loads asynchronously, and is CSS-isolated.

## Feature Gating

After Stripe checkout, the success URL receives a `session_id`. Use the get-receipt tool to find which features were purchased:

- **Regular plans:** Receipt metadata contains `planId`. Use get-pricing to look up plan features.
- **Custom plans:** Receipt metadata contains `featureDetails_0`, `featureDetails_1`, etc. Join and parse as JSON to get feature names and prices.

---

## API v1 — Authenticated REST API

All v1 endpoints require an API key passed as `Authorization: Bearer cpk_...`.

API keys are created in Dashboard → Settings → API Keys. Keys with `read` permission can list/read. Keys with `read_write` can also create, update, delete.

Base URL: `https://cuprice.io/api/v1`

---

### Projects

#### List Projects
`GET /api/v1/projects`
Returns: `{ projects: [{ id, name, slug, description, shareId, currency, isActive, createdAt, updatedAt, _count: { features, pricingPlans } }] }`

#### Create Project
`POST /api/v1/projects` (read_write)
Body: `{ name (required, max 100), description, pricingPageDescription, currency (default "USD") }`
Returns: created project object (status 201)

#### Get Project
`GET /api/v1/projects/{slug}`
Returns: project with themeSettings, features (with countableData), pricingPlans (with planFeatures)

#### Update Project
`PUT /api/v1/projects/{slug}` (read_write)
Body: `{ name, description, pricingPageDescription, currency, annualDiscount, annualDiscountEnabled, isActive, checkoutSuccessUrl, checkoutCancelUrl, checkoutTestSuccessUrl, checkoutTestCancelUrl, theme }`
The `theme` object accepts all design settings:
- Colors: primaryColor, hoverColor, buttonTextColor, pricingBackgroundColor, pricingBorderColor, pricingHeaderTextColor, pricingPriceColor, pricingTextColor, pricingDescriptionColor, pricingHeaderBackgroundColor
- Badge: popularBadgeColor, popularBadgeTextColor, popularBadgeBorderColor, popularBadgePosition
- Custom plan card: customPlanButtonColor, customPlanButtonTextColor, customPlanCardBackgroundColor, customPlanCardBorderColor, customPlanCardTitleColor, customPlanCardFeatureColor, customPlanCardCheckmarkColor, customPlanCardBadgeBgColor, customPlanCardBadgeTextColor, customPlanCardBadgeBorderColor
- Layout: fontFamily, borderRadius, headerAlign, descriptionAlign, toggleAlign, showProjectName, showPricingHeader
- Custom CSS: customCSS (string with CSS rules)
All fields optional — only provided fields are updated.

#### Delete Project
`DELETE /api/v1/projects/{slug}` (read_write)
Cascades: deletes all plans, features, theme.
Returns: `{ success: true }`

---

### Features

#### List Features
`GET /api/v1/projects/{slug}/features`
Returns: `{ features: [{ id, name, description, basePrice, featureType, isCountable, order, countableData }] }`

#### Create Feature
`POST /api/v1/projects/{slug}/features` (read_write)
Body: `{ name (required), description, basePrice (required >= 0), isCountable, featureType ("Standart"|"Limits"|"Usage Based"), usageCount, condition, countPrice, eventAggregationMethod }`
Max 50 features per project. Returns: created feature (status 201)

#### Update Feature
`PUT /api/v1/projects/{slug}/features/{featureId}` (read_write)
Body: `{ name, description, basePrice, isCountable, featureType, usageCount, condition, countPrice }`
All fields optional.

#### Delete Feature
`DELETE /api/v1/projects/{slug}/features/{featureId}` (read_write)
Also removes the feature from all plans. Returns: `{ success: true }`

---

### Plans

#### List Plans
`GET /api/v1/projects/{slug}/plans`
Returns: `{ plans: [{ id, name, description, isPopular, isVisible, basePrice, isFree, planFeatures: [{ featureId, multiplier, feature }] }] }`

#### Create Plan
`POST /api/v1/projects/{slug}/plans` (read_write)
Body: `{ name (required), description, isPopular, isVisible, basePrice, isFree, features: [{ featureId, multiplier }] }`
Returns: created plan with features (status 201)

#### Update Plan
`PUT /api/v1/projects/{slug}/plans/{planId}` (read_write)
Body: `{ name, description, isPopular, isVisible, basePrice, isFree, freemiumDay, isPerUserPricing, perUserMultiplier }`

#### Delete Plan
`DELETE /api/v1/projects/{slug}/plans/{planId}` (read_write)
Returns: `{ success: true }`

#### Duplicate Plan
`POST /api/v1/projects/{slug}/plans/{planId}/duplicate` (read_write)
Body: `{ name }` (optional, defaults to "Original (Copy)")
Copies all plan features. Returns: duplicated plan (status 201)

---

### Plan Features (assign features to plans)

#### List Plan Features
`GET /api/v1/projects/{slug}/plans/{planId}/features`
Returns: `{ features: [{ id, planId, featureId, multiplier, order, feature }] }`

#### Add Features to Plan
`POST /api/v1/projects/{slug}/plans/{planId}/features` (read_write)
Body (single): `{ featureId, multiplier }`
Body (batch): `{ features: [{ featureId, multiplier }] }`
Skips already assigned features. Returns: `{ added, skipped, features }`

#### Remove Feature from Plan
`DELETE /api/v1/projects/{slug}/plans/{planId}/features?featureId={id}` (read_write)
Returns: `{ success: true }`