growsurf-mcp

# GrowSurf MCP Server

[![npm version](https://img.shields.io/npm/v/@growsurfteam/growsurf-mcp)](https://www.npmjs.com/package/@growsurfteam/growsurf-mcp)
[![npm downloads](https://img.shields.io/npm/dm/@growsurfteam/growsurf-mcp)](https://www.npmjs.com/package/@growsurfteam/growsurf-mcp)
[![license](https://img.shields.io/npm/l/@growsurfteam/growsurf-mcp)](./LICENSE)
[![node](https://img.shields.io/node/v/@growsurfteam/growsurf-mcp)](https://nodejs.org)

The **official GrowSurf command-line interface (CLI) and open-source Model Context Protocol (MCP) server** for implementing **GrowSurf referral and affiliate programs** with guided steps and safe REST API wrappers.

Connect it to an AI agent and, in plain language, the agent can create a referral or affiliate program, configure rewards, install tracking, add and manage participants, and read analytics, all backed by the GrowSurf REST API.

- Learn more about GrowSurf at https://growsurf.com
- Learn more about this MCP server at https://docs.growsurf.com/build-with-ai

## Who is this for

This MCP server is for:

- Developers using MCP-compatible tools (Claude Code, Codex, Cursor, Copilot, and other MCP clients)
- Teams that want guided, AI-assisted GrowSurf integrations

This MCP server is NOT for:

- Browser-only users who want a local stdio install. ChatGPT web, Claude.ai, and Claude Desktop do not run a local MCP server, but all three connect to GrowSurf through the hosted remote connector at `https://mcp.growsurf.com`. See the full client list and setup at https://docs.growsurf.com/build-with-ai#mcp.

## What you get

- **Guided Integration**:
  - Universal Code install
  - Native iOS/Android SDK implementation guidance
  - Native GrowSurf Window guidance
  - Signup flow
  - Qualifying action flow
  - Affiliate sale / transaction tracking
  - Webhooks
- **Agent Recipes**:
  - MCP prompts for creating referral programs, creating affiliate programs, embedding the widget, listing and fetching programs and participants, configuring rewards, wiring webhooks, and reading analytics
  - Installable Agent Skill bundle at `skills/growsurf-agent-toolkit`
  - Steering to review starter Design, Emails, Options, Installation, rewards, and GrowSurf Window content before patching
  - One-shot program-creation eval prompts and acceptance checks for starter content and configuration review
- **Happy‑Path REST API Wrappers**:
  - Create an account and get an API key with no existing credentials
  - Read and rename the bound team, request team verification, and resend the team owner's verification email
  - List and get campaigns
  - Get campaign analytics (totals, optional per-period time series, email metrics, previous-period totals, status counts, and rates)
  - Create, update, and clone programs (campaigns)
  - List, create, update, and delete campaign rewards
  - Get/update Design, Emails, Options, and Installation config
  - Capture temporary GrowSurf preview screenshots when the user explicitly asks for visual proof
  - List, create, update, delete, and test program webhooks
  - List, get, and add participants
  - Update a participant, email a participant, and get a participant's analytics and activity logs
  - Trigger referral credit (for referral programs), with optional delayed award (1-90 days)
  - Cancel a pending delayed referral trigger (for referral programs)
  - Record affiliate sale/transaction (for affiliate programs)
  - Create mobile participant tokens for signed-in native app users
- **Official API Library Snippets**:
  - TypeScript
  - Python
  - PHP
  - Ruby
  - Java
- **Helpers**:
  - Compute participant auto-auth HMAC hash
  - Normalize webhook payloads
  - Generate best‑effort idempotency keys for webhook deduplication

## Requirements

- Node.js 22+
- A GrowSurf account for hosted OAuth
- A GrowSurf **API key** for local stdio setup or manual API-key remote setup. A scoped key works as long as it has access to the tools and programs you want the agent to use.
- A **campaign (program) ID** for campaign-scoped tools. Set `GROWSURF_CAMPAIGN_ID` as the default, pass a `campaignId` argument to target a specific program, or call `growsurf_list_campaigns` to find available programs. For a newly created program, pass the `id` returned by `growsurf_create_campaign` to the other tools.
- Static guidance/snippet tools can run without credentials
- Exception: `growsurf_create_account` needs **no** API key. It creates a new account and returns an API key. Team-level tools do not need a campaign ID.
- Every listed tool publishes standard MCP read-only, destructive, idempotent, and open-world safety hints. Scoped business actions stay available; API-key rotation is intentionally not an MCP tool. Rotate keys in GrowSurf Settings or through a direct REST/SDK client.

## Official CLI

The npm package installs the `growsurf-mcp` command. Run it without a global install:

```bash
npx -y @growsurfteam/growsurf-mcp
```

The CLI starts GrowSurf's local stdio MCP server. Set `GROWSURF_API_KEY` for API-backed actions and `GROWSURF_CAMPAIGN_ID` for a default program. Public developer resources and static integration guidance work without credentials.

Inspect the installed command without starting the stdio server:

```bash
npx -y @growsurfteam/growsurf-mcp --help
npx -y @growsurfteam/growsurf-mcp --version
```

## Supported MCP Hosts

The recommended path is GrowSurf's hosted OAuth endpoint at `https://mcp.growsurf.com` when your host supports remote Streamable HTTP with OAuth. Use the local `npx` server when your host needs a stdio process or manual API-key setup. No GrowSurf account yet? An agent can connect to the hosted onboarding endpoint `https://mcp.growsurf.com/onboard` with no credentials and call `growsurf_create_account` to sign up.

The GrowSurf MCP server works with any MCP-compatible host. The examples below cover a few config-based and CLI hosts. For the complete, current list of supported clients (including ChatGPT web, Claude.ai, Claude Desktop, GitHub Copilot, Gemini CLI, Devin Desktop, and Cline) with step-by-step setup, see https://docs.growsurf.com/build-with-ai#mcp.

- Cursor
- Claude Code (CLI-based)
- Antigravity
- Codex (CLI-based)

### Cursor

1. Open or create Cursor's global MCP configuration at `~/.cursor/mcp.json`.
2. Add a server named `growsurf` with the hosted OAuth endpoint:

```json
{
  "mcpServers": {
    "growsurf": {
      "type": "http",
      "url": "https://mcp.growsurf.com"
    }
  }
}
```

For local stdio instead, use:

```json
{
  "mcpServers": {
    "growsurf": {
      "command": "npx",
      "args": ["-y", "@growsurfteam/growsurf-mcp"],
      "env": {
        "GROWSURF_API_KEY": "YOUR_API_KEY",
        "GROWSURF_CAMPAIGN_ID": "YOUR_CAMPAIGN_ID"
      }
    }
  }
}
```

### Claude Code (CLI-based)

Open your terminal and connect Claude Code to the hosted OAuth endpoint:

```bash
claude mcp add --transport http --scope user growsurf https://mcp.growsurf.com
claude mcp login growsurf
```

For local stdio instead, install the server directly into Claude Code:

```bash
claude mcp add growsurf \
  -e GROWSURF_API_KEY=your_api_key \
  -e GROWSURF_CAMPAIGN_ID=your_campaign_id \
  -- npx -y @growsurfteam/growsurf-mcp
```


### Antigravity

1. Open Antigravity.
2. Click the **…** menu in the panel to the right and select **MCP Servers**.
3. Click **Manage MCP Servers > View raw config**.
4. Recommended: in the `mcp_config.json` file, add the hosted OAuth endpoint:

```json
{
  "mcpServers": {
    "growsurf": {
      "serverUrl": "https://mcp.growsurf.com"
    }
  }
}
```

5. Save the config, open **Settings > Customizations**, and select **Authenticate** for GrowSurf.

For local stdio instead, use:

```json
{
  "mcpServers": {
    "growsurf": {
      "command": "npx",
      "args": ["-y", "@growsurfteam/growsurf-mcp"],
      "env": {
        "GROWSURF_API_KEY": "YOUR_API_KEY",
        "GROWSURF_CAMPAIGN_ID": "YOUR_CAMPAIGN_ID"
      }
    }
  }
}
```

### Codex

Recommended: connect Codex to the hosted OAuth endpoint:

```bash
codex mcp add growsurf --url https://mcp.growsurf.com
codex mcp login growsurf
```

Or create or edit `~/.codex/config.toml`:

```toml
[mcp_servers.growsurf]
url = "https://mcp.growsurf.com"
```

For local stdio instead, add the following:

```toml
[mcp_servers.growsurf]
command = "npx"
args = ["-y", "@growsurfteam/growsurf-mcp"]

[mcp_servers.growsurf.env]
GROWSURF_API_KEY = "YOUR_API_KEY"
GROWSURF_CAMPAIGN_ID = "YOUR_CAMPAIGN_ID"
```

Or configure local stdio from the CLI:

```bash
codex mcp add growsurf \
  --env GROWSURF_API_KEY=YOUR_API_KEY \
  --env GROWSURF_CAMPAIGN_ID=YOUR_CAMPAIGN_ID \
  -- npx -y @growsurfteam/growsurf-mcp
```


## Configuration

Set the following environment variables when running the MCP server:

- `GROWSURF_API_KEY` (optional for startup; required for API-calling tools. Use a key with the scopes and program access those tools need)
- `GROWSURF_CAMPAIGN_ID` (optional; the default program for campaign-scoped tools. A tool's `campaignId` argument overrides it, so a single server can operate on any of your programs)
- `GROWSURF_API_BASE_URL` (optional; defaults to `https://api.growsurf.com/v2`. Useful for local or hosted MCP gateways that should call a different GrowSurf API origin)
- `GROWSURF_PARTICIPANT_AUTH_SECRET` (optional; used by the hash helper)
- `GROWSURF_WEBHOOK_TOKEN` (optional; used for your own webhook URL token scheme)


## Run with npx

After publishing this package, customers can run:

```bash
npx @growsurfteam/growsurf-mcp
```

For local development in this repo:

```bash
npm install
npm run build
node dist/cli.js
```

## MCP tools

Every tool declares an MCP output schema and returns `structuredContent`, so hosts know each tool's result shape. REST tools return the API response (plus a JSON text block for older clients); the guidance and snippet tools return their markdown document under `markdown`.

### Guided Integration

- `growsurf_integration_guide`
  Step-by-step