Skip to main content

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.

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

​
MCP Server Configuration

Cursor supports MCP servers natively. Add the Podium server to your project’s .cursor/mcp.json: 
{
  "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:
ToolWhat It Does
search_productsSearch the product catalog with filters
get_productFetch full product details by ID
get_profileRead a user’s companion/taste profile
update_profileUpdate preferences, brands, concerns
get_recommendationsGet personalized product recommendations
check_pointsCheck a user’s points balance
create_checkoutCreate a checkout session with shipping
list_tasksBrowse available task bounties

​
Project Rules

Create .cursor/rules/podium.mdc to give Cursor persistent context about Podium’s SDK and API patterns: 
---
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