GrowSurf MCP Server

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:

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:

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:

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

For local stdio instead, use:

{
  "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:

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:

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:

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

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

For local stdio instead, use:

{
  "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:

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

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

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

For local stdio instead, add the following:

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

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:

npx @growsurfteam/growsurf-mcp

For local development in this repo:

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

Read the full README on GitHub →