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.

MCP is optional. Any action-capable agent that can send HTTPS requests can start with GrowSurf's client-neutral REST workflow at https://growsurf.com/agent-start.md.

- Learn more about GrowSurf at https://growsurf.com
- Start with direct REST at https://growsurf.com/agent-start.md
- Read the OpenAPI contract at https://growsurf.com/openapi.json
- Read the Arazzo workflow at https://growsurf.com/arazzo.yaml
- Learn about optional MCP setup at https://docs.growsurf.com/build-with-ai#optional-connect-mcp

## 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 and Claude.ai use the hosted remote connector at `https://mcp.growsurf.com`. Claude Desktop can use either the local stdio server or the hosted connector. See the full client list and setup at https://docs.growsurf.com/build-with-ai#optional-connect-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, advising on program design, troubleshooting referral tracking, embedding the widget, listing and fetching programs and participants, configuring rewards, wiring webhooks, and reading analytics
  - Prompts use details from your conversation and ask only for missing information needed for the next step. No form inputs are needed. Existing prompt names and direct arguments remain supported.
  - 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, time series, email metrics, participant engagement activity, and activation cohorts)
  - Create, update, and clone programs (campaigns)
  - List, create, update, and delete campaign rewards
  - List, create, update, and delete Program Resources, including a safe one-time FILE preparation flow
  - Get/update Design, Emails, Options, and Installation config
  - Capture temporary GrowSurf preview screenshots so the user can see a draft program
  - 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

## Choosing a tool

Use program and participant tools to read or change records. Guidance tools return advice or code for you to apply:

| Task | Tool |
| --- | --- |
| Choose a program design and reward structure | `growsurf_program_design_advisor` |
| Plan a web integration | `growsurf_integration_guide` |
| Get browser JavaScript examples | `growsurf_client_snippets` |
| Get one embeddable element's HTML | `growsurf_embeddable_element_snippet` |
| Generate page-level participant auto authentication code | `growsurf_grsf_config_snippet` |
| Get backend REST API library examples | `growsurf_api_library_snippets` |
| Integrate a native iOS or Android app | `growsurf_mobile_sdk_guide` |
| Diagnose a program problem | `growsurf_troubleshoot_referral_tracking` |
| Generate checks for an agent's program-creation workflow | `growsurf_agent_program_creation_eval` |

Published tool names and fields use `campaign` for a program, including `campaignId`. These identifiers remain supported. Display titles use program terminology; Campaign Reward remains the name for a reward configuration.

To delete one participant, pass one ID or email in `participants` to `growsurf_bulk_delete_participants`. The same permanent-deletion warnings apply. A separate single-participant tool is not needed. Program deletion and explicit reward fulfillment are outside this MCP tool set; completing a program is not deletion, and configuring a reward is not proof that it was delivered.

## Optional compact connection

The default connection lists all 63 tools. Add `--compact` to select 32 tools for program setup, installation, participant management, referral tracking, rewards, and analytics. Your credential permissions can reduce the visible set further.

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

In a stdio client configuration, append `"--compact"` to the package's `args` array. Server integrations can call `createGrowSurfMcpServer({ toolSurface: "compact" })`. Omit the option to keep the full catalog.

Compact combines related guidance and settings tools:

| Tool | Selection | Arguments |
| --- | --- | --- |
| `growsurf_get_guidance` | `topic`: `integration`, `browser`, `api_libraries`, `mobile_sdk`, `embeddable_element`, `participant_auto_auth`, or `program_creation_checks` | Put the selected guide's existing arguments under `input`. Use `{}` for defaults. |
| `growsurf_get_program_settings` | `section`: `design`, `emails`, `options`, or `installation` | Put `campaignId` under `input`, or use the configured default. |
| `growsurf_update_program_settings` | The same `section` values | Put `campaignId` and the `fields` patch under `input`. Read the section first. |

For example, read a program's installation settings:

```json
{
  "name": "growsurf_get_program_settings",
  "arguments": { "section": "installation", "input": { "campaignId": "YOUR_PROGRAM_ID" } }
}
```

Program recommendations and troubleshooting keep their own tools. Participant reads, updates, deletion, referral actions, and sale or refund actions remain separate. Compact prompts, resources, guidance, and proposed configuration calls use the compact tool names and arguments.

Use the full connection for account creation, team administration, program cloning, participant resources, webhook creation/updates/deletion/tests, participant emails, payout destinations, and webhook normalization. Remove `--compact` and reconnect. These operations remain available with their existing contracts on the full connection; compact rejects calls to tools outside its catalog. The tool-selection table above describes the full connection.

## 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. Call it only after the authorized owner approves account creation and accepts GrowSurf's Terms of Service and Privacy Policy. The account starts a 14-day Business trial without a credit card and returns its API key once. A lost key cannot be recovered through the API, so use this only if you can store a secret past the current conversation; otherwise have the owner connect `https://mcp.growsurf.com` and sign in. Pause for owner email verification before protected calls. Unverified accounts are deleted after 7 days. 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 wi