# Vergio MCP reference

Connect Claude, Cursor, or Codex to your Vergio workspace. Endpoint: `https://vergio.ai/api/mcp`. Claude connector OAuth uses role-derived access; other clients can send a scoped Bearer key created under **Integrations > API & MCP**.

## Tools

### list_in_market_accounts

This week's surfaced in-market accounts for your agency, each with the evidence (score reasoning + top signals) behind it. Call this to see who to reach out to now.

Availability: **Unavailable**

| Input | Type | Required |
| --- | --- | --- |
| `icp_profile` | string | no |

### search_accounts

Search your scored accounts. Filter by minimum In-Market score (0-100), tier, or status; results are cursor-paginated (pass the returned next_cursor to page).

| Input | Type | Required |
| --- | --- | --- |
| `min_score` | number | no |
| `tier` | string | no |
| `status` | string | no |
| `icp_profile` | string | no |
| `limit` | number | no |
| `cursor` | string | no |

### get_account_evidence

Full detail for one account: its In-Market / Fit / Intent / Opportunity scores, the plain-English reasoning, and its signal timeline. Pass the storeId from a list/search result.

| Input | Type | Required |
| --- | --- | --- |
| `store_id` | string | yes |

### get_account_signals

The signal history for one account (optionally since a date). Use it to understand what changed and when.

| Input | Type | Required |
| --- | --- | --- |
| `store_id` | string | yes |
| `since` | string | no |

### record_outcome

Report what happened after you reached out to an account. Call this when you know the result (discovery, qualifying, proposal, negotiation, won, lost) — it becomes a learning label that improves everyone's rankings. Requires the write:outcomes scope.

| Input | Type | Required |
| --- | --- | --- |
| `store_id` | string | yes |
| `action` | "discovery" | "qualifying" | "proposal" | "negotiation" | "won" | "lost" | yes |
| `value` | number | no |
| `note` | string | no |
| `event_id` | string | no |
| `lost_reason` | "no_response" | "timing" | "budget" | "chose_another_agency" | "project_cancelled" | "not_a_fit" | "other" | no |
| `lost_reason_other` | string | no |

### list_cadences

Your workspace's active outreach cadences, each with its id, name, step count, and whether it includes a Growth Report. Use a cadence id with enroll_in_cadence. Available only during an approved Outreach Studio pilot.

Availability: **Pilot**

### enroll_in_cadence

Enroll a store into an active cadence after recipient email permission was confirmed on the contact record. Published or verified addresses alone are not permission. Pass cadence_id and store_id; contact_id is optional. Sends use the key creator's connected Google mailbox. Requires write:outreach.

Availability: **Pilot**

| Input | Type | Required |
| --- | --- | --- |
| `cadence_id` | string | yes |
| `store_id` | string | yes |
| `contact_id` | string | no |

### stop_enrollment

Stop a live enrollment so no further emails are sent to it. Pass the enrollment_id (from list results). Requires the write:outreach scope.

Availability: **Pilot**

| Input | Type | Required |
| --- | --- | --- |
| `enrollment_id` | string | yes |

### get_outreach_stats

Your outreach summary: active enrollments, emails sent this week, replies this week, and the reply rate (shown only after 10 sends). Available only during an approved Outreach Studio pilot.

Availability: **Pilot**

### list_deals

Your pipeline deals, newest first. Filter by store_id or stage (discovery|qualifying|proposal|negotiation|won|lost); cursor-paginated (pass the returned next_cursor). Use a deal's id with update_deal / move_deal_stage.

| Input | Type | Required |
| --- | --- | --- |
| `store_id` | string | no |
| `stage` | "discovery" | "qualifying" | "proposal" | "negotiation" | "won" | "lost" | no |
| `limit` | number | no |
| `cursor` | string | no |

### create_deal

Open a new deal on an account. Pass store_id and a name; value, stage, next_step, next_step_due are optional. If the account isn't saved yet it is added to your pipeline as a prospect automatically. Requires the write:deals scope.

| Input | Type | Required |
| --- | --- | --- |
| `store_id` | string | yes |
| `name` | string | yes |
| `value` | number | no |
| `stage` | "discovery" | "qualifying" | "proposal" | "negotiation" | "won" | "lost" | no |
| `next_step` | string | no |
| `next_step_due` | string | no |

### update_deal

Edit a deal by id: name, value, stage, next_step, next_step_due, owner_user_id, or archive it. Moving stage to 'lost' requires a lost_reason. The version is managed for you. Requires the write:deals scope.

