npm package: @getcheddar/cheddar-mcp
Description: Model Context Protocol server for Cheddar Payment Platform integration
Author: Cheddar
Latest version: 1.0.5

# Cheddar MCP Server

A Model Context Protocol (MCP) server for integrating with the Cheddar Payment Platform. This server provides AI assistants with tools to generate payment integration code and manage Cheddar resources.

**Package:** `@getcheddar/cheddar-mcp`  
**Version:** 1.0.5

---

## Two Modes of Operation

The MCP server works in two modes depending on whether you provide API credentials:

### Mode A: Code Generation Only (No Auth Required)

**Use this mode to:**

- Generate integration code (React, Vue, Next.js, etc.)
- Create checkout forms and hosted page URLs
- Configure webhooks and validation logic
- Get code recommendations and best practices

**No API credentials needed!** These tools work out of the box:

| Tool                                         | Description                                      |
| -------------------------------------------- | ------------------------------------------------ |
| `cheddar_checkout_generate_hosted_url`       | Generate hosted checkout page URLs               |
| `cheddar_checkout_generate_embedded_form`    | Generate embedded checkout form code             |
| `cheddar_checkout_generate_integration_code` | Generate complete framework-specific integration |
| `cheddar_checkout_configure_webhook`         | Generate webhook handler code                    |
| `cheddar_checkout_validate_webhook`          | Validate webhook signatures                      |

**Quick Start (No Auth):**

```json
{
  "mcpServers": {
    "cheddar": {
      "command": "npx",
      "args": ["-y", "@getcheddar/cheddar-mcp@1.0.5"]
    }
  }
}
```

**Example Prompt for Lovable:**

```
Create a React checkout page for my SaaS using Cheddar payments.
- Collect customer email and name
- Accept credit card payments securely
- Subscribe customers to a "Pro Plan"
- Handle errors gracefully

Use cheddar_checkout_generate_integration_code with framework "react".
```

---

### Mode B: Full API Access (Auth Required)

**Use this mode to:**

- Query actual customer data from your Cheddar account
- Create and update customers, subscriptions, payment methods
- Manage billing and plan changes
- Access real-time subscription status

**Requires Cheddar API credentials.** These tools need authentication:

| Tool                           | Description                        |
| ------------------------------ | ---------------------------------- |
| `cheddar_customer_get`         | Retrieve customer by ID or code    |
| `cheddar_customer_create`      | Create a new customer              |
| `cheddar_customer_update`      | Update customer information        |
| `cheddar_payment_method_get`   | Retrieve payment method by ID      |
| `cheddar_payment_token_create` | Tokenize card data (PCI-compliant) |
| `cheddar_subscription_get`     | Retrieve subscription details      |
| `cheddar_plan_get`             | Retrieve plan information          |

**Setup with Auth:**

1. **Sign up for Cheddar:** https://getcheddar.com/signup
2. **Get your credentials:**
   - **Username:** Your Cheddar account email
   - **Secret Key:** Top navbar → Configuration → Product Settings → Secret Key

3. **Configure MCP:**

```json
{
  "mcpServers": {
    "cheddar": {
      "command": "npx",
      "args": ["-y", "@getcheddar/cheddar-mcp@1.0.5"],
      "env": {
        "CHEDDAR_API_URL": "https://api.getcheddar.com",
        "CHEDDAR_USERNAME": "your-email@example.com",
        "CHEDDAR_SECRET_KEY": "your-secret-key-here"
      }
    }
  }
}
```

**Alternative: OAuth2 Access Token**

If you have an OAuth2 access token instead:

```json
{
  "mcpServers": {
    "cheddar": {
      "command": "npx",
      "args": ["-y", "@getcheddar/cheddar-mcp@1.0.5"],
      "env": {
        "CHEDDAR_API_URL": "https://api.getcheddar.com",
        "CHEDDAR_ACCESS_TOKEN": "your-oauth2-access-token"
      }
    }
  }
}
```

**Example Prompt with Auth:**

```
Get customer details for customer code "cust_12345" and show me their subscription status and payment methods.

Use cheddar_customer_get, then cheddar_subscription_get and cheddar_payment_method_get.
```

---

## Configuration Reference

| Variable               | Mode      | Description                                              |
| ---------------------- | --------- | -------------------------------------------------------- |
| `CHEDDAR_API_URL`      | Auth only | REST API base URL. Default: `https://api.getcheddar.com` |
| `CHEDDAR_USERNAME`     | Auth only | Your Cheddar account email address                       |
| `CHEDDAR_SECRET_KEY`   | Auth only | Secret Key from Product Settings                         |
| `CHEDDAR_ACCESS_TOKEN` | Auth only | OAuth2 Bearer token (alternative to username/secret)     |

**Note:** If no auth credentials are provided, the server runs in **code generation mode only** and will return clear error messages if you try to use data access tools.

---

## Usage with Claude Desktop

Add to your Claude Desktop configuration:

**For code generation (no auth):**

```json
{
  "mcpServers": {
    "cheddar": {
      "command": "npx",
      "args": ["-y", "@getcheddar/cheddar-mcp@1.0.5"]
    }
  }
}
```

**For full API access (with auth):**

```json
{
  "mcpServers": {
    "cheddar": {
      "command": "npx",
      "args": ["-y", "@getcheddar/cheddar-mcp@1.0.5"],
      "env": {
        "CHEDDAR_API_URL": "https://api.getcheddar.com",
        "CHEDDAR_USERNAME": "your-email@example.com",
        "CHEDDAR_SECRET_KEY": "your-secret-key"
      }
    }
  }
}
```

