> For the complete documentation index, see [llms.txt](https://docs.growsurf.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.growsurf.com/build-with-ai.md).

# Build with AI

## MCP

[GrowSurf's MCP server](https://github.com/growsurf/growsurf-mcp) lets an AI agent work directly with your GrowSurf programs. It can create a referral or affiliate program, tune the design, inspect email/options defaults, configure rewards, wire webhooks, manage participants, and read analytics.

### What an agent can do

Create entire referral/affiliate programs with a one-shot prompt:

```
Create a GrowSurf referral program for Acme, keep rewards disabled until I approve them, then summarize the Design, Emails, Options, Installation, and Rewards settings.
```

{% hint style="info" %}
New to GrowSurf? OAuth connector clients (ChatGPT, Claude, and other sign-in flows) connect to an existing team, so sign up first if you do not have a GrowSurf account. An agent can also sign up for you: connect it to the onboarding endpoint `https://mcp.growsurf.com/onboard` with no credentials (or use the local server or API-key setup) and have it call `growsurf_create_account`. The returned API key is locked until the team owner's email address is verified. After the owner clicks the verification link, the agent continues with the same API key.
{% endhint %}

***

### Connect the MCP server

You need one of these:

* A GrowSurf account (sign up [here](https://app.growsurf.com/signup) or programmatically via [`/POST Create Account`](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-accounts)).
* A GrowSurf API key for local setup or remote clients that do not support GrowSurf sign-in.
* Optional: a default campaign `id`. You can skip this if your agent will create a new campaign first, then pass the returned `id` as `campaignId`.

{% tabs %}
{% tab title="ChatGPT" %}
Add GrowSurf as a developer-mode app (custom connector) in ChatGPT on the web.

1. Open *Settings > Connectors > Advanced* and turn on **Developer mode**. Enterprise workspaces need an admin to allow it.
2. In the *Connectors* tab, select **Create**, name the app **GrowSurf**, and set authentication to OAuth.
3. Use this MCP server URL:

   ```
   https://mcp.growsurf.com/mcp
   ```
4. Optional: add the [GrowSurf logo](https://app.growsurf.com/assets/img/logo/iconmark-blue-padded.png).
5. Finish the OAuth flow, then start a new chat, choose **Developer mode** from the + menu, and enable GrowSurf.

ChatGPT registers its own OAuth client automatically, so you do not paste an API key.
{% endtab %}

{% tab title="Claude.ai" %}
Add GrowSurf as a remote custom connector in Claude on the web.

1. Open *Settings > Connectors*. On Team or Enterprise, an organization owner must first add the connector under *Organization settings > Connectors*.
2. Select **Add custom connector** and name it **GrowSurf**. Organization owners choose *Add > Custom > Web*.
3. Enter this remote MCP server URL:

   ```
   https://mcp.growsurf.com
   ```
4. Select **Add**, then **Connect**, and sign in to GrowSurf to approve the requested access.
   {% endtab %}

{% tab title="Claude Desktop" %}
Claude remote connectors are tied to your Claude account and also work in Claude Desktop.

1. Open *Settings > Connectors* for the same Claude account you use in Claude Desktop.
2. Select **Add custom connector** and name it **GrowSurf**. On Team or Enterprise, an organization owner must add it first.
3. Enter this remote MCP server URL:

   ```
   https://mcp.growsurf.com
   ```
4. Select **Connect**, sign in to GrowSurf, approve access, then enable **GrowSurf** in Claude Desktop.
   {% endtab %}

{% tab title="Claude Code" %}
Recommended: connect Claude Code to GrowSurf's hosted MCP endpoint:

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

On first use, Claude Code opens GrowSurf sign-in and consent. You can also start that flow directly:

```bash
claude mcp login growsurf
```

If you prefer local stdio, install the local server directly into Claude Code:

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

For a single existing campaign in local stdio, add:

```bash
-e GROWSURF_CAMPAIGN_ID=YOUR_CAMPAIGN_ID
```

Manual API-key fallback for the hosted endpoint:

```bash
claude mcp add --transport http growsurf https://mcp.growsurf.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
```

For a single existing campaign on the manual hosted path, add:

```bash
--header "x-growsurf-campaign-id: YOUR_CAMPAIGN_ID"
```

{% endtab %}

{% tab title="GitHub Copilot" %}
Add GrowSurf as a remote MCP server in VS Code, then use it from Copilot's agent mode.

Run this in your terminal, or open the Command Palette and run *MCP: Add Server > HTTP*:

```bash
code --add-mcp '{"name":"growsurf","type":"http","url":"https://mcp.growsurf.com"}'
```

Open Copilot Chat, switch to **Agent** mode, start GrowSurf, then sign in and approve access when VS Code prompts you.
{% endtab %}

{% tab title="Cursor" %}
Open *Cursor Settings > Tools & Integrations*, select **New MCP Server**, and add a server named `growsurf`.

Recommended: add GrowSurf's hosted MCP endpoint to `mcp.json`:

{% code overflow="wrap" %}

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

{% endcode %}

For API-key auth instead of OAuth, use the manual hosted path:

{% code overflow="wrap" %}

```json
{
  "mcpServers": {
    "growsurf": {
      "url": "https://mcp.growsurf.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

{% endcode %}

If you prefer local stdio, add this to `mcp.json`:

{% code overflow="wrap" %}

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

{% endcode %}

**Sign-in window didn't open?** Some Cursor versions never open the GrowSurf sign-in window (a bug in Cursor, not your setup). Replace the `growsurf` entry with this configuration and reconnect. It needs Node.js installed, and opens sign-in in your browser on the first connection:

{% code overflow="wrap" %}

```json
{
  "mcpServers": {
    "growsurf": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.growsurf.com"]
    }
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="Codex" %}
Recommended: connect Codex to GrowSurf's hosted MCP endpoint:

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

Start GrowSurf sign-in and consent:

```bash
codex mcp login growsurf
```

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

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

For API-key auth instead of OAuth, point Codex at the manual hosted path and read the API key from an environment variable:

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

If you prefer local stdio, create or edit `~/.codex/config.toml`:

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

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

Or configure it from the CLI:

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

{% endtab %}

{% tab title="Gemini CLI" %}
Connect GrowSurf to Gemini CLI over HTTP:

```bash
gemini mcp add --transport http growsurf https://mcp.growsurf.com
```

Open Gemini CLI, run `/mcp` to check the connection, then finish signing in and approve access in your browser.
{% endtab %}

{% tab title="Windsurf" %}
Add GrowSurf as a remote MCP server in Windsurf's Cascade.

1. Open *Windsurf Settings > Cascade > Manage MCP servers*, then add a custom server.
2. Add a remote server named **GrowSurf** with this URL:

   ```
   https://mcp.growsurf.com
   ```
3. Refresh the server list, then sign in to GrowSurf and approve access.
   {% endtab %}

{% tab title="Cline" %}
Add GrowSurf as a remote MCP server in the Cline extension.

1. In Cline, open the *MCP Servers* panel and choose *Remote Servers*.
2. Add a server named **GrowSurf** with this URL:

   ```
   https://mcp.growsurf.com
   ```
3. Connect, then sign in to GrowSurf and approve access.
   {% endtab %}

{% tab title="Antigravity" %}
Open Antigravity, click the **…** menu, select *MCP Store*, then open *Manage MCP Servers > View raw config*.

Recommended: add GrowSurf's hosted MCP endpoint to `mcp_config.json`. Antigravity uses `serverUrl` for remote MCP servers:

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

For API-key auth instead of OAuth, use the manual hosted path:

```json
{
  "mcpServers": {
    "growsurf": {
      "serverUrl": "https://mcp.growsurf.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

If you prefer local stdio, add this to `mcp_config.json`:

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

{% endtab %}

{% tab title="Other" %}
For any other client that supports remote Streamable HTTP MCP servers with OAuth:

1. Add a remote Streamable HTTP MCP server and name it **GrowSurf**.
2. Use this OAuth-capable server URL:

   ```
   https://mcp.growsurf.com
   ```
3. Start the connection, then sign in to GrowSurf and approve access.

If your client asks for a URL and custom headers instead of GrowSurf sign-in, use `https://mcp.growsurf.com/mcp` with header `Authorization: Bearer YOUR_API_KEY`.
{% endtab %}
{% endtabs %}

#### Hosted Streamable HTTP endpoint

Use hosted OAuth when your MCP client supports remote Streamable HTTP with OAuth:

* URL: `https://mcp.growsurf.com`
* Auth: GrowSurf sign-in and consent.
* API keys: not required for OAuth clients.

Use this option if your MCP client asks for a URL and custom headers instead of opening GrowSurf sign-in:

* URL: `https://mcp.growsurf.com/mcp`
* Required header for API-calling tools: `Authorization: Bearer YOUR_API_KEY`
* Optional header for a default campaign: `x-growsurf-campaign-id: YOUR_CAMPAIGN_ID`

The local server and manual fallback can use the account-bootstrap tool without an API key. OAuth clients use the GrowSurf team you select and approve. Campaign-scoped tools need either a `campaignId` argument or a default campaign header/environment value.

#### Hosted OAuth connector

GrowSurf's hosted MCP endpoint supports OAuth for ChatGPT, Claude.ai, Claude Desktop, Claude Code, GitHub Copilot, Cursor, Codex, Gemini CLI, Windsurf, Cline, Antigravity, and other compatible remote MCP clients. Browser-only clients must support custom remote MCP/OAuth connectors; if yours does not, use a supported coding agent or the local stdio setup.

#### What access you approve

When you sign in through the hosted connector, GrowSurf asks you to approve access before the agent can do anything. The agent can then, on your behalf:

* Read and update the selected team.
* Read, create, and update programs; create, update, or delete their reward configuration and webhooks.
* Read, add, update, and remove participants.
* Record or refund sales and approve commissions or rewards.
* Read analytics.

The hosted MCP server asks only for scopes used by its current tools. It does not request permission to rotate API keys, delete programs, read detailed reward, commission, or payout records, delete issued rewards, or fulfill rewards. API-key rotation is not an MCP action. Rotate a key from GrowSurf Settings or through a direct REST/SDK client whose API key has the `api_key:rotate` scope.

MCP Team tools stay on the team selected during approval.

You can review or revoke a connected client at any time from your GrowSurf account settings.

***

### Example prompts

After you have the MCP installed, view these example prompts for quickly creating a GrowSurf program.

<details>

<summary><strong>Referral programs</strong></summary>

Ask your agent to use the GrowSurf MCP tools:

```
Use GrowSurf to create a referral program for Acme. Review the default Design, Emails, Options, Installation, and Rewards. Keep rewards safe until I approve them. Return the campaign editor URL and summarize the settings.
```

{% hint style="info" %}
The agent should use this order:

1. `growsurf_create_campaign` with `type: "REFERRAL"`.
2. `growsurf_get_campaign`, `growsurf_list_campaign_rewards`, `growsurf_get_campaign_design`, `growsurf_get_campaign_emails`, `growsurf_get_campaign_options`, and `growsurf_get_campaign_installation`.
3. Patch only requested changes with the `growsurf_update_campaign_*` tools.
4. Fetch the updated campaign, Design, Emails, Options, Installation, and Rewards before reporting back.
   {% endhint %}

</details>

<details>

<summary><strong>Affiliate programs</strong></summary>

Affiliate programs can create payable obligations, so have the agent confirm payout and tax settings before launch:

```
Create an affiliate program for Acme in USD. Review commission defaults, payout threshold, tax collection, affiliate portal design, and emails. Do not publish until I approve the money settings.
```

{% hint style="info" %}
The agent should inspect:

* `growsurf_list_campaign_rewards` for commission/reward config.
* `growsurf_get_campaign_options` for approval, payout, and tax settings.
* `growsurf_get_campaign_design` for affiliate portal sections such as commissions, payouts, affiliate summary, and participant settings.
* `growsurf_get_campaign_design`, `growsurf_get_campaign_emails`, and `growsurf_get_campaign_options` for configuration review.
  {% endhint %}

</details>

***

### Agent Skills

GrowSurf also ships an Agent Skill recipe layer with the MCP package. If your agent supports skills, install or copy the [`growsurf-agent-toolkit`](https://github.com/growsurf/growsurf-mcp/tree/main/skills/growsurf-agent-toolkit) skill from the MCP package. It gives the agent a stricter workflow for:

* Creating referral programs.
* Creating affiliate programs.
* Embedding the widget.
* Adjusting rewards.
* Wiring webhooks.
* Reading analytics.

{% hint style="info" %}
MCP prompts are also bundled in the server, so compatible MCP clients can discover the same recipes without a separate skill install.
{% endhint %}

***

### Resources

* [GrowSurf MCP server](https://github.com/growsurf/growsurf-mcp)
* [GrowSurf REST API reference](/developer-tools/rest-api/api-reference.md)
* [Model Context Protocol](https://modelcontextprotocol.io/introduction)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.growsurf.com/build-with-ai.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.