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 Windsurf’s Cascade AI assistant with Podium MCP tools and workspace rules. This gives Windsurf full context about the Podium SDK and live API access for building commerce integrations.

​
Prerequisites

​
MCP Server Configuration

Windsurf supports MCP servers. Add the Podium server in Windsurf’s MCP settings:
  1. Open Settings (Cmd+,)
  2. Search for “MCP” or navigate to the MCP configuration panel
  3. Add a new server:
{
  "mcpServers": {
    "podium": {
      "command": "node",
      "args": ["path/to/podium-mcp-server/dist/index.js"],
      "env": {
        "PODIUM_API_KEY": "podium_live_sk_..."
      }
    }
  }
}
After saving, Windsurf’s Cascade agent can call Podium tools directly during conversations.

​
Available Tools

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

​
Workspace Rules

Create .windsurf/rules.md in your project root to give Cascade persistent context about Podium: 
# Podium Development Context

## SDK

- Package: `@podium-sdk/node-sdk`
- Client: `import { createPodiumClient } from '@podium-sdk/node-sdk'`
- Auth: `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), `podium_live_*` (production)
- Responses follow `{ data, error, pagination }` envelope
- Pagination: `?page=1&limit=20`
- IDs are UUIDs
- POST/PUT payloads go in `requestBody` parameter in SDK calls

## 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, prompt Cascade:
“Create an API route that takes a user ID and category, fetches personalized recommendations from Podium, and returns them as a JSON array with id, name, price, and imageUrl”
Cascade will:
  1. Use the SDK patterns from rules to write correct imports
  2. Call client.companion.listRecommendations() with the right parameters
  3. Shape the response to the requested format

​
Tips

  • Use Cascade Flows for multi-step tasks that combine code generation with tool calls
  • Reference the rules — Cascade reads .windsurf/rules.md automatically for every conversation
  • Extend the MCP server if you need more tools — the pattern from the MCP recipe is consistent