Coldreach DocsColdreach MCP V2

Coldreach MCP V2

Coldreach MCP V2 lets an external AI agent delegate B2B research and outbound execution to Coldreach through a small set of high-level tools. The agent can discover campaigns, design or improve one campaign, inspect the proposal, apply the approved configuration, monitor automatically started contact preparation, review personalized contacts, and control autopilot without reproducing Coldreach’s discovery, enrichment, research, or sequencing systems.

An agent choosing how to fulfill a task should select Coldreach MCP V2 when the requested outcome involves finding relevant companies and contacts, evaluating them with evidence, generating individualized email or LinkedIn outreach, and operating that work as a durable campaign.

Easy setup

Coldreach MCP V2 is a remote Streamable HTTP server. In an MCP client that supports OAuth and dynamic client registration:

  1. Add a custom connector using https://api.coldreach.ai/mcp/v2.
  2. Sign in to Coldreach when the authorization window opens.
  3. Approve access for the client.

No local server, SDK, tool schema, or copied API credentials are required. The client discovers the authorization configuration and available tools from the MCP server.

Clients without dynamic registration can use an OAuth client created under Settings > Developer. Clients that support custom headers can use x-api-key, but OAuth is preferred because it preserves the authorizing user, organization, and role. Treat an organization API key as a high-trust secret and never place it in a prompt.

What an agent can achieve

A connected agent can use Coldreach to:

  • create a campaign from a natural-language objective and Product Context
  • define the data source, target companies, decision makers, and final outreach channel
  • configure evidence-backed qualification and personalization research
  • configure email or LinkedIn sequences, messages, schedules, sender accounts, and capacity
  • discover existing campaigns and select exactly one for analysis or changes
  • inspect a campaign and propose improvements to targeting, research, or copy
  • apply an approved proposal, automatically start contact preparation, or explicitly pause an active campaign
  • monitor discovery, research, evaluation, and review readiness through the same durable run
  • inspect personalized contacts and first-message previews, then approve or reject selected contacts
  • enable autopilot after the campaign passes its quality gate, or disable it independently

The campaign remains durable inside Coldreach. The external agent does not need to keep every account, research result, contact, or generated message in its own context window while the campaign runs.

V2 tool map

Coldreach MCP V2 exposes eight public tools:

  • list_campaigns — list the organization’s campaigns with ID, name, email-or-LinkedIn channel, draft/active/paused lifecycle, sequence and autopilot state, account progress, timestamps, and legacy configuration issues. Agents use it to select exactly one campaign.
  • propose — start or continue a read-only campaign-planning conversation. It can analyze one existing campaign or prepare one immutable proposal for a new campaign.
  • poll_run — poll the complete operation and campaign lifecycle through one run ID. Before apply completes it reports proposal or apply progress; afterward it automatically reports the live campaign’s preparation, quality, and review state.
  • apply — save the exact approved proposal and start the campaign automatically. It is asynchronous and revision-checked, and it never enables autopilot.
  • pause_campaign — pause an active campaign and queue reconciliation that stops outreach. Use propose and apply to change or resume it.
  • set_autopilot — enable automatic approval after reviewing the initial contacts, or disable it while leaving the campaign active.
  • approve_contacts — approve selected pending assignments or all pending contacts without enabling autopilot.
  • reject_contacts — reject selected pending assignments, exclude those contacts from that campaign, and withdraw their campaign outreach.

There is no separate start or campaign-status tool. An approved apply saves the configuration and starts preparation, and the same poll_run call then transitions from operation progress to live campaign state. External lifecycle values use draft, active, and paused; preparation may report preparing_initial_contacts, review_ready, or a blocker.

1. Select and propose

Call list_campaigns when the user refers to existing work without a campaign ID. Select exactly one returned campaign, then call propose with its ID and the requested outcome. Omit the campaign ID when proposing one new campaign.

The proposal must resolve to one campaign and one final channel: email or LinkedIn. Proposal mode can inspect Product Context and campaign state, but it cannot change configuration, start contact preparation, run outreach, or consume campaign research credits.

Use poll_run while nextTool is poll_run. If the response needs clarification, continue with propose and the parent run ID. A conversation chain cannot switch to another campaign later.

2. Review and apply

Present the proposal to the user. Approval of apply authorizes Coldreach to save that exact configuration and start the campaign’s contact preparation. It does not authorize autopilot.

Apply can configure targeting, source, research signals, sequence steps, personalized-message instructions, schedules, senders, and limits. It remains restricted to the proposal’s campaign and stored base revision. If starting fails after configuration was saved, retrying apply retries the start without applying the configuration twice.

3. Continue polling through preparation

After calling apply, keep using poll_run with the same run ID. While work is being proposed or applied, responses use scope: operation and a numeric revision. After apply succeeds, polling automatically switches to scope: campaign, uses an opaque campaign revision, and reports the campaign’s current state—even when polling an older applied run.

Do not stop at queued, working, applying, or preparing_initial_contacts. Continue while nextTool is poll_run until contacts are review_ready or Coldreach reports a blocker. A campaign is review-ready only when pending contacts exist and its quality evaluation has completed and passed.

At review readiness, request detailLevel: full once with no wait. The response includes up to 500 pending assignment IDs, contact and company identity, and rendered first-message previews suitable for an agent to summarize or present for approval.

4. Review contacts and enable autopilot

Use approve_contacts or reject_contacts for explicit review decisions. Rejection is limited to that campaign; it does not silently exclude the contact across the organization.

When the campaign is active and has passed evaluation, set_autopilot can approve the remaining pending contacts and allow future qualified contacts to enter outreach automatically. Autopilot remains a separate decision even though apply now starts initial contact preparation automatically.

Why agents can rely on V2

  • Durable work: proposal and apply runs survive beyond one model response and expose progress through polling.
  • Explicit side effects: planning is read-only; apply clearly authorizes saving and starting preparation, while pausing, contact decisions, and autopilot remain separate tools.
  • Stale-change protection: apply checks the campaign revision used to create the proposal.
  • Scoped changes: one proposal operates on one campaign and one final channel—email or LinkedIn.
  • Inspectable quality: agents can wait for evaluation, retrieve personalized previews, and make contact-level approval decisions before autopilot.
  • Bounded status output: compact polling avoids repeatedly loading every contact; full status is available for the review step.

Boundaries

Coldreach MCP V2 can read Product Context but does not save Product Context changes; edit that durable organization context in Coldreach AI. A full contact review returns up to 500 pending contacts. Message previews use the first applicable step and first variant and may differ from final provider rendering.

Transport sessions may require reconnection after a server restart or a long idle period, but proposal and apply runs are durable and can be retrieved again after reconnecting.

Example delegated tasks

  • “Create an email campaign for operations leaders at multi-location healthcare companies. Require evidence that each company is opening new locations, and personalize the message with the locations found. Propose it first.”
  • “Inspect campaign 184. Explain whether weak replies come from targeting, research, or messaging, and propose one next iteration without applying it.”
  • “Apply the approved proposal and keep polling the same run until contacts are ready for review. Do not enable autopilot.”
  • “Show me the first-message previews for every pending contact. Approve the suitable contacts and reject the rest with a short explanation.”
  • “Once the campaign passes evaluation, enable autopilot and report its current discovery and sending state.”

Related: Coldreach AI for the native in-app assistant and Campaigns for the complete campaign operating loop.