GrowSurf MCP Server

Official

by growsurf

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

Get Participant

growsurf_get_participant

Read-onlyIdempotent

Instructions

Fetch a single participant by GrowSurf participant ID or email address. referralStatus describes credit to their referrer; referralCount counts referrals this participant generated, so zero is consistent with CREDIT_AWARDED. In rewards, approved records approval; status, isFulfilled, and fulfilledAt record fulfillment marking, not confirmation of delivery. Targets campaignId if you pass it, otherwise GROWSURF_CAMPAIGN_ID.

Input Schema

Name	Required	Description
`campaignId`	Yes	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.
`participantId`	No
`participantEmail`	No

Output Schema

Name	Required	Description
`id`	No	The participant's unique id.
`rank`	No	All-time leaderboard rank.
`email`	No	The participant's email address.
`isNew`	No	`true` when the request created the participant. Returned by participant creation calls.
`notes`	No	Internal notes. Never shown to participants.
`rewards`	No	Rewards the participant has earned.
`isWinner`	No	`true` once the participant has earned at least one reward.
`language`	No	The language code of the participant's portal and program emails, such as `es`. The program's base language unless the participant (or you) picked another of the program's languages.
`lastName`	No	The participant's last name.
`metadata`	No	Custom key/value metadata (single level).
`referrer`	No	Summary of the participant's referrer (same core fields as a participant). Present only when the participant was referred.
`shareUrl`	No	The participant's unique referral link. Omitted for affiliate program participants who are not approved affiliates.
`createdAt`	No	When the participant joined, as a Unix timestamp in milliseconds.
`firstName`	No	The participant's first name.
`ipAddress`	No	IP address recorded for the participant, or `null`.
`leadCount`	No	Pending referrals that have not converted yet.
`referrals`	No	Ids of participants they successfully referred (100 most recent).
`referredBy`	No	Id of the referrer. Present only when the participant was referred.
`shareCount`	No	Share counts keyed by channel (e.g. `email`, `facebook`, `twitter`, `copyRefLink`, `iosNativeShare`).
`vanityKeys`	No	The participant's vanity keys.
`fingerprint`	No	Browser identifier recorded for the participant, or `null`.
`inviteCount`	No	Invites sent by the participant.
`isAffiliate`	No	Affiliate programs only. Whether this participant is an enrolled affiliate. A referred customer who has not joined the program is `false`.
`monthlyRank`	No	Current-month leaderboard rank (resets monthly).
`unsubscribed`	No	`true` if the participant unsubscribed from program emails.
`referralCount`	No	All-time referrals credited to the participant.
`fraudRiskLevel`	No	The participant's fraud risk level.
`payoutSettings`	No	Actions the participant must complete before a payout can be released. Always present.
`referralSource`	No	How the participant joined the program. `DIRECT` means without a referrer, `PARTICIPANT` means through a participant referral, `IMPORT` means through a CSV import, `MANUAL` means through the dashboard, and `DELETED_PARTICIPANT` means the original referrer was later deleted.
`referralStatus`	No	The referrer's credit status for this participant. Present only when the participant was referred.
`rewardEvidence`	No	What this response establishes about rewards. Combine with other reads; unknown here does not override evidence elsewhere.
`affiliateStatus`	No	Affiliate programs only. The enrolled affiliate's status (`APPROVED`, `SUSPENDED`, or `BANNED`). `null` for participants who are not affiliates.
`fraudReasonCode`	No	Reason code behind `fraudRiskLevel` (e.g. `UNIQUE_IDENTITY`, `DUPLICATE_EMAIL`, `MANUAL_UPDATE`).
`impressionCount`	No	Total views of the participant's referral link.
`prevMonthlyRank`	No	Previous-month leaderboard rank.
`mobileInstanceId`	No	App-install scoped identifier supplied by a native app, or `null`.
`monthlyReferrals`	No	Ids of participants they successfully referred this month (100 most recent).
`paypalEmailAddress`	No	PayPal email address on file, used for affiliate or PayPal reward payouts.
`unreadPayoutsCount`	No	Payouts the participant has not yet viewed. Affiliate programs only.
`monthlyReferralCount`	No	Referrals credited this month (resets monthly).
`allMatchingFraudsters`	No	Other participants flagged as matching this participant during anti-fraud checks.
`uniqueImpressionCount`	No	Unique views of the participant's referral link.
`unreadCommissionsCount`	No	Commissions the participant has not yet viewed. Affiliate programs only.
`prevMonthlyReferralCount`	No	Referrals credited the previous month.
`affiliateEnrollmentSource`	No	Affiliate programs only. How the affiliate enrolled (`OPEN_ENROLLMENT`, `APPLICATION`, `PARTICIPANT_AUTH`, `INVITE`, `REST_API`, `CSV`, or `DASHBOARD`). `null` when not recorded.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.19.23Oct 22, 2026

changedOutput schema / properties / referralSource / description

Previous value: -"How the participant joined the program."New value: +"How the participant joined the program. `DIRECT` means without a referrer, `PARTICIPANT` means through a participant referral, `IMPORT` means through a CSV import, `MANUAL` means through the dashboard, and `DELETED_PARTICIPANT` means the original referrer was later deleted."

