DocumentationAPI Reference

Guides

MCP

Connect Cursor, Claude, ChatGPT, and other MCP clients to Furnace.

Furnace runs a hosted MCP (Model Context Protocol) server so AI clients like Cursor, Claude, and ChatGPT can work with your account directly — create campaigns, add people, read replies, and more. The tools mirror the Client API and update automatically.

Server URL

Add this as a remote (HTTP) MCP server in your client:

https://mcp.getfurnace.io/mcp

You can also copy this from Settings → Developers → MCP in Furnace.

Connect with OAuth

  1. In your MCP client, add a new remote / HTTP MCP server using the URL above.
  2. When prompted, sign in to Furnace and click Approve.
  3. Your client receives an access token automatically — there is no API key to paste.

Server updates apply on your next session without any change to your MCP config.

What you get

Tools mirror the Furnace Client API — campaigns, flows, leads, inbox threads, webhooks, API keys, and mailbox connect sessions. The API Reference documents the underlying endpoints and objects.

Adding leads: pick the right tool

  • A CSV or Excel file: createBulkUploadUrl, upload the file with curl -X PUT -H "Content-Type: text/csv" --data-binary @leads.csv "<upload_url>", then importLeadsFromUpload and poll getAsyncImportJob. Rows never pass through tool calls, so this works for thousands of leads. It needs a client that can run a shell command (Claude Code, Claude Cowork).
  • A few rows you already have as data: queueAsyncLeadImport (up to 1000 per call), or bulkSyncLeads (up to 100, returns right away). With no shell and a large list, use createStagedLeadImport to send rows in batches of 500.
  • People already in Furnace (a saved list, another campaign, or known global_lead_ids): enrollPeople. It does not accept new lead rows.

When adding people, tag by name (Hunter, Running Meta Ads) rather than inventing UUIDs. Send email_verification only when you already have a verifier result; never guess ok. Tags are person-level; custom_lead_data is campaign-level personalization.

Enriching people

  • enrichPerson finds a person's title, company, LinkedIn and mobile phone from their email or LinkedIn URL. A new match costs 1 enrichment credit; repeats within 30 days are free (reused: true). It saves nothing.
  • If status is pending, the mobile is still on its way: call getPersonEnrichment a few minutes later. getPersonEnrichment is free, so use it first to check whether someone was already enriched.
  • Save the fields you want with updatePerson. phone_number is the company phone; mobile_phone_number is the person's mobile.

Attachments

  • Reading: listThreadMessages lists each message's attachments. downloadMessageAttachment returns a signed url; add include_content=true to read small files (3 MB or less) directly: PDFs come back as their text, text files (CSV, JSON, HTML) as text, and images as images. Other types, and PDFs with no text layer, return only the url.
  • Sending a file on disk: createThreadAttachment without content_base64, upload with curl -X PUT -H "Content-Type: <content_type>" --data-binary @file "<upload_url>", then pass the attachment_id in attachment_ids on createReplyJob or createForwardJob.
  • Sending a small generated file: createThreadAttachment with content_base64 (4 MB or less). Do not paste large files into tool calls as base64.

Advanced: API key

For scripts or clients that do not support OAuth, you can authenticate with an API key instead:

Authorization: Bearer f_your_key_here

Create a key under Settings → Developers → API keys — see Authentication. Prefer OAuth for interactive MCP clients.