| Input | Type | Required |
| --- | --- | --- |
| `deal_id` | string | yes |
| `name` | string | no |
| `value` | number | null | no |
| `stage` | "discovery" | "qualifying" | "proposal" | "negotiation" | "won" | "lost" | no |
| `next_step` | string | null | no |
| `next_step_due` | string | null | no |
| `owner_user_id` | string | null | no |
| `lost_reason` | any | no |
| `lost_reason_other` | string | null | no |
| `archived` | boolean | no |

### move_deal_stage

Move a deal to a stage (discovery|qualifying|proposal|negotiation|won|lost). 'won' marks the account a customer; 'lost' needs a lost_reason (no_response|timing|budget|chose_another_agency|project_cancelled|not_a_fit|other). Requires the write:deals scope.

| Input | Type | Required |
| --- | --- | --- |
| `deal_id` | string | yes |
| `stage` | "discovery" | "qualifying" | "proposal" | "negotiation" | "won" | "lost" | yes |
| `value` | number | no |
| `lost_reason` | "no_response" | "timing" | "budget" | "chose_another_agency" | "project_cancelled" | "not_a_fit" | "other" | no |
| `lost_reason_other` | string | no |

### list_contacts

The contacts on file for one account. Pass the store_id. Use a contact's id with update_contact.

| Input | Type | Required |
| --- | --- | --- |
| `store_id` | string | yes |

### create_contact

Add a contact to an account. Email permission defaults to unknown. Set email_permission_status=confirmed only when the recipient gave permission, with its source and date; published or verified addresses are not permission. Requires write:contacts.

| Input | Type | Required |
| --- | --- | --- |
| `store_id` | string | yes |
| `first_name` | string | no |
| `last_name` | string | no |
| `name` | string | no |
| `role` | string | no |
| `email` | string | no |
| `email_permission_status` | "unknown" | "confirmed" | "withdrawn" | no |
| `email_permission_source` | "direct_request" | "website_form" | "event" | "existing_relationship" | "imported_consent" | "other" | no |
| `email_permission_confirmed_at` | string | no |
| `email_permission_note` | string | no |

### update_contact

Edit a contact by id. Permission confirmation requires the recipient's actual permission source and date; withdrawal permanently suppresses the address. Requires write:contacts.

| Input | Type | Required |
| --- | --- | --- |
| `contact_id` | string | yes |
| `first_name` | string | no |
| `last_name` | string | no |
| `role` | string | null | no |
| `email` | string | null | no |
| `email_permission_status` | "unknown" | "confirmed" | "withdrawn" | no |
| `email_permission_source` | "direct_request" | "website_form" | "event" | "existing_relationship" | "imported_consent" | "other" | no |
| `email_permission_confirmed_at` | string | no |
| `email_permission_note` | string | no |

### find_contacts

Discover published contact emails on a merchant's own website and save any new ones to the account. Pass the store_id. Requires the write:contacts scope.

| Input | Type | Required |
| --- | --- | --- |
| `store_id` | string | yes |

### add_deal_note

Write a note to a deal's activity timeline. Pass deal_id and text. Requires the write:deals scope.

| Input | Type | Required |
| --- | --- | --- |
| `deal_id` | string | yes |
| `text` | string | yes |

### set_account_status

Set an account's relationship status: prospect | customer | churned | not_a_fit. Requires the write:deals scope.

| Input | Type | Required |
| --- | --- | --- |
| `store_id` | string | yes |
| `status` | "prospect" | "customer" | "churned" | "not_a_fit" | yes |

### request_report

Request an asynchronous white-label Growth Report for an account. Pass the store_id. Requires generate:reports; current availability is published separately from this compatibility contract.

Availability: **Unavailable**

| Input | Type | Required |
| --- | --- | --- |
| `store_id` | string | yes |

### get_pipeline_summary

Your pipeline at a glance: open deals, overdue, deals missing a next step, one-off value, and MRR by currency.

### list_webhooks

Your registered webhook endpoints and the event types available to subscribe to.

### create_webhook

Register an https endpoint to receive signed events (deal.created, deal.updated, deal.stage_changed, contact.created, store.entered, store.exited, store.signal, watch.health_changed). Omit event_types to receive all. The signing secret is returned once. Requires the manage:webhooks scope.

| Input | Type | Required |
| --- | --- | --- |
| `url` | string | yes |
| `event_types` | array | no |

### delete_webhook

Remove a webhook endpoint by id. Requires the manage:webhooks scope.

