> ## Documentation Index
> Fetch the complete documentation index at: https://podium.build/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cursor

> Configure Cursor with MCP tools and project rules for building on Podium

Set up Cursor to build on Podium with full MCP tool access and project-level context rules. This gives Cursor's agent the ability to search products, manage profiles, execute checkouts, and more — all from within your IDE.

## Prerequisites

* [Cursor](https://cursor.com) installed
* A [Podium API key](https://app.podium.build/onboarding)
* The Podium MCP server built (see [Build a Claude MCP Server](/docs/recipes/mcp-server))

## MCP Server Configuration

Cursor supports MCP servers natively. Add the Podium server to your project's `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "podium": {
      "command": "node",
      "args": ["path/to/podium-mcp-server/dist/index.js"],
      "env": {
        "PODIUM_API_KEY": "podium_live_sk_..."
      }
    }
  }
}
```

After saving, restart Cursor or open the MCP panel (Cmd+Shift+P → "Cursor Settings: Tools & MCP") and verify the "podium" server shows as connected.

### Available Tools

Once connected, Cursor's agent can call these tools in conversation:

| Tool                  | What It Does                             |
| --------------------- | ---------------------------------------- |
| `search_products`     | Search the product catalog with filters  |
| `get_product`         | Fetch full product details by ID         |
| `get_profile`         | Read a user's companion/taste profile    |
| `update_profile`      | Update preferences, brands, concerns     |
| `get_recommendations` | Get personalized product recommendations |
| `check_points`        | Check a user's points balance            |
| `create_checkout`     | Create a checkout session with shipping  |
| `list_tasks`          | Browse available task bounties           |

## Project Rules

Create `.cursor/rules/podium.mdc` to give Cursor persistent context about Podium's SDK and API patterns:

```markdown theme={null}
---
description: Rules for building with the Podium commerce and agentic intelligence platform
globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]
---

# Podium Development Context

## SDK

- Package: `@podium-sdk/node-sdk`
- Client: `import { createPodiumClient } from '@podium-sdk/node-sdk'`
- Auth: Pass `apiKey` to `createPodiumClient({ apiKey: process.env.PODIUM_API_KEY })`
- Base URL (staging): `https://podium-staging.up.railway.app/api/v1`

## SDK Namespaces

| Namespace | Purpose |
|-----------|---------|
| `client.product.*` | Product CRUD, variants, media |
| `client.agentic.*` | Product feed, checkout sessions |
| `client.companion.*` | Profiles, recommendations, interactions |
| `client.user.*` | User management, points, rewards |
| `client.userOrder.*` | Order lifecycle, checkout, discounts |
| `client.tasks.*` | Task pools, bounties, verification |
| `client.x402.*` | USDC payment flows |
| `client.campaign.*` | Campaigns, voting, surveys |
| `client.admin.*` | API keys, org management |

## API Conventions

- All endpoints require `Authorization: Bearer <api_key>` header
- API keys are org-scoped: `podium_test_*` (staging) or `podium_live_*` (production)
- Responses follow `{ data, error, pagination }` envelope
- Pagination: `?page=1&limit=20`
- IDs are UUIDs

## Architecture

- Multi-tenant PostgreSQL with RLS
- Async event system for background job processing
- x402 protocol for machine-native USDC payments on Base
- Enrichment pipeline for product intelligence
- Companion profiles for personalized recommendations
```

## Example Workflow

With MCP connected and rules in place, you can ask Cursor:

> "Search for skincare products under \$25 and build a React component that displays them as cards with an add-to-cart button that creates a checkout session"

Cursor will:

1. Call `search_products` to get real product data
2. Use the SDK patterns from the rules to write correct code
3. Generate a component using `createPodiumClient` and the right SDK methods

## Tips

* **Use Agent mode** (Cmd+I → Agent) for multi-step tasks that involve both tool calls and code generation
* **Reference the MCP server recipe** if you need to add more tools — the pattern is consistent
* **Keep rules up to date** as the SDK evolves — add new namespaces or patterns as needed