GrowSurf

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.

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#connect-the-mcp-server

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#connect-the-mcp-server.

What you get

• Guided Integration:
• Universal Code install
• Native iOS/Android and React Native 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:
• 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 the program's integrations and get a dashboard link to connect one
• List, get, add, and bulk delete participants
• Update a participant, email a participant, and get a participant's analytics and activity logs
• Get a participant's payout-destination status and ask them to confirm a payout destination
• Trigger referral credit (for referral programs), with optional delayed award (1-90 days)
• Cancel a pending delayed referral trigger (for referral programs)
• Record affiliate sales/transactions and their refunds or chargebacks (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:

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

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:

For example, read a program's installation settings:

{

"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 team administration, program cloning, groups and bulk participant moves, participant resources, custom domains, 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. Sign up at https://app.growsurf.com.
• A GrowSurf API key for local stdio setup or manual API-key remote setup. Create one in the GrowSurf dashboard after you sign up. 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
• 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

For an MCP-compatible host, use GrowSurf's hosted OAuth endpoint at https://mcp.growsurf.com when the host supports remote Streamable HTTP with OAuth. Use the local npx server when the host needs a stdio process or manual API-key setup. No GrowSurf account yet? Sign up at https://app.growsurf.com and create an API key in the dashboard, or connect to https://mcp.growsurf.com and sign in with OAuth.

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#connect-the-mcp-server.

• 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