Connect the Twain MCP server to your AI assistant

Mohamed ChahinMay 6, 20264 min read

Updated

Connect Twain to Claude, ChatGPT, Cursor, or any MCP client to inspect campaigns, generate sequences, and add leads from chat, then review, edit, and export the result in Twain.

  • API & MCP
  • Workflow automation

Why it matters

Most outbound work doesn't happen in one app. You're in Slack reading a thread, in HubSpot looking at a deal, in Linear writing a ticket about a launch, and somewhere in there you decide a lead is worth reaching out to. Switching to Twain to actually do the outreach is friction. Often enough, the lead never makes it.

The Twain MCP server removes the switch. Wire Twain into Claude, ChatGPT, Claude Code, Cursor, or anything else that speaks the Model Context Protocol, and the assistant in front of you can talk to Twain directly. List your campaigns, generate a sequence for a lead, add someone to a campaign's automation, all from the chat you're already in.

The result is straightforward. Outreach happens on the same surface where the decision happens, instead of two tools later when the moment is gone.

What you can do

The MCP exposes the building blocks of a Twain workspace. Every tool maps to something you can already do in the UI.

  • Browse the workspace. list_workspaces, list_agents, list_campaigns, list_workflows. All read-only, no credits spent.
  • Inspect a setup. get_campaign returns a campaign's generation_costs by mode and names the campaign's automation when it has one, while get_workflow returns an automation's fixed credits_per_contact. The assistant reads those fields before quoting a generation or automation run.
  • Generate for a single lead. generate_contact takes a LinkedIn URL, a work email, or a company domain with the person's name, runs the research, drafts the sequence, and stores the lead on the campaign. High and Ultra return a Thesis; Ultra also returns a Strategy. A longer run returns a job ID, so the assistant follows it with get_generation_status instead of starting the same generation again. list_generation_jobs finds jobs from a batch or an interrupted call.
  • Read results back. get_contact returns a stored contact's messages and analysis; list_contacts lists a campaign's contacts and whether each has generated.
  • Bulk add leads. add_contacts_to_campaign imports contacts for free without generating outreach. Open the returned campaign in Twain to generate the batch, review the copy, edit it, and export it.
  • Push into an automation. add_contact_to_workflow queues the lead through a campaign automation's steps (research, copy, notify) without you opening the app.
  • Create from scratch. create_workspace adds a private or team workspace to put a new setup in. suggest_agent_setup walks you through a new agent the way Twain's agent builder does: the company website, the agent's purpose, then the customer segments and research and warning rules Twain suggests for the company, which you edit. create_agent builds the agent from what you kept. preview_campaign interviews you for a campaign brief one question at a time, with the questions and options of Twain's own campaign builder, and shows you the brief before anything is saved. create_campaign then stands up the campaign from the brief you confirmed: the context, goal and step-by-step sequence every message in the campaign gets written against. Its first generation initializes the campaign's messaging; review and edit that messaging in Twain afterwards.
  • Review a campaign's spend. get_campaign_log returns the campaign's activity log, newest first: imports, generations by mode, removals, exports, verified-email lookups, and setup changes, with the credits each entry charged and totals per kind of spend.
  • Connect your stack. list_integrations shows the CRMs, sequencers, and Slack you've connected and whether each connection works. connect_integration gives you a one-use Twain link to finish the connection in your browser: paste the API key of a sequencer such as Instantly, Smartlead, or lemlist there, or sign in to HubSpot, Salesforce, Outreach, Apollo, Attio, or Slack. Your keys never pass through the chat.
  • Check credits. get_credits returns the current credit balance so the assistant can warn you before generating.
  • Send feedback. give_feedback passes bug reports, missing capabilities, and rough edges straight to the Twain team, right from the chat.

What your plan returns. On the Starter plan, the assistant gets each contact's profile, company, and messages, and whether it has warnings. Its signals, Absent signals, relationship context, Thesis, Strategy, and warning details stay in Twain: the response says so and links the contact. Pro, Enterprise, and the free trial return all of it.

Read-only tools never cost credits. Before generate_contact, the assistant quotes the selected mode from the campaign's generation_costs. Before add_contact_to_workflow, it quotes the workflow's credits_per_contact. The first confirmed mode and spend become session preferences, so the assistant reuses them unless the price rises, it cannot determine the price, a new batch materially increases the total, or you ask to confirm every time. After a generation, credits_used is the amount actually charged.