---

## Usage with Cursor

1. Open Cursor Settings
2. Navigate to **Features → MCP**
3. Add a new MCP server:

**For code generation:**

- **Name:** `cheddar`
- **Command:** `npx`
- **Arguments:** `-y`, `@getcheddar/cheddar-mcp@1.0.5`

**For full API access:**

- **Name:** `cheddar`
- **Command:** `npx`
- **Arguments:** `-y`, `@getcheddar/cheddar-mcp@1.0.5`
- **Environment:** Set `CHEDDAR_USERNAME` and `CHEDDAR_SECRET_KEY`

---

## Usage with Lovable.dev

### Step 1: Get Credentials (for full API access, optional)

1. Sign up at https://getcheddar.com/signup
2. Configure your product
3. Get your Secret Key: Top navbar → Configuration → Product Settings → Secret Key

### Step 2: Configure MCP in Lovable

Add to your Lovable project configuration:

**Option 1: Code Generation Only (Recommended for starters)**

```json
{
  "mcpServers": {
    "cheddar": {
      "command": "npx",
      "args": ["-y", "@getcheddar/cheddar-mcp@1.0.5"]
    }
  }
}
```

**Option 2: Full API Access**

```json
{
  "mcpServers": {
    "cheddar": {
      "command": "npx",
      "args": ["-y", "@getcheddar/cheddar-mcp@1.0.5"],
      "env": {
        "CHEDDAR_API_URL": "https://api.getcheddar.com",
        "CHEDDAR_USERNAME": "your-email@example.com",
        "CHEDDAR_SECRET_KEY": "your-secret-key"
      }
    }
  }
}
```

### Step 3: Try These Prompts

**For code generation (no auth needed):**

```
Create a complete payment integration for my React app:
1. A pricing page with 3 tiers (Basic, Pro, Enterprise)
2. Checkout flow using Cheddar's embedded form
3. Webhook handler for subscription events
4. Use Tailwind CSS for styling

Start with cheddar_checkout_generate_integration_code.
```

**For data access (requires auth):**

```
Build a customer dashboard showing:
- Customer profile from Cheddar
- Current subscription plan
- Payment methods on file
- Recent invoices

Use cheddar_customer_get and related tools.
```

---

## Testing

### Sandbox Environment

Use the sandbox for testing before going live:

```json
{
  "env": {
    "CHEDDAR_API_URL": "https://sandbox.getcheddar.com",
    "CHEDDAR_USERNAME": "your-sandbox-email",
    "CHEDDAR_SECRET_KEY": "your-sandbox-secret"
  }
}
```

### Test Card Numbers

- `4111111111111111` - Visa (success)
- `4000000000000002` - Declined

---

## Complete Tool Reference

### Code Generation Tools (No Auth Required)

| Tool                                         | Description                                  |
| -------------------------------------------- | -------------------------------------------- |
| `cheddar_checkout_generate_hosted_url`       | Generate hosted checkout page URLs           |
| `cheddar_checkout_generate_embedded_form`    | Generate embedded checkout form code         |
| `cheddar_checkout_generate_integration_code` | Generate framework-specific integration code |
| `cheddar_checkout_configure_webhook`         | Generate webhook handler code                |
| `cheddar_checkout_validate_webhook`          | Validate webhook signatures                  |

### Data Access Tools (Auth Required)

| Tool                                         | Description                              |
| -------------------------------------------- | ---------------------------------------- |
| `cheddar_customer_get`                       | Retrieve a customer by ID or code        |
| `cheddar_customer_create`                    | Create a new customer                    |
| `cheddar_customer_update`                    | Update customer information              |
| `cheddar_payment_method_get`                 | Retrieve a payment method by ID          |
| `cheddar_payment_method_get_customer`        | Get customer from payment method         |
| `cheddar_payment_method_get_gateway_account` | Get gateway account for payment method   |
| `cheddar_payment_token_create`               | Tokenize card data (PCI-compliant)       |
| `cheddar_payment_method_add_to_customer`     | Add tokenized payment method to customer |
| `cheddar_subscription_get`                   | Retrieve subscription by ID              |
| `cheddar_subscription_get_customer`          | Get customer from subscription           |
| `cheddar_subscription_get_plan`              | Get plan from subscription               |
| `cheddar_subscription_get_payment_method`    | Get payment method from subscription     |
| `cheddar_subscription_delete_promotion`      | Remove promotion from subscription       |
| `cheddar_plan_get`                           | Retrieve plan by ID or code              |
| `cheddar_gateway_account_get`                | Get gateway account details              |

---

## Docker Usage

Build and run with Docker:

```bash
# Build
docker build -t cheddar-mcp ./packages/cheddar-mcp

# Run (code generation only)
docker run -i --rm cheddar-mcp

# Run with auth
docker run -i --rm \
  -e CHEDDAR_API_URL=https://api.getcheddar.com \
  -e CHEDDAR_USERNAME=your-email \
  -e CHEDDAR_SECRET_KEY=your-secret \
  cheddar-mcp
```

---

## Development

```bash
# Clone the repository
git clone https://github.com/chdr/cheddar-ai-tools.git
cd cheddar-ai-tools/packages/cheddar-mcp

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Test
npm test
```

---

## License

MIT © Cheddar (chdr)

## Support

- Documentation: https://docs.getcheddar.com
- Support: support@getcheddar.com
- Issues: https://github.com/chdr/cheddar-ai-tools/issues