> ## 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.

# Windsurf

> Configure Windsurf with MCP tools and workspace rules for building on Podium

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

* [Windsurf](https://codeium.com/windsurf) 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

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:

```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, Windsurf's Cascade agent can call Podium tools directly during conversations.

### Available Tools

| 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           |

## Workspace Rules

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

```markdown theme={null}
# 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](/docs/recipes/mcp-server) is consistent

## Related

* [Cursor Setup](/docs/ai-tools/cursor) — same MCP server, different IDE
* [Claude Desktop](/docs/ai-tools/claude-desktop) — canonical MCP setup
* [SDK Setup](/docs/sdk/setup) — complete SDK reference