Connect Claude

Claude connects through a custom connector, and one connector covers claude.ai in the browser, Claude Desktop, and the mobile apps. No terminal, no config files.

Open Settings, pick Connectors, and click Add custom connector. Paste the server URL:

https://mcp.api.twain.ai/

Click Add, then sign in through the OAuth prompt with the same account you use for Twain. Enable the connector in any chat from the + menu.

Connectors are account-level: the same setup follows you everywhere you use Claude, and it also shows up in Claude Code automatically when you're signed in with the same account. On Team and Enterprise plans, only owners can add custom connectors, from Organization settings.

Connect Claude Code

Claude Code (the CLI / VS Code integration) supports HTTP MCP servers natively. One command:

claude mcp add --transport http twain https://mcp.api.twain.ai/

Claude Code flags the server as needing sign-in. Run /mcp, select twain, and choose Authenticate; a browser opens for OAuth. Sign in with the same account you use for Twain. After that, the token is cached and refreshed automatically, and the assistant can call Twain tools directly.

Verify the server is connected:

claude mcp list

You should see twain in the list. The tools (list_campaigns, generate_contact, etc.) become available immediately.

Connect ChatGPT

On ChatGPT web, custom MCP apps sit behind Developer mode and OAuth sign-in, and availability depends on your workspace plan. Enable Developer mode in your settings, create an app with the server URL, and sign in through the OAuth prompt:

https://mcp.api.twain.ai/

Connect Codex

In the ChatGPT desktop app, open Settings, select MCP servers, and click Add server. Name it twain, choose Streamable HTTP as the transport, and paste the same URL:

https://mcp.api.twain.ai/

Save the server and restart when prompted. The server list flags Twain as requiring sign-in; click Authenticate and complete the OAuth flow in the browser. The Codex CLI and IDE extension share this configuration, so the tools follow you across all three. Note that servers added this way run inside Codex sessions.

Connect Cursor

Cursor speaks HTTP MCP directly, like Claude Code. Open ~/.cursor/mcp.json (create it if missing) and add:

{
  "mcpServers": {
    "twain": {
      "url": "https://mcp.api.twain.ai/"
    }
  }
}

Reload Cursor. The Twain tools show up alongside the rest of your MCP servers, and the OAuth handshake runs the first time you trigger one.

Other MCP clients

Any client that speaks streamable HTTP can connect. Clients with OAuth discovery need only the URL; Gemini CLI, for example, connects with gemini mcp add --transport http twain https://mcp.api.twain.ai/ and re-authenticates with /mcp auth twain. For clients that authenticate with an API key instead, add a config entry that sends the key in the X-Api-Key header:

{
  "mcpServers": {
    "twain": {
      "url": "https://mcp.api.twain.ai/",
      "headers": {
        "X-Api-Key": "your-twain-api-key"
      }
    }
  }
}

Your API key is in the app, under API key in the user menu.

Example prompts

Once the server is connected, you don't think about MCP. You just talk to the assistant.

For complete flows, cost checks, and recovery prompts, use the Twain MCP prompt playbook.

A few prompts that work well out of the box:

  • "List my Twain campaigns and tell me which one is for outbound to founders." The assistant calls list_campaigns, reads the descriptions, picks the closest match.
  • "Generate a sequence for https://www.linkedin.com/in/sample in the Founders campaign." The assistant confirms the credit cost, runs generate_contact, and returns the campaign URL when it's done.
  • "Add these 30 LinkedIn URLs to the Q2 SDR automation." The assistant queues them through add_contact_to_workflow one at a time.
  • "How many credits do I have left?" One get_credits call.
  • "What has the Founders campaign spent its credits on?" The assistant calls get_campaign_log and breaks the total down by kind of spend.
  • "Spin up a new campaign for infosec leadership from my security agent." The assistant calls list_agents, then preview_campaign, which asks you one question at a time: why these accounts now, which kind of campaign, what you want them to do, which channels. It drafts the steps, shows you the brief to confirm, then calls create_campaign and reports back with the campaign URL.

MCP fits work that starts in a conversation. When the trigger is an event instead, use an n8n workflow: qualify and route a new signup or prepare a rep when a demo is booked.

The campaigns, agents, and credits are the same ones you use in the web app. Open the returned campaign link in Twain to review and edit the final copy and export it.