# Co-Sell with AI (MCP)

Run the full co-sell referral lifecycle from your AI assistant, in plain language.

---

## Overview

The [Fours MCP Server](/mcp/overview/) exposes Fours' co-sell APIs as tools. Any
[Model Context Protocol](https://modelcontextprotocol.io/) client can call them: Claude Desktop,
Claude Code, Cursor, VS Code (GitHub Copilot), Devin Desktop (formerly Windsurf) and ChatGPT. A
Partner or Alliance Manager describes what they want, and the assistant creates referrals, looks up
status, syncs with the cloud partner and reads dashboard insights.

One connection covers **AWS, Azure and GCP** co-sell. It also covers peer-to-peer co-sell with the
companies you partner with through Fours. The `partner` field picks the destination on each call.
`AWS`, `AZURE` and `GCP` share the opportunity with that cloud provider. `SUGER` shares it with
another company you partner with through Fours.

**Availability:** All Fours pricing plans

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

To connect your client, see [MCP › Setup](/mcp/setup/). For the security model, see
[MCP › Overview](/mcp/overview/).

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

## What you can do

The MCP server has 28 co-sell tools. For each tool's parameters and behavior, see the
[Co-Sell group in MCP › Supported Tools](/mcp/tools/#co-sell-28). In plain terms, an assistant can:

- **Work referrals.** List, read, create, update and sync referrals with AWS, Azure and GCP. It can
  create several at once, or preview the referrals your CRM records would become.
- **Check before sending.** Validate a referral against the cloud partner's rules, and predict its
  AWS quality score.
- **Propose changes for a person to approve.** On AWS referrals, it can stage an update for your
  team to approve or reject. It cannot approve its own proposal.
- **Share with partner companies.** Share a deal with a company you partner with through Fours,
  respond to deals partners share with you, and handle commissions once a deal is Won.
- **Log deals for review.** Record a deal a partner raised as a draft for your team to review.
- **Work AWS leads.** List and read your AWS Partner Central leads, and accept pending invitations.
- **Read insights.** Pull pipeline KPIs and outstanding actions, look up partner contacts, and ask
  AWS which funding programs a referral qualifies for.

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

## 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 or 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."
- **Log a partner's deal for review:** "Record the deal Contoso raised in this Slack thread as a deal-registration draft."
- **Leads:** "List my AWS lead invitations that are still pending, and accept the one from Acme Corp."
- **Funding fit:** "Which AWS funding programs does referral `ref-abc123` qualify for?"

## Recommended workflow

1. **Validate before you create.** Ask the assistant to run `ValidateReferral` first. Each cloud
   partner requires different fields, and a dry run shows missing values before anything is sent.
   If the same partner already has an open referral that matches, validation warns you. The warning
   does not block the create. Validation covers AWS, GCP and Azure only. For a `SUGER` referral, go
   straight to `CreateCosellReferral`.
2. **Create the referral.** A successful create submits the referral to the partner, and its status
   becomes `PENDING_CREATE`. If the partner API rejects it, the status is `CREATE_FAILED`. 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 on, a new referral is saved as
   `DRAFT` instead. It is not submitted until someone approves it in the Fours Console.
3. **Track and update.** Use `ListCosellReferrals` and `GetCosellReferral` to check progress. Use
   `UpdateCosellReferral` to edit fields or move the status or stage.
4. **Let updates push themselves.** For AWS, Azure and GCP, a successful `UpdateCosellReferral`
   starts the outbound sync by itself. Don't call `SyncSingleReferral` afterwards. Two kinds of
   update are saved but not sent:
   - With the co-sell approval process on, an update to a referral that isn't approved or submitted
     yet stays a `DRAFT` until it is approved in the Fours Console.
   - An update to an AWS referral at `Launched` or `Closed Lost` stays in Fours.

   Use `SyncSingleReferral` to pull the latest partner state. A `SUGER` referral needs no sync:
   Fours keeps the partner's copy in step itself.

## Propose changes for approval

`ProposeCosellReferralUpdate` lets an assistant suggest an edit to an AWS referral without making
it. A person on your team approves or rejects the proposal on the referral page. Approving is not an
MCP tool, so an assistant cannot approve its own proposal.

Fours refuses a proposal that would close the referral, blank a field, name another cloud, or
include contact details or pricing. It also refuses one when someone edited the linked CRM record in
the last 24 hours. For the full list of rules, see
[Proposing a referral update](/mcp/tools/#proposing-a-referral-update).

## AWS leads

`ListLeads`, `GetLead` and `AcceptLead` work the AWS Partner Central [leads](/cosell/aws-programs/leads/)
in your Fours lead list. `AcceptLead` accepts an invitation that is still `PENDING`, and records the
acceptance with AWS. Accepting doesn't qualify the lead, convert it into an opportunity, or send
anything to the customer. Rejecting, qualifying, editing and converting a lead are not MCP tools. Do
them in the Fours Console.

## Ask about funding

`GetReferralFundingRecommendation` asks AWS Partner Central which funding programs an AWS referral
qualifies for. It returns the overview behind the **Funding Insights** card on a referral (see
[Co-Sell Insights](/cosell/ai/insights/)). The referral must already be synced to ACE, and you
need the [AWS Partner Central (ACE) integration](/integrations/aws-partner-network-api/).

- **The answer is AWS's.** It says plainly when no program fits, and what to do next.
- **Amounts are estimates.** They are eligibility assessments, not approvals. To request the money,
  file a funding application. See [AWS Funding](/cosell/aws-programs/funding/).
- **A slow answer comes back as pending.** If AWS hasn't answered within about 25 seconds, ask again
  in about a minute.

```d2
shape: sequence_diagram
assistant: "AI assistant"
fours: "Fours MCP server"
aws: "AWS Partner Central"
assistant -> fours: "GetReferralFundingRecommendation"
fours -> aws: "Funding overview for the referral's ACE opportunity"
answered: "AWS answers within about 25 seconds" {
  aws -> fours: "Assessment and funding cards" { style.stroke-dash: 4 }
  fours -> assistant: "Answer, plus availableCards" { style.stroke-dash: 4 }
}
slow: "AWS takes longer" {
  fours -> assistant: "pending: true" { style.stroke-dash: 4 }
  assistant -> fours: "Same call, about a minute later"
  fours -> assistant: "The answer, or AWS's error" { style.stroke-dash: 4 }
}
```

An assistant can also prepare an AWS funding application. It can prefill one from a CRM
opportunity, run Fours' pre-submission checks, and save it as a draft for a person to review.
`SubmitFundingApplication` sends a draft to AWS Partner Central only after that person approves it.
See the [Funding group in MCP › Supported Tools](/mcp/tools/#funding-8).

## 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. Use `ListPrmPartners` to find the partner and get the `partnerId` the referral needs.

It behaves differently from a cloud referral in four ways:

- **The partner responds in Fours.** The recipient gets their own copy in `PENDING_ACCEPTANCE`. They
  accept by moving it to `ACTIVE`. They decline by setting `status` to `REJECTED` with a
  `declineReason`, which is required. 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 system to push to. `SyncSingleReferral` on a
  `SUGER` referral syncs the linked CRM record. It accepts `direction=OUTBOUND` only.
- **Send only the fields you are changing.** On a partner's copy with a hidden deal value, a read
  returns `dealValueAmount`, `dealValueCurrency` and `sharePercentage` blank. Sending the whole
  record back writes those blanks or fails validation. Ask the assistant to patch specific fields
  instead.
- **Won needs an accepted co-sell.** A `SUGER` co-sell can move to `Won` only once its status is
  `ACTIVE`. Before that, the update is refused with
  `cannot close as Won from status "…"; the co-sell must be Active (accepted) first`.

### Who receives the referral

To send the referral to a person at the partner, set `recipientMode` to `CONTACT` in
`info.sugerOpportunity`. Sending `partnerTeam` means the same thing.

- Fours puts the partnership's partner champion first. The champion owns the referral on the
  partner's side. The champion and everyone else on the partner's team each get the share email.
- A partnership with no champion is refused, so set one first.
- In `partnerTeam`, list only the other people at the partner to add to the co-sell. Each is one of
  that partner's contacts (list them with `GetPrmPartnerContacts` and `scope=all`) or someone new.
  Someone new needs a `name` and a company email address that isn't on your own domain.

For a partner with nobody on file, set `recipientMode` to `ADMINS`. Leaving out both fields works
the same way. The partner's copy then has no deal team until the partner accepts and names an owner.
So the share email reaches only the people the partner set to receive co-sell emails in its
[email notification settings](/settings/email-notification/#partners). If it set none, nobody gets
it. Later emails about that copy, such as a close or an update, aren't sent to the partner.

`RegisterCosellOnBehalf` always asks the partnership's champion to confirm the deal. So it refuses
`recipientMode` `ADMINS`, and it needs a champion to be set.

Once the partner accepts, each side's team members who aren't already in the other side's partner
contacts are added there. See [Contacts](/prm/work-a-partner-record/#contacts). Existing or removed
contacts are left as they are. Nobody is invited, and nothing is pushed to a CRM.

### Commission tools

On a `SUGER` co-sell, these tools handle the partner's share of the deal:

- `UpdateCosellPartner` lets a Seller change one partner's revenue-share terms before Close Won, its
  deal-value visibility, and collaboration fields.
- `ProposeCommissionUpdate` lets a Seller propose new commission terms after Close Won. The partner
  must approve.
- `UpdateCommissionLifecycle` moves a commission to its next state once the deal is Won: approved,
  payment sent, confirmed, or clawed back.

For the allowed state changes, see [Commission states](/mcp/tools/#commission-states).

### Deal-registration drafts

Four tools work the review queue of deal registrations that haven't been confirmed yet. It is the
same queue your team reviews in the Fours Console under
[Partner Co-Sells](/prm/track-and-respond-to-deals/). Ask the assistant to log a deal a partner
raised, and it calls `CreateDealRegistrationDraft`.

A draft registers nothing and shares nothing. Someone on your team confirms or discards it in the
console. Use drafts rather than `CreateCosellReferral` or `RegisterCosellOnBehalf`, which register
the deal straight away without review. Each draft lists the facts still missing, so the assistant
knows what to ask the partner for.

## What isn't available over MCP

Some operations are deliberately not MCP tools. Do them in the Fours Console:

- Deleting a referral.
- Bulk-syncing a whole organization.
- Auto-share.
- System configuration.
- Approving or rejecting a proposed referral update.
- Confirming or discarding a deal-registration draft.
- Rejecting, qualifying, editing or converting an AWS lead.

## 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. |
| `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 on | Approve the referral in the Fours Console. It will not submit automatically. |
| Changes aren't showing up on the cloud partner's side | The update is waiting for approval, or the AWS referral is already `Launched` or `Closed Lost` | Approve the referral in the Fours Console. Otherwise the outbound sync starts on its own after `UpdateCosellReferral`. Don't call `SyncSingleReferral` to push it. |
| `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, for example "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. |
| Validation warns about a duplicate open referral | The partner already has an open referral matching this one | The warning is advisory. 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 | These operations are deliberately not MCP tools | Use the Fours Console. |
| A funding application won't submit from chat | The draft still has missing or invalid fields, or it isn't an unsent draft any more: it was already sent to AWS, declined by an approver, or submitted once | Have the assistant run `ValidateFundingApplicationPayload` and fix each field it lists. Then submit a draft a person has approved. See [AWS Funding](/cosell/aws-programs/funding/). |
| `GetReferralFundingRecommendation` returns `pending` with no content | AWS hadn't answered within about 25 seconds | Ask again in about a minute. |
| `GetReferralFundingRecommendation` is refused | The referral isn't an AWS referral or hasn't synced to ACE, there is no AWS Partner Central (ACE) integration, or the `triggerId` isn't one the deal is offered | Use an AWS referral with an ACE opportunity ID, connect the [AWS Partner Central (ACE) integration](/integrations/aws-partner-network-api/), and omit `triggerId` or pass one from `availableCards`. |
| `AcceptLead` is refused with the lead's status | The invitation isn't `PENDING` any more | Nothing to do if it is `ACCEPTED`. A rejected or expired invitation can't be accepted. |

## FAQ

**Can I manage co-sell funding requests through MCP?**
Yes, for AWS funding. An assistant can prefill a funding application from a CRM opportunity, check
it, and save it as a draft. Once a person approves the draft, the assistant can submit it to AWS
Partner Central. It can also read your AWS benefit wallets with `ListFundingBenefits`. See
[AWS Funding](/cosell/aws-programs/funding/).

**Can my AI assistant delete a referral or sync my whole organization at once?**
No. See [What isn't available over MCP](#what-isnt-available-over-mcp).

**What happens right after I create a referral?**
It submits to the cloud partner, and its status becomes `PENDING_CREATE`. If the partner rejects it,
the status is `CREATE_FAILED`. If your organization has co-sell approval on, it is saved as `DRAFT`
until someone approves it in the Console.

**Does updating a referral in chat also update it with the cloud partner?**
Yes, for AWS, Azure and GCP. A successful `UpdateCosellReferral` starts the outbound sync on its own.
The exceptions are an update waiting for approval, and an update to an AWS referral at `Launched` or
`Closed Lost`.

**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 gets
their own copy and accepts or declines it in Fours. See
[Fours peer-to-peer referrals](#fours-peer-to-peer-referrals-partnersuger).

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