# Co-Sell with AI (MCP)

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

---

## Overview

The [Suger MCP Server](/mcp/overview) exposes Suger's 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
Suger 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 Suger. 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 Suger.

**Availability:** All Suger 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 13 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) |
| `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) |
| `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 |

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

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

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

- **The partner responds in Suger.** 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 — Suger 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.

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

:::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 Suger
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 Suger 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.
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 — fix the fields and re-create). 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 Suger 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 Suger 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 — Suger 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 Suger 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 | Fix the fields and re-create. Run `ValidateReferral` first next time to catch this before creating. |
| Referral saved as `DRAFT` instead of submitting | Your organization has the co-sell approval process enabled | Approve the referral in the Suger Console — it will not submit automatically. |
| Changes aren't showing up on the cloud partner's side | `UpdateCosellReferral` only changes the record in Suger | Call `SyncSingleReferral` afterwards to push the change out or pull the latest partner state. Not needed for `SUGER` referrals — Suger 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." |
| 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 Suger 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 Suger 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 Suger 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 Suger
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 — fix the fields and re-create). 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 Suger 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 Suger keeps the partner's copy in step itself.

**Can I share a deal with another Suger 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 Suger. See
[Suger peer-to-peer referrals](#suger-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).