Co-Sell with AI (MCP)

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

Overview

The Fours MCP Server exposes Fours’ co-sell APIs as tools that any Model Context Protocol client — Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Devin Desktop (formerly 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 to connect your client, and 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.

Co-Sell tools

The MCP server exposes 28 co-sell tools, covering the whole referral lifecycle, deal-registration drafts and your AWS leads:

The descriptions above are deliberately short. For each tool’s full parameter list and response shape, see MCP → Supported Tools.

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.

What ProposeCosellReferralUpdate does

ProposeCosellReferralUpdate works on AWS referrals only; any other referral is reported as not found. It stages a proposed change for a person on your team to approve or reject, and never changes the referral itself. A new proposal replaces one that is still waiting. Approving or rejecting a proposal is not an MCP tool, so an assistant cannot approve its own proposal.

The proposal is refused with a 400, and nothing is stored, when:

• the referral isn’t open — its status must be ACTIVE, IN_REVIEW, ACTION_REQUIRED or UPDATE_FAILED, at a stage that doesn’t end the deal — or the change would close it, for example by moving it to Launched or Closed Lost;
• the change would blank a field that has a value;
• the new text names another cloud, or contains an email address, a phone number, or pricing or discount terms;
• the referral is linked to a Salesforce opportunity that someone edited in the last 24 hours (edits by Fours’ own Salesforce sync don’t count), or Fours can’t read that opportunity to check.

AWS leads

ListLeads, GetLead and AcceptLead work the AWS Partner Central leads in your Fours lead list. AcceptLead accepts an invitation that is still PENDING and starts the sync that records the acceptance with AWS. Any other invitation status is refused with a 400 that names it, so an assistant can tell a lead that is already ACCEPTED from a failure. Accepting doesn’t qualify the lead or convert it into an opportunity, and sends nothing to the customer. Rejecting, qualifying, editing and converting a lead are not MCP tools: do them in the Fours Console.

What GetReferralFundingRecommendation returns

GetReferralFundingRecommendation asks AWS Partner Central for the funding overview behind the Funding Insights card on a referral (see Co-Sell Insights). It works on an AWS referral that has already synced to ACE, and needs your AWS Partner Central (ACE) integration; otherwise the call is refused with an error that says which.

• The answer is AWS’s. It says plainly when no funding program fits and what to do next, and it lists the other funding cards the deal qualifies for. Those are listed, not run: ask for one by passing its triggerId.
• Amounts are estimates. Figures in the answer are eligibility assessments, not approvals. Requesting the money is a separate funding application — see AWS Funding.
• A slow answer comes back as pending. When AWS hasn’t answered within about 25 seconds, the result has pending set and no content. Ask again in about a minute: that call returns the answer, or the error if AWS failed.
• Answers are kept for 48 hours. Fours keeps each answer for you for 48 hours, so asking for the same card on the same referral again in that time doesn’t wait on AWS.

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) to find the partner and get the partnerId a SUGER referral needs.

To send the referral to a person at the partner, set recipientMode to CONTACT in info.sugerOpportunity — or just send partnerTeam, which means the same. Fours puts the partnership’s partner champion first: the champion owns the referral on the partner’s side, and 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 put on the co-sell: each is one of that partner’s contacts (list them with GetPrmPartnerContacts and scope=all) or someone new, who 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 instead; leaving out both works the same way. Either way, the partner’s copy has no deal team until the partner accepts and names an owner, so the share email reaches only the people the partner’s organization has set to receive co-sell emails in its email notification settings — nobody, if it has set none — and the 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 needs a champion to be set.

Once the partner accepts, the people on each side’s team who aren’t already in the other side’s partner contacts are added there — see Contacts. Existing or removed contacts are left as they are, nobody is invited, and nothing is pushed to a CRM.

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:

Any other pair is refused with INVALID_TRANSITION.

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.

Deal-registration drafts

Four tools work the review queue of deal registrations that haven’t been confirmed yet — the same drafts your team reviews in the Fours Console under Partner Co-Sells. A draft is a SUGER co-sell in DRAFT status. Nothing is registered or shared until someone on your team confirms it in the console, and confirming or discarding a draft is not an MCP tool.

• Create, don’t register. Ask the assistant to log a deal a partner raised — in conversation or from notes — and it calls CreateDealRegistrationDraft. Only the deal name (or the customer’s company name) is needed to start a draft. Use it rather than CreateCosellReferral or RegisterCosellOnBehalf, which register the deal straight away without your team’s review.
• Missing facts. Each draft comes back with missingFields: what the partner can still be asked for, such as the customer’s website, industry and country, the deal value and currency, the target close date, or a business-problem description of at least 20 characters. An empty list means there is nothing left to ask the partner, not that the draft is ready to confirm — your team still sets the deal type, delivery model and collaboration context in the console.
• Updates replace whole sections. UpdateDealRegistrationDraft replaces the draft’s customer information and deal details as a whole, so read the draft first and send back every field you want to keep.

Drafts don’t appear in ListCosellReferrals or the co-sell dashboard until they are confirmed.

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.”
• 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 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. Let updates push themselves. For AWS / Azure / GCP, a successful UpdateCosellReferral starts the outbound sync to the cloud partner by itself — don’t call SyncSingleReferral afterwards. Two updates 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, and 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 either — 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

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. An assistant can read your AWS benefit wallets with ListFundingBenefits and ask which programs an AWS referral qualifies for with GetReferralFundingRecommendation, but requesting the money is a funding application.

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? Yes, for AWS, Azure and GCP. A successful UpdateCosellReferral starts the outbound sync on its own, so don’t call SyncSingleReferral afterwards. The exceptions: an update saved as a DRAFT under the co-sell approval process waits for approval in the Console, and an update to an AWS referral at Launched or Closed Lost stays in Fours. 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 above.

For the developer view of the same create endpoint, see Create a Referral via API.