Skip to main content
Glama
GrowSurf MCP Server

GrowSurf MCP Server

Official

Add Participant

growsurf_add_participant

Add or fetch a participant by email, complete a pending offer signup, and directly enroll new participants, including affiliates, without the public review flow.

Instructions

Add or fetch a participant by email. If the email already exists, the existing participant is returned unchanged. One exception: if that participant claimed an offer in the Claim Offer Popup and the signup is not complete yet, this call completes the signup with the original referrer and saves any non-blank firstName, lastName, and metadata you send. This is trusted direct enrollment and bypasses the public application review flow for affiliates. For affiliate programs, set isAffiliate to true to enroll a new participant as approved or false to create a non-affiliate. If you omit it, a valid referredBy creates a referred non-affiliate; without a valid referrer, the new participant is enrolled as approved. A valid referredBy can be combined with isAffiliate: true. A 409 means the same participant is already being added or cannot join right now, so do not retry in a loop. A 422 means the program's fraud rules blocked the participant. Targets campaignId if you pass it, otherwise GROWSURF_CAMPAIGN_ID.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "email": "<email>",
      "campaignId": "<campaignId>"
    },
    "name": "growsurf_add_participant"
  }
}

Input Schema

NameRequiredDescriptionDefault
emailYes
groupIdNoPlaces the new participant in this group (`grp_…`), or in Default with `null`. This is a manual placement, so the groups' email and domain rules do not apply to them. Applies only when this call creates the participant; to move an existing participant, use `growsurf_update_participant`. An ID that is not a group in this program returns `400` and adds no one.
languageNoThe language of the participant's portal and program emails. Stored when it is one of the program's languages (`languages` in `growsurf_get_campaign_options`). A regional tag maps to its language (for example, `fr-BE` is stored as `fr`). Any other value is ignored and the program's base language applies. Applies only when this call creates the participant. Omit it to use the program's base language. Supported codes: `en`, `es`, `fr`, `de`, `it`, `pt-BR`, `nl`, `pl`, `sv`, `tr`, `ja`, `ko`, `zh-CN`, `id`, `da`, `nb`, `nn`, `fi`, `is`, `cs`, `sk`, `hu`, `ro`, `hr`, `sl`, `et`, `lv`, `lt`, `el`, `bg`, `uk`, `ru`, `pt-PT`, `ca`, `vi`, `ms`, `fil`, `af`, `sw`, `zh-TW`, `es-419`.
lastNameNo
metadataNo
firstNameNo
ipAddressNo
campaignIdYesTarget program id for this call: the `id` returned by `growsurf_list_campaigns`, not the program name or a share URL. Defaults to GROWSURF_CAMPAIGN_ID when omitted. Program IDs also identify newly created programs without restarting the server.
referredAtNoWhen the participant was referred, in Unix milliseconds. Used only with a valid `referredBy`. If you omit `referralStatus`, GrowSurf compares this time with the program's referral credit window to set it. Defaults to the time of the request.
referredByNo
fingerprintNo
isAffiliateNoAffiliate programs only. Controls affiliate enrollment for a new participant. `true` enrolls the participant with `affiliateStatus: APPROVED`; `false` creates a non-affiliate without `affiliateStatus`. Existing participants are returned unchanged.
referralStatusNo
mobileInstanceIdNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.19.33
    • changedInput schema / properties / campaignId / description
      Previous value: -"Target program (campaign) id for this call. Defaults to GROWSURF_CAMPAIGN_ID when omitted. Program IDs also identify newly created programs without restarting the server."New value: +"Target program id for this call: the `id` returned by `growsurf_list_campaigns`, not the program name or a share URL. Defaults to GROWSURF_CAMPAIGN_ID when omitted. Program IDs also identify newly created programs without restarting the server."
  2. Changed1 schema field changedv0.19.32
    • addedInput schema / properties / groupId
      Added value: +{
      +  "description": "Places the new participant in this group (`grp_…`), or in Default with `null`. This is a manual placement, so the groups' email and domain rules do not apply to them. Applies only when this call creates the participant; to move an existing participant, use `growsurf_update_participant`. An ID that is not a group in this program returns `400` and adds no one.",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
  3. Changed1 schema field changedv0.19.28
    • changedInput schema / properties / language / description
      Previous value: -"The language of the participant's portal and program emails. Stored when it is one of the program's languages (`languages` in `growsurf_get_campaign_options`). A regional tag maps to its language (for example, `es-MX` is stored as `es`). Any other value is ignored and the program's base language applies. Applies only when this call creates the participant. Omit it to use the program's base language. Supported codes: `en`, `es`, `fr`, `de`, `it`, `pt-BR`, `nl`, `pl`, `sv`, `tr`, `ja`, `ko`, `zh-CN`, `id`, `da`, `nb`, `nn`, `fi`, `is`, `cs`, `sk`, `hu`, `ro`, `hr`, `sl`, `et`, `lv`, `lt`, `el`, `bg`, `uk`, `ru`, `pt-PT`, `ca`, `vi`, `ms`, `fil`, `af`, `sw`."New value: +"The language of the participant's portal and program emails. Stored when it is one of the program's languages (`languages` in `growsurf_get_campaign_options`). A regional tag maps to its language (for example, `fr-BE` is stored as `fr`). Any other value is ignored and the program's base language applies. Applies only when this call creates the participant. Omit it to use the program's base language. Supported codes: `en`, `es`, `fr`, `de`, `it`, `pt-BR`, `nl`, `pl`, `sv`, `tr`, `ja`, `ko`, `zh-CN`, `id`, `da`, `nb`, `nn`, `fi`, `is`, `cs`, `sk`, `hu`, `ro`, `hr`, `sl`, `et`, `lv`, `lt`, `el`, `bg`, `uk`, `ru`, `pt-PT`, `ca`, `vi`, `ms`, `fil`, `af`, `sw`, `zh-TW`, `es-419`."
  4. Changed9 schema fields changedv0.19.27
    • addedInput schema / properties / fingerprint / maxLength
      Added value: +255
    • addedInput schema / properties / firstName / maxLength
      Added value: +255
    • addedInput schema / properties / ipAddress / maxLength
      Added value: +255
    • changedInput schema / properties / language / description
      Previous value: -"The language of the participant's portal and program emails. Must be one of the program's languages (`languages` in `growsurf_get_campaign_options`); any other code returns a `400`. Applies only when this call creates the participant. Omit it or send `null` to use the program's base language. Supported codes: `en`, `es`, `fr`, `de`, `it`, `pt-BR`, `nl`, `pl`, `sv`, `tr`, `ja`, `ko`, `zh-CN`, `id`, `da`, `nb`, `nn`, `fi`, `is`, `cs`, `sk`, `hu`, `ro`, `hr`, `sl`, `et`, `lv`, `lt`, `el`, `bg`, `uk`, `ru`, `pt-PT`, `ca`, `vi`, `ms`, `fil`, `af`, `sw`."New value: +"The language of the participant's portal and program emails. Stored when it is one of the program's languages (`languages` in `growsurf_get_campaign_options`). A regional tag maps to its language (for example, `es-MX` is stored as `es`). Any other value is ignored and the program's base language applies. Applies only when this call creates the participant. Omit it to use the program's base language. Supported codes: `en`, `es`, `fr`, `de`, `it`, `pt-BR`, `nl`, `pl`, `sv`, `tr`, `ja`, `ko`, `zh-CN`, `id`, `da`, `nb`, `nn`, `fi`, `is`, `cs`, `sk`, `hu`, `ro`, `hr`, `sl`, `et`, `lv`, `lt`, `el`, `bg`, `uk`, `ru`, `pt-PT`, `ca`, `vi`, `ms`, `fil`, `af`, `sw`."
    • changedInput schema / properties / language / type
      Previous value: -[
      -  "string",
      -  "null"
      -]New value: +"string"
    • addedInput schema / properties / lastName / maxLength
      Added value: +255
    • addedInput schema / properties / mobileInstanceId / maxLength
      Added value: +255
    • addedInput schema / properties / referredAt
      Added value: +{
      +  "description": "When the participant was referred, in Unix milliseconds. Used only with a valid `referredBy`. If you omit `referralStatus`, GrowSurf compares this time with the program's referral credit window to set it. Defaults to the time of the request.",
      +  "minimum": 0,
      +  "type": [
      +    "integer",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / referredBy / maxLength
      Added value: +100
  5. Changed3 schema fields changedv0.19.15
    • addedInput schema / properties / campaignId / minLength
      Added value: +1
    • addedInput schema / properties / language
      Added value: +{
      +  "description": "The language of the participant's portal and program emails. Must be one of the program's languages (`languages` in `growsurf_get_campaign_options`); any other code returns a `400`. Applies only when this call creates the participant. Omit it or send `null` to use the program's base language. Supported codes: `en`, `es`, `fr`, `de`, `it`, `pt-BR`, `nl`, `pl`, `sv`, `tr`, `ja`, `ko`, `zh-CN`, `id`, `da`, `nb`, `nn`, `fi`, `is`, `cs`, `sk`, `hu`, `ro`, `hr`, `sl`, `et`, `lv`, `lt`, `el`, `bg`, `uk`, `ru`, `pt-PT`, `ca`, `vi`, `ms`, `fil`, `af`, `sw`.",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • changedInput schema / required
      Previous value: -[
      -  "email"
      -]New value: +[
      +  "email",
      +  "campaignId"
      +]
  6. Changed1 schema field changedv0.19.9
    • changedInput schema / properties / campaignId / description
      Previous value: -"Target program (campaign) id for this call. Defaults to GROWSURF_CAMPAIGN_ID when omitted. Pass the `id` returned by growsurf_create_campaign to configure or operate a program you just created, without restarting the server."New value: +"Target program (campaign) id for this call. Defaults to GROWSURF_CAMPAIGN_ID when omitted. Program IDs also identify newly created programs without restarting the server."
  7. First observedv0.12.2

TDQS

A4.2/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations by disclosing that this is trusted direct enrollment that bypasses the public application review flow for affiliates, exactly what happens when the email already exists, the one exception path and which fields it writes, and what 409 and 422 mean operationally. This is the kind of mutation-side-effect context the readOnlyHint/destructiveHint flags cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core add-or-fetch behavior and then layers conditionals, with no filler sentences. The affiliate default rule is packed into one long sentence that takes a careful read, but every clause carries decision-relevant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with annotations and an output schema, the description covers the risky parts: bypass of review flow, silent no-op on existing participants, and error-code semantics. Remaining gaps are per-parameter details on the create path that the partially documented schema only half supplies.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With only 36% schema coverage across 14 params, the description compensates by explaining cross-parameter behavior: firstName/lastName/metadata only persist on the claim-offer exception path, isAffiliate's three-way default resolution with referredBy, and campaignId falling back to GROWSURF_CAMPAIGN_ID. Other params (groupId, language, referredAt, referralStatus, fingerprint, ipAddress) are left to the schema or undocumented in both places.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource: "Add or fetch a participant by email," and immediately clarifies the upsert semantics. An agent can tell this is the write/enroll path rather than a pure lookup like growsurf_get_participant, though no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete conditional guidance: existing email returns unchanged, the Claim Offer Popup exception completes an incomplete signup, isAffiliate controls affiliate enrollment, and 409/422 responses should not be retried. It lacks an explicit "use growsurf_update_participant for existing participants" routing statement in the description itself.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools