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. create_agent builds a Twain agent from a company URL plus an ICP description. create_campaign stands up a new campaign attached to that agent, from a campaign brief: 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.
  • 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.

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.
  • "Spin up a new campaign for infosec leadership from my security agent." The assistant calls list_agents, asks you the handful of questions a brief needs — why these accounts now, what you want them to do, which channels, how many steps — 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.