# Co-Sell with AI (MCP)

Run the full co-sell referral lifecycle from your AI assistant, using natural language

---

## Overview

The [Fours MCP Server](/mcp/overview) exposes Fours' co-sell APIs as tools that any
[Model Context Protocol](https://modelcontextprotocol.io/) client — Claude Desktop, Claude Code,
Cursor, VS Code (GitHub Copilot), Windsurf, ChatGPT — can call. Instead of clicking through the
Fours Console, a Partner or Alliance Manager can describe what they want in plain language and let
the assistant create referrals, look up status, sync with the cloud partner, and read dashboard
insights.

One connection covers **AWS, Azure, and GCP** co-sell, plus peer-to-peer co-sell with the partner
companies you work with through Fours. The destination is chosen per call by the `partner` field:
`AWS` / `AZURE` / `GCP` share the opportunity with that cloud provider, and `SUGER` shares it with
another company you partner with through Fours.

**Availability:** All Fours pricing plans

**MCP Server URL:** `https://apiv2.suger.cloud/mcp`

See [MCP → Setup](/mcp/setup) to connect your client, and [MCP → Overview](/mcp/overview) for the
full tool catalog and security model.

**Prerequisite:** your organization's co-sell integration must already be connected — see
[Co-Sell Configuration](/cosell/cosell-configuration).

## Co-Sell tools

The MCP server exposes 19 co-sell tools, covering the whole referral lifecycle:

| Tool | What it does |
|------|--------------|
| `ListCosellReferrals` | List referrals (inbound + outbound) with filters — partner, status, stage, time range, text |
| `GetCosellReferral` | Get the full record for one referral by ID |
| `CreateCosellReferral` | Create an outbound referral to a cloud provider (AWS / AZURE / GCP) or to a partner company (SUGER) |
| `RegisterCosellOnBehalf` | Register a co-sell referral on behalf of another company you partner with |
| `UpdateCosellReferral` | Edit referral fields, status, or stage — and, on a referral a partner shared with you, accept or decline it |
| `BatchCreateCosellReferrals` | Create several referrals in one call (recommended ≤ 20) |
| `BatchPreviewCosellReferrals` | Preview the referrals that would be created from CRM records, before creating them |
| `ValidateReferral` | Dry-run validate a referral against the partner schema **before** creating it |
| `PredictReferralQualityScore` | Predict the AWS opportunity quality score for a referral |
| `SyncSingleReferral` | Sync one referral inbound or outbound with the cloud partner; on a `SUGER` referral this syncs the linked CRM record instead |
| `AzureInvitePartnerCollaboration` | Invite another partner to collaborate on an Azure referral (Azure only) |
| `AzureMicrosoftSolutionLookup` | Look up a Microsoft first-party solution to attach to an Azure referral (Azure only) |
| `AzureThirdPartySolutionLookup` | Look up a third-party (marketplace) solution to attach to an Azure referral (Azure only) |
| `GetCosellDashboard` | Co-sell insights — pipeline KPIs, outstanding actions, activity logs |
| `GetPartnerContacts` | List known partner contacts for a buyer company (by email domain) |
| `SearchPartnerConnections` | Search the org's connected AWS partners by name |
| `UpdateCosellPartner` | Seller-only. Update one partner's copy of a `SUGER` co-sell — revenue-share terms (before Close Won), deal-value visibility, and collaboration fields |
| `ProposeCommissionUpdate` | Seller-only. Request a change to a partner's commission terms *after* Close Won; the change needs that partner's approval |
| `UpdateCommissionLifecycle` | Advance a `SUGER` co-sell's commission to its next state once the deal is Won |

The descriptions above are deliberately short. For each tool's full parameter list and
response shape, see [MCP → Supported Tools](/mcp/tools/).

:::note
`BatchPreviewCosellReferrals` and `PredictReferralQualityScore` call a language model and record AI
usage for your organization, so each call has a cost.
:::

### What `ValidateReferral` returns

Two behaviours are worth knowing before you build a workflow on the dry run:

- **Duplicate open referrals come back as a warning.** If the same partner already has a
  still-open referral matching the one you are validating, `ValidateReferral` reports it.
  It is advisory — the create call is not blocked, because two referrals can legitimately
  exist for the same customer.
- **`partner=SUGER` is rejected.** Validation covers **AWS, GCP, and Azure** only. Asking
  the assistant to validate a Fours partner-to-partner referral returns an error rather
  than a result — skip validation and call `CreateCosellReferral` directly for `SUGER`.

### Fours peer-to-peer referrals (`partner=SUGER`)

A `SUGER` referral is shared with another company you partner with through Fours, not with a cloud
provider. It behaves differently in four ways worth knowing before you prompt for one:

- **The partner responds in Fours.** The recipient gets their own copy in `PENDING_ACCEPTANCE`.
  They accept by moving it to `ACTIVE`, or decline by setting `status` to `REJECTED` with a
  `declineReason` (required — the request is refused without it). Only the company that *received*
  the referral can respond; the sender withdraws instead. Both use `UpdateCosellReferral`.
- **No outbound sync is needed.** There is no external partner system to push to — Fours keeps the
  partner's copy in step itself. `SyncSingleReferral` on a `SUGER` referral synchronizes the linked
  **CRM** record, accepts `direction=OUTBOUND` only, and returns an error for `INBOUND`.
- **Send only the fields you are changing.** On a partner's copy whose deal value is hidden, a read
  returns `dealValueAmount`, `dealValueCurrency` and `sharePercentage` blanked out. Reading a
  referral and sending the whole object back writes those blanks or fails validation — so ask the
  assistant to patch specific fields rather than echo a record back.
- **Won needs an accepted co-sell.** A `SUGER` co-sell can move to stage `Won` only once its
  status is `ACTIVE`. Before it has been accepted, the update is refused with
  `cannot close as Won from status "…"; the co-sell must be Active (accepted) first`.

Use `ListPrmPartners` (see [MCP → Supported Tools](/mcp/tools/)) to find the partner and get the
`partnerId` a `SUGER` referral needs.

#### Commission tools

Three of the tools above apply only to `SUGER` referrals, and only after the deal is Won.

`UpdateCommissionLifecycle` advances a commission by naming the **target state** you want; the
action is derived from the current and target pair. Only four states can be named as a target, and
only from the state that legitimately precedes them:

| From | Target `state` | What it means |
| --- | --- | --- |
| `PENDING` | `APPROVED` | The commission terms are agreed. |
| `APPROVED` | `PAYMENT_SENT` | Payment has been sent to the partner. |
| `PAYMENT_SENT` | `CONFIRMED` | The partner confirmed receipt. |
| `PAYMENT_SENT` | `APPROVED` | The partner **rejected** the payment, sending it back for another attempt. |
| `CONFIRMED` | `CLAWED_BACK` | The commission has been reversed after receipt was confirmed. |

Any other pair is refused with `INVALID_TRANSITION`.

:::warning
**Do not send `PAYMENT_REJECTED` as a target.** It is a state the server writes for you: rejecting a
payment is expressed as `PAYMENT_SENT → APPROVED`, and the server records the rejection and the revert
as two history entries in one write. The same is true of `PENDING` and `PENDING_UPDATE_APPROVAL` —
they are states you can observe, never states you can ask for.
:::

The commission lives on the **payee** (reseller) copy, which the server resolves for you — you
always pass your *own* `referralId`. A **Seller** must additionally send `partnerOrganizationId`
to say whose commission is being acted on; a partner acting on its own commission omits it.

To change the commission *terms* rather than advance the state, use `ProposeCommissionUpdate`.
That is a Seller-only request that needs the partner's approval, which the partner gives back
through `UpdateCommissionLifecycle`.

:::note
Destructive or org-wide operations are intentionally **not** exposed to AI — deleting a referral,
bulk-syncing an entire org, auto-share, and system-config endpoints must be done in the Fours
Console. Co-sell **funding** applications are managed in the Console and API (see
[Co-Sell Funding](/cosell/cosell-funding)); they are not available as MCP tools.
:::

## Example prompts

- **List:** "List my AWS referrals in Pending Acceptance status from last week."
- **Detail:** "Show me referral `ref-abc123`."
- **Create:** "Create an AWS co-sell referral for Acme Corp, expected close date 2026-09-30."
- **Validate first:** "Validate this referral against the AWS schema before I submit it."
- **Update status / stage:** "Move referral `ref-abc123` from Draft to Submitted."
- **Sync:** "Sync referral `ref-abc123` outbound to AWS."
- **Insights:** "Show my co-sell pipeline for the last 30 days."
- **Partner lookup:** "Who at AWS have we worked with for acme.com before?"
- **Share with a partner company:** "Share the Acme deal with Contoso as a Fours co-sell referral."
- **Respond to a partner:** "Accept the referral Contoso shared with us."

## Recommended workflow

1. **Validate before you create.** Ask the assistant to run `ValidateReferral` first — each cloud
   partner requires different fields, and a dry run surfaces missing values before anything is sent.
   This step applies to **AWS, GCP and Azure** only; `partner=SUGER` is rejected by validation, so
   go straight to `CreateCosellReferral` for a partner-to-partner referral.
2. **Create the referral.** On a successful create the referral is submitted to the partner
   automatically; its status becomes `PENDING_CREATE` (or `CREATE_FAILED` if the partner API
   rejects it — to retry, fetch it with `GetCosellReferral`, fix the fields, and call
   `CreateCosellReferral` again with the same `id`). If your organization has the co-sell approval
   process enabled, a brand-new referral is instead saved as `DRAFT` and is not submitted until it
   is approved in the Fours Console.
3. **Track and update.** Use `ListCosellReferrals` / `GetCosellReferral` to check progress, and
   `UpdateCosellReferral` to edit fields or move status / stage.
4. **Sync when needed.** For AWS / Azure / GCP, `UpdateCosellReferral` changes Fours only; call
   `SyncSingleReferral` afterwards to push the change to the cloud partner or pull the latest
   partner state. A `SUGER` referral needs no such call — Fours propagates the partner's copy
   itself, and `SyncSingleReferral` there syncs the linked CRM record instead.

## Security & scope

- **Authentication:** OAuth 2.1 only (API keys and static tokens are not supported for MCP).
- **Organization scoping:** every tool call is scoped to your authenticated organization — there is
  no way to reach another organization's referrals.
- **Permissions:** the MCP server respects your existing Fours co-sell permissions
  (read / create / edit). It never grants access broader than your account already has.

## Troubleshooting

| Issue | Possible cause | Resolution |
|-------|----------------|------------|
| Referral stuck in `CREATE_FAILED` | The partner API rejected one or more required fields | Fetch it with `GetCosellReferral`, fix the fields, and call `CreateCosellReferral` again with the same `id` — Fours resubmits that referral in place. Without the `id` you get a second referral. Run `ValidateReferral` first next time to catch this before creating. |
| `UpdateCosellReferral` is refused on an AWS referral in `CREATE_FAILED` | AWS never accepted a referral whose create failed, so it can only be resubmitted, not edited | Fetch it with `GetCosellReferral` and call `CreateCosellReferral` again with the same `id`. |
| Referral saved as `DRAFT` instead of submitting | Your organization has the co-sell approval process enabled | Approve the referral in the Fours Console — it will not submit automatically. |
| Changes aren't showing up on the cloud partner's side | `UpdateCosellReferral` only changes the record in Fours | Call `SyncSingleReferral` afterwards to push the change out or pull the latest partner state. Not needed for `SUGER` referrals — Fours propagates those itself. |
| `SyncSingleReferral` fails on a `SUGER` referral with `direction=INBOUND` | On a `SUGER` referral this tool syncs the linked CRM record, which is outbound-only | Call it with `direction=OUTBOUND`, or skip it — the partner's copy is already in step. |
| Declining a `SUGER` referral is rejected | `declineReason` is required when setting `status` to `REJECTED` | Supply a reason, e.g. "Decline referral ref-abc123 because the budget was cut." |
| `ValidateReferral` errors on a `SUGER` referral | Validation supports AWS, GCP and Azure only | Skip the dry run and call `CreateCosellReferral` directly for `partner=SUGER`. |
| Validation warns about a duplicate open referral | The partner already has a still-open referral matching this one | Advisory only. Check whether it really is a duplicate, then create anyway if the new referral is distinct. |
| Can't delete a referral or bulk-sync the whole org from chat | Destructive and org-wide operations are intentionally excluded from MCP tools | Use the Fours Console for deletes, bulk-sync, or auto-share. |
| Can't submit a funding application from chat | Co-sell funding is not available as an MCP tool | Use the Fours Console or API — see [Co-Sell Funding](/cosell/cosell-funding). |

## FAQ

**Can I manage co-sell funding requests through MCP?**
No — funding applications are managed in the Fours Console and API only. See
[Co-Sell Funding](/cosell/cosell-funding).

**Can my AI assistant delete a referral or sync my whole organization at once?**
No. Destructive and org-wide operations are intentionally excluded from MCP tools. Use the Fours
Console for these.

**What happens right after I create a referral?**
It submits to the cloud partner automatically and its status becomes `PENDING_CREATE` (or
`CREATE_FAILED` if the partner rejects it — fetch it with `GetCosellReferral`, fix the fields, and
call `CreateCosellReferral` again with the same `id`). If your organization has
co-sell approval enabled, it is saved as `DRAFT` until approved in the Console instead.

**Does updating a referral in chat also update it with the cloud partner?**
Not automatically. `UpdateCosellReferral` only changes the Fours record — call `SyncSingleReferral`
afterwards to push the change to the partner. This applies to AWS, Azure and GCP; a `SUGER`
referral has no external partner system, and Fours keeps the partner's copy in step itself.

**Can I share a deal with another Fours partner company, not a cloud provider?**
Yes — create the referral with `partner=SUGER` and the partnership's `partnerId`. The partner
receives their own copy and accepts or declines it in Fours. See
[Fours peer-to-peer referrals](#fours-peer-to-peer-referrals-partnersuger) above.

For the developer view of the same create endpoint, see
[Create a Referral via API](/cosell/cosell-referral-api).