changedOutput schema / properties / referralSource / enum

Previous value: -[
-  "DIRECT",
-  "PARTICIPANT"
-]New value: +[
+  "DIRECT",
+  "PARTICIPANT",
+  "DELETED_PARTICIPANT",
+  "IMPORT",
+  "MANUAL"
+]

Changed3 schema fields changedv0.19.15Oct 15, 2026

addedInput schema / properties / campaignId / minLength
```
Added value: +1
```
addedInput schema / required
```
Added value: +[
+  "campaignId"
+]
```

addedOutput schema / properties / language

Added value: +{
+  "description": "The language code of the participant's portal and program emails, such as `es`. The program's base language unless the participant (or you) picked another of the program's languages.",
+  "type": "string"
+}

Changed1 schema field changedv0.19.9Oct 3, 2026

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

Changed1 schema field changedv0.18.1Sep 23, 2026

addedOutput schema / properties / leadCount

Added value: +{
+  "description": "Pending referrals that have not converted yet.",
+  "type": "integer"
+}

Changed5 schema fields changedv0.14.0Sep 10, 2026

addedOutput schema / properties / rewardEvidence

Added value: +{
+  "description": "What this response establishes about rewards. Combine with other reads; unknown here does not override evidence elsewhere.",
+  "properties": {
+    "approvalPolicy": {
+      "description": "Referral reward approval policy from requireManualRewardApproval, not affiliate commission approval or an individual reward state.",
+      "enum": [
+        "manual",
+        "automatic",
+        "unknown"
+      ],
+      "type": "string"
+    },
+    "automaticFulfillmentMarking": {
+      "description": "The autoFulfillRewards setting, when returned by an options read. Null means unknown; this controls marking, not delivery.",
+      "type": [
+        "boolean",
+        "null"
+      ]
+    },
+    "basis": {
+      "enum": [
+        "this_response_only"
+      ],
+      "type": "string"
+    },
+    "conclusion": {
+      "type": "string"
+    },
+    "deliveryStatus": {
+      "enum": [
+        "unknown"
+      ],
+      "type": "string"
+    },
+    "integrationConnection": {
+      "enum": [
+        "not_established"
+      ],
+      "type": "string"
+    },
+    "nextStep": {
+      "type": "string"
+    },
+    "programReferralTrigger": {
+      "enum": [
+        "not_established"
+      ],
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

changedOutput schema / properties / rewards / items / properties / fulfilledAt / description

Previous value: -"When the reward was fulfilled, as a Unix timestamp in milliseconds. `null` until fulfilled."New value: +"When the reward was marked fulfilled, as a Unix timestamp in milliseconds. `null` until marked fulfilled; this is not a delivery receipt."

changedOutput schema / properties / rewards / items / properties / isFulfilled / description

Previous value: -"`true` once the reward has been fulfilled."New value: +"`true` once the reward is marked fulfilled. Confirm actual delivery through fulfillment records."

changedOutput schema / properties / rewards / items / properties / status / description

Previous value: -"Fulfillment status of the earned reward."New value: +"Fulfillment marking of the earned reward. `FULFILLED` records that it was marked fulfilled, not proof of delivery. `CANCELLED` means an unpaid Lead reward was reversed before fulfillment."

changedOutput schema / properties / rewards / items / properties / status / enum

Previous value: -[
-  "PENDING",
-  "FULFILLED"
-]New value: +[
+  "PENDING",
+  "FULFILLED",
+  "CANCELLED"
+]

First observedv0.12.2Aug 25, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive, closed-world), so the bar is lower, yet the description adds real value by interpreting field semantics: referralStatus vs referralCount (zero consistent with CREDIT_AWARDED) and that rewards.status/isFulfilled/fulfilledAt mark fulfillment, not delivery. That is genuine meaning an agent could not derive from the annotations.

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-loaded with the core purpose, then dense field-semantics clauses. Every sentence carries information, though the rewards-field interpretation is fairly detailed for a description and borders on output-documentation territory.

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?

An output schema exists so return values need not be documented, yet the description still clarifies ambiguous fields. Purpose, lookup keys, and targeting are all covered; only identifier formats and any pagination/error behavior are unaddressed, which is minor for a single-record fetch.

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?

Schema description coverage is only 33% (only campaignId documented), so the description must compensate, and it does: it explains that the participant can be identified by either ID or email (mirroring the anyOf alternation) and that campaignId overrides the GROWSURF_CAMPAIGN_ID default. It does not, however, describe the format of either identifier.

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

Purpose5/5

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

States a specific verb (Fetch) and resource (a single participant) and gives the two lookup keys (participant ID or email). The word 'single' implicitly separates it from the list_participants sibling, so an agent can tell which one to pick without opening the schema.

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

Usage Guidelines3/5

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

Usage is implied rather than stated: an agent can infer 'fetch one record' vs the sibling list/analytics/activity-log tools, and the campaignId targeting note hints at routing. But there is no explicit when-to-use, when-not, or named alternative, so it stays at the minimum-viable level.

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

Deploy Server