# Connect your AI

Connect Claude, ChatGPT, Claude Code or any MCP host to your Victoria AI workspace, and what a connected assistant can and can't do.

Victoria AI runs an [MCP](https://modelcontextprotocol.io) server at `https://api.versionseven.ai/mcp`. Connect it to an AI assistant and the assistant can create and edit campaigns, add leads, check senders, run the activation preflight and activate, with the same tools the Copilot uses inside the app. The conversation runs on the host's model and costs nothing on Victoria's side; only the two lead-finding tools spend credits.

## Connect in a minute

Most people connect from Claude or ChatGPT in the browser, and it takes three steps. No key, nothing to install.

1. **Add the connector.** In Claude: **Settings → Connectors → Add custom connector**, paste `https://api.versionseven.ai/mcp`, save. The Claude desktop app and Cowork use the same Connectors setting, so one connection covers all three. In ChatGPT: **Settings → Connectors → Create** (developer mode on), paste the same URL.
2. **Sign in and approve.** The assistant opens Victoria AI. Sign in with your Victoria account, pick your workspace if you have more than one, choose **Read and write** (it can build and launch campaigns, asking before each change) or **Read only** (it can look but never change anything or spend credits), and choose **Allow**.
3. **Ask for something.** Start a chat with the connector on and try _"Which of my campaigns got replies this week?"_ — it reads and changes nothing. From there, ask for a campaign.

That's the whole setup. The rest of this page is what the connection can do, how it asks before changing anything, and the other ways to connect.

## What a connected assistant can do

The server lists a tool when your credential holds its scope. A **Read and write** connection holds every scope, so all of these are listed; a **Read only** connection lists only the reads. To change a connection's access, disconnect it in **Settings → Connect your AI** and connect again.

- **Reads**, which have no side effects: `campaigns_list`, `campaign_detail`, `campaign_analysis`, `campaign_step_funnel`, `campaign_sender_breakdown`, `campaign_queue`, `campaign_preflight`, `personalization_quality`, `get_sequence_template`, `list_personalization_fields`, `list_webhooks`, `onboarding_checklist`, `read_website`, `leads_lookup`, `lead_detail`, `csv_upload_status`, `lead_jobs_status`, `sender_accounts`, `verify_sender`, `connect_sender`, `reconnect_sender`, `check_domain_dns` (an SPF, DKIM and DMARC check of any domain; nothing is stored), `pipelines_lookup`, `deals_lookup`, `deal_detail` and `team_members_lookup`. `connect_sender` and `reconnect_sender` answer with a link into the app and mint nothing themselves. ChatGPT's deep research gets `search` and `fetch`, which find campaigns, leads and deals by name, email or company and read one record.
- **Writes**, which the host asks you to confirm: `create_campaign`, `update_campaign`, `update_sequence`, `update_sequence_step`, `create_personalization_field`, `update_personalization_field`, `assign_sender_accounts`, `set_ab_testing`, `promote_ab_winner`, `activate_campaign`, `activate_webhook`, `deactivate_webhook`, `update_lead`, `create_deal`, `update_deal`, and `check_sender_dns`, which re-runs the SPF, DKIM and DMARC check for a connected mailbox and stores the verdict (it needs `accounts:write`).
- **Actions that spend credits**, also confirmed: `find_leads` and `add_leads_from_search`, which search the lead database and add matches to a campaign.

The inbox and the Copilot's knowledge-base tools aren't exposed. One resource, `victoria://guides/messaging-rules`, holds the sequence format and the house messaging rules; an assistant reads it before writing sequence copy.

### Scopes

An API key can be limited per family (`leads`, `campaigns`, `crm`, `accounts`) to `read` or `write`, and `:write` implies `:read`, so a key with `campaigns:read` alone lists the campaign reads and none of the campaign writes. An OAuth connection carries every scope. [Authentication](https://docs.versionseven.ai/guides/authentication#scopes) covers the scopes themselves.

### More than one organization

A connection or key acts in one organization. If you belong to more than one, choose a default on the consent screen when you connect, or later in **Settings → Connect your AI**, or ask the assistant: the `switch_organization` tool lists your organizations and moves the connection to one of them, and later calls act there. Until a default is set, every other tool refuses with `NO_DEFAULT_ORGANIZATION`.

## How the sign-in works

The three steps above are the whole procedure; this is what happens underneath. The consent page names the host asking, where you'll be sent back to, and what the connection can do; if you've already approved that host, the page sends you straight back. The connection acts as you, in your organization, with every scope. Hosts find the sign-in flow themselves: the discovery document at `https://api.versionseven.ai/.well-known/oauth-protected-resource/mcp` names Victoria AI's authorization server, and an unauthenticated request to `/mcp` answers `401` with a `WWW-Authenticate` header pointing at it. A token copied from a browser session is refused: only a token issued through this consent flow, or an API key, is accepted.

## Connect Claude Code

Claude Code signs in the same way. Add the server, then run `/mcp` inside Claude Code and choose it to complete the sign-in:

```bash
claude mcp add --transport http victoria https://api.versionseven.ai/mcp
```

Add `--scope user` to make it available in every project rather than the current one.

## Cursor and scripts

Hosts that take a URL and a header send an API key as the bearer token instead (Claude Code accepts this too, for a machine that shouldn't hold a sign-in). [Create a key](https://docs.versionseven.ai/guides/authentication#create-a-key) in **Settings → API Keys**, then:

**Claude Code**

```bash
claude mcp add --transport http victoria https://api.versionseven.ai/mcp \
  --header "Authorization: Bearer $VICTORIA_API_KEY"
```

**Cursor**

```json
{
  "mcpServers": {
    "victoria": {
      "url": "https://api.versionseven.ai/mcp",
      "headers": {
        "Authorization": "Bearer vk_your_key"
      }
    }
  }
}
```

**curl**

```bash
curl https://api.versionseven.ai/mcp \
  -H "Authorization: Bearer $VICTORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'
```

For Cursor, save the JSON as `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for every project) with your key in place of `vk_your_key`, and keep the file out of version control.

The transport is Streamable HTTP at its plainest: each request is a `POST` carrying one JSON-RPC message, answered with a JSON body rather than an event stream. The server is stateless, so there's no session to open; `tools/list` and `tools/call` are independent requests, as above.

The key's [scopes](https://docs.versionseven.ai/guides/authentication#scopes) decide which tools are listed. `find_leads`, `add_leads_from_search` and `create_deal` act as a person: with a key, that's the user who generated it or, when the key records no creator, the organization's owner.

## What it never does on its own

- **Every write is confirmed.** Each tool that changes your account is annotated as a write, which is what hosts such as claude.ai and ChatGPT use to ask you before running it.
- **Activation runs the preflight.** `activate_campaign` goes through the same readiness checks as the Activate button in the app and [`PATCH /v1/campaigns/{campaign_id}`](https://docs.versionseven.ai/api-reference/campaigns/update-campaign): sequence and step content, variables and lead data, assigned sender accounts and channel fit, sender email authentication, account conflicts and limits, enrolled leads, and the subscription. A blocking check refuses; warnings need an explicit `ack_warnings`. Campaigns are created as drafts, and nothing sends until activation.
- **It never sends a message.** No tool sends to or replies to a prospect, and the inbox isn't exposed.
- **It can't connect a sender, upload a CSV or change billing.** Those happen in the app; a result that needs one carries a `next_step` link to the right page.

## Credits

Two tools spend credits, and they quote the cost before you approve:

- `find_leads`: about 0.8 credits per result returned, so a page of 25 is about 21 credits. Short pages are refunded.
- `add_leads_from_search`: the search cost plus, in `email` mode, about 3.3 credits per lead reserved for finding an email and settled to what's found. `linkedin_only` mode costs only the search.

A credit is 1,000 tokens. Both tools are refused at a zero balance and past the trial's lead cap; `add_leads_from_search` then answers a `suggested_count` that fits. Leads added this way are personalized and worked like any other lead, which spends credits as usual.

## Where lead data comes from

Results from `find_leads` and `add_leads_from_search` are licensed from FullEnrich and are shown with the attribution "Powered by FullEnrich". Use them only for your own B2B outreach inside your workspace: they can't be exported for resale or shared outside your organization. If the GDPR applies to your outreach, tell each contact where their data came from within a month of obtaining it or at your first message, whichever is earlier. Leads you delete, and every lead in an account that closes, are purged within 90 days, including from backups. The [Terms of Service](https://www.versionseven.ai/legal/terms) and [Acceptable Use Policy](https://www.versionseven.ai/legal/aup) carry the full conditions.

## Limits and errors

Lead-database spend through connected assistants and API keys (`find_leads`, `add_leads_from_search`) is also capped per organization at 5,000 credits in any 24 hours; past it the tool answers `DAILY_SPEND_LIMIT` with what is left. The Lead Database page and the in-app Copilot are not capped.

Each signed-in user, and each API key, gets 120 tool calls a minute and 2,000 a day; connecting Claude and ChatGPT as the same user shares one allowance. Over either, the tool answers an error result with `error: "RATE_LIMITED"` and `retry_after_seconds` rather than an HTTP `429`, so the assistant can wait and retry. The [per-address limit](https://docs.versionseven.ai/guides/rate-limits) on the REST API also applies to `/mcp`, before authentication, as a real `429` with `Retry-After`.

| Status | Meaning |
| - | - |
| `401` | No credential, or one that isn't valid: a browser session token, a revoked or expired key. The `WWW-Authenticate` header names the discovery document, which is how a host starts the sign-in flow. |
| `403` | `ORGANIZATION_DEACTIVATED`, in the API's [error body](https://docs.versionseven.ai/guides/errors#the-error-body). |
| `429` | `RATE_LIMITED` for the address. Retry after `Retry-After` seconds. |
| `503` | `AUTH_UNAVAILABLE`: the credential couldn't be checked. Retry after a short wait. |

Inside a conversation, a refused call is a tool result with `success: false` and an `error` code: `INSUFFICIENT_SCOPE`, `RATE_LIMITED`, `DAILY_SPEND_LIMIT`, `NO_ACTING_USER`, `NO_DEFAULT_ORGANIZATION`, `INSUFFICIENT_TOKENS`, `UNKNOWN_TOOL`, `INTERNAL_ERROR`, or the tool's own code in the same shape, such as `CAMPAIGN_NOT_READY` from `activate_campaign`.

## Revoking access

- An OAuth connection is removed from your assistant's connector settings.
- An API key is revoked in **Settings → API Keys**. The key is checked on every call, so a revoked key answers `401` from the next request.

## Victoria Pulse

Victoria Pulse has its own API and MCP server, separate from this one. Its OpenAPI document is at `https://data.versionseven.ai/openapi.json`, its tool manifest at `https://data.versionseven.ai/openapi/mcp-tools.json`, and its MCP endpoint at `https://data.versionseven.ai/mcp`, with the discovery document at `https://data.versionseven.ai/.well-known/oauth-protected-resource/mcp`.