| Input | Type | Required |
| --- | --- | --- |
| `endpoint_id` | string | yes |

### read_managed_watch

Read your workspace's managed-watch capacity, evidence coverage, cadence, health, and cancellation contract. Requires read:watch.

### read_watch_health

Read honest managed-watch source health overall and per source lane. Requires read:watch.

### resize_managed_watch

Set managed-watch capacity to an integer from 0 through 1000 slots. Requires write:watch.

| Input | Type | Required |
| --- | --- | --- |
| `slots` | integer | yes |

### cancel_managed_watch

Permanently cancel future managed monitoring without rewriting historical activity. Requires write:watch.

### read_self_directed_watches

Read the explicit stores your workspace watches and their monthly expected spend. Requires read:watch.

### add_self_directed_watches

Add up to 200 explicit, known store UUIDs and return the spend delta. Requires write:watch.

| Input | Type | Required |
| --- | --- | --- |
| `store_ids` | array | yes |

### remove_self_directed_watches

Remove up to 200 explicit, known store UUIDs and return the spend delta. Requires write:watch.

| Input | Type | Required |
| --- | --- | --- |
| `store_ids` | array | yes |

### get_client_watches

Read the client portfolio, health, and suggestions for this workspace. Requires read:watch.

| Input | Type | Required |
| --- | --- | --- |
| `suggestion_limit` | integer | no |
| `suggestion_cursor` | string | no |

### get_client_watch_brief

Read one stored monthly client brief or a stored range of at most 12 periods. Requires read:watch.

| Input | Type | Required |
| --- | --- | --- |
| `store_id` | string | yes |
| `period` | string | no |
| `from` | string | no |
| `to` | string | no |

### add_client_watches

Add up to 200 client watches. This changes monthly spend and requires write:watch.

| Input | Type | Required |
| --- | --- | --- |
| `stores` | array | yes |
| `preview` | boolean | no |

### remove_client_watches

Cancel client monitoring or durably decline a client suggestion. Requires write:watch.

| Input | Type | Required |
| --- | --- | --- |
| `store_ids` | array | yes |
| `mode` | "cancel" | "decline" | no |

### get_balance

Read your workspace wallet's paid, promotional, held, and available USD balances. Requires read:wallet.

Availability: **Activation-gated**

### get_usage

Read bounded wallet usage grouped by catalog item, budget subject, entry type, or day. Requires read:wallet.

Availability: **Activation-gated**

| Input | Type | Required |
| --- | --- | --- |
| `from` | string | yes |
| `to` | string | yes |
| `dimension` | "catalog_item" | "budget_subject" | "entry_type" | "day" | yes |
| `cursor` | string | no |
| `limit` | integer | no |

### inspect_prices

Inspect active, versioned USD wallet catalog items. Requires read:wallet.

Availability: **Activation-gated**

### get_watch_contract

Read your workspace managed-watch capacity, coverage, cadence, status, cancellation semantics, and source health. Requires read:watch.

Availability: **Activation-gated**

### list_watch_events

Read a bounded, cursor-paginated watch event projection with lifecycle state and explicit source completeness. Requires read:watch.

Availability: **Activation-gated**

| Input | Type | Required |
| --- | --- | --- |
| `as_of` | string | no |
| `cursor` | string | no |
| `limit` | integer | no |

### get_watch_receipt

Read a watch truth receipt with activity silence and source health exposed as separate fields. Requires read:watch.

Availability: **Activation-gated**

| Input | Type | Required |
| --- | --- | --- |
| `since` | string | no |

### get_runway

Forecast expected and maximum monthly watch spend, funded runway, and what pauses first. Requires read:wallet.

Availability: **Activation-gated**

### get_tool_receipt

Poll a Growth Report job and its related reserve, capture, and release action receipts. Requires read:accounts or generate:reports.

Availability: **Activation-gated**

| Input | Type | Required |
| --- | --- | --- |
| `job_id` | string | yes |

### list_approvals

Read a bounded page of supervision approvals. Defaults to pending and requires read:wallet.

Availability: **Activation-gated**

| Input | Type | Required |
| --- | --- | --- |
| `status` | "pending" | "approved" | "declined" | "expired" | "superseded" | "execution_failed" | no |
| `cursor` | string | no |
| `limit` | integer | no |

### list_standing_rules

Read a bounded page of active and revoked standing rules, including stored spend snapshots. Requires read:wallet.

Availability: **Activation-gated**

| Input | Type | Required |
| --- | --- | --- |
| `cursor` | string | no |
| `limit` | integer | no |