Connect the Tantra MCP server

Overview#

The Tantra MCP server lets an AI assistant such as Claude, ChatGPT, Claude Code or Cursor work with your Tantra account through tools. Once connected, you ask in plain language, for example "pause the webinar campaign and show me who replied this week", and the assistant calls Tantra for you. This article shows how to run the server, give it your API key, confirm it works, and what the assistant can and cannot do through it.

MCP stands for Model Context Protocol, an open standard that lets AI clients call external tools. The Tantra MCP server is a small program that forwards each tool call to the Tantra API with your key.

You run the server yourself. Tantra provides the source code; you run it on your own machine for yourself, or on your own server for a team. Tantra does not operate a shared MCP endpoint.

How it works#

The server is a Node program. You start it, give it a Tantra API key, and point your AI client at it. When you ask the client to do something in Tantra, the client calls one of the server's tools, the server calls the Tantra API with your key, and the result comes back to the client. The server stores nothing: every call goes to Tantra, and Tantra applies the same account scoping it applies to the app.

There are two ways to run it:

• Per user (stdio): the server runs on your own computer and your client starts and stops it. Your API key lives in the client's configuration. This is the common choice for Claude Desktop, Claude Code and Cursor.
• Shared HTTP server: one server on your own infrastructure serves a team. Each person connects with their own API key, sent on every request, so each person sees only their own account. Clients that connect to a URL rather than a local program, such as ChatGPT, use this mode.

Most people want the per-user setup. The steps below cover it; the shared server is described further down.

Before you start#

• A Tantra API key. Create one on the API Keys page and copy the tk_live_ value at creation. See Create and manage API keys.
• Node.js 20 or newer on the machine that will run the server.
• The server source: the tantra-mcp folder Tantra provides.

Step-by-step: build the server#

Run these commands in the tantra-mcp folder:

npm install
npm run build

The build produces dist/index.js, the file your client will point at.

Step-by-step: add the server to your client#

The server reads your key from the TANTRA_API_KEY environment variable, set in the client's configuration. TANTRA_API_URL chooses the backend and defaults to the production Tantra API.

Claude Code#

Run this command, replacing the key and the path with your own:

claude mcp add tantra \
  --env TANTRA_API_URL=https://api.usetantra.com/api/v1 \
  --env TANTRA_API_KEY=tk_live_your_key_here \
  -- node "/path/to/tantra-mcp/dist/index.js"

Claude Desktop or Cursor#

Add an entry to the client's MCP config file, for example claude_desktop_config.json or .mcp.json:

{
  "mcpServers": {
    "tantra": {
      "command": "node",
      "args": ["/path/to/tantra-mcp/dist/index.js"],
      "env": {
        "TANTRA_API_URL": "https://api.usetantra.com/api/v1",
        "TANTRA_API_KEY": "tk_live_your_key_here"
      }
    }
  }
}

The client starts the server when it launches.

Let an AI assistant do the setup#

The setup is a few commands, so a coding assistant can do it. Open the tantra-mcp folder in Claude Code or Cursor and ask it to run the build, register the server with your client using dist/index.js and your key, and confirm with the whoami tool. Paste the key when it asks, and tell it not to print or commit the key. The server's README contains a ready-made prompt.

Step-by-step: confirm the connection#

Ask your client to run the whoami tool. It returns your Tantra profile. If it returns your account, the key works and the connection is good. You can also run the built-in inspector from the server folder with npm run inspect.

What happens next#

The tools appear in your client. Ask in plain language and the assistant picks the right tool; each tool returns Tantra's response. Actions take effect in Tantra right away, the same as in the app: starting a campaign sends invitations, replying in the inbox sends a message.

When the server connects, it also gives the assistant a short set of instructions: which steps need you in the dashboard, what to do when a plan limit is reached, and that anything that sends must be confirmed with you first. Tools that send or delete are marked so that the assistant asks before using them, in clients that support confirmations.

Available tools#

The server exposes dozens of tools, grouped by area. The names below are the main ones; the server's README lists every tool with its arguments.

Area	Main tools
Account	whoami, list_sender_accounts, manage_sender_account, get_settings, update_settings, get_help
Calendar campaigns	list_campaigns, get_campaign, create_campaign, start_campaign, set_campaign_status, cancel_campaign, get_campaign_rsvp, get_campaign_progress, add_campaign_contacts
Sequences (email, LinkedIn, WhatsApp, Telegram)	list_email_campaigns, create_email_campaign, create_sequence_step, start_email_campaign, set_email_campaign_paused, cancel_email_campaign, list_email_enrollments, control_enrollment, add_email_campaign_contacts
Contacts and lists	list_contacts, get_contact, import_contacts, update_contact, set_contact_stage, get_contact_activity, manage_contact_list, manage_contact_tags
Inbox	list_email_threads, get_thread_messages, get_person_conversations, reply_to_email_thread
Social accounts	list_channel_accounts, set_channel_account_limits, disconnect_channel_account
Do-not-contact	unsubscribe_contact, manage_suppression_list, upload_suppression_csv, list_blocked_emails
Templates and AI	list_templates, manage_template, generate_template_copy, preview_email_personalization, preview_calendar_personalization
Deliverability	get_deliverability_health, set_mailbox_warmup, list_tracking_domains, manage_tracking_domain
Webinars	list_webinars, get_webinar_report, sync_zoom, list_zoom_registrants, webinargeek_sync, list_webinargeek_subscribers
Reports and dashboard	get_dashboard_metrics, get_email_analytics, get_campaign_performance_report, get_webinar_attribution, export_csv
Webhooks	list_webhooks, manage_webhook
Billing	get_billing

get_help searches this help centre, so the assistant can look up how a feature works before acting.

What stays in the dashboard#

Some steps are deliberately not available through the server, because they involve a password, a secret key or a payment. The assistant is told to send you to the right page and continue once you confirm:

• Connecting a LinkedIn, WhatsApp or Telegram account.
• Uploading a Google service-account file, and saving Zoom or WebinarGeek credentials.
• Setting up the AI provider used for personalization.
• Creating, rotating or revoking an API key.
• Changing your plan or the number of included accounts. The assistant can read your plan, usage and price previews with get_billing; the change itself is made on the Billing page. No tool takes card details.

Account administration pages are not reachable through the server at all.

Shared HTTP server for a team#

Run npm run start:http on your own host, behind HTTPS, and set TANTRA_MCP_ALLOWED_HOSTS to its hostname. Each person configures their client with the URL and their own key in an X-Tantra-Api-Key header. The server verifies the key with Tantra before opening a session, requires the same key on every later request, and rate-limits by address and by key. Nothing is stored between requests except the open session.

Two settings control what the tools may do, in either mode:

• TANTRA_MCP_READ_ONLY=true exposes only tools that change nothing. A person can also opt a single session into read-only with an X-Tantra-Read-Only: true header.
• TANTRA_MCP_ALLOW_BILLING_WRITES=true adds a tool that changes the subscription. It is off by default because a plan change can charge the saved card immediately.

Best practices#

• Use a dedicated API key for the MCP server, named so you can recognise it. You can revoke it without affecting other integrations.
• Keep the key out of shared files and chat. It is a live secret, and it is all-or-nothing: a key can do everything the tools allow.
• Confirm the audience and the content before letting the assistant start a campaign, add contacts to a live campaign, or reply in the inbox. Those reach real people and cannot be recalled.
• Treat text the assistant reads from contacts and inbox messages as information, not instructions. The server tells the assistant the same, but a read-only session is the safer choice when the assistant is summarising replies.
• Rebuild with npm run build after updating the server source, so the client sees the current tools.

Common mistakes#

• Pointing the client at the source folder instead of the built dist/index.js. Build first, then point at the built file.
• Using a revoked or rotated key. Create a fresh key and update the config.
• Running the shared HTTP server without HTTPS in front of it. Every request carries a key.
• Expecting the assistant to connect a social account or upload a service account. Those stay in the dashboard.

Troubleshooting#

Symptom	Cause	Fix
Startup error saying no credentials are set	TANTRA_API_KEY is missing from the client config	Set it to your tk_live_ key
Startup error about TANTRA_API_URL	The backend address is not https	Use https://api.usetantra.com/api/v1; plain http is accepted for localhost only
Tantra returns 401 after a valid key	The key was revoked or rotated, or the backend URL is wrong	Create a new key, or check TANTRA_API_URL
Tools do not appear in the client	The server was not built, or the client points at the wrong file	Run npm run build and point the client at dist/index.js
Only read tools appear	The server or the session is read-only	Remove TANTRA_MCP_READ_ONLY or the X-Tantra-Read-Only header
Shared server answers 404 Session not found	The session expired, the server restarted, or the request carried a different key than the one that opened the session	Reconnect the client
A tool is refused with a plan or account-limit message	The current plan does not cover the action	The assistant will point you to the Billing page; change the plan there, then retry

FAQ#

Which clients work with the Tantra MCP server?#

Any MCP-compatible client. Claude Desktop, Claude Code and Cursor connect to the per-user server directly. Clients that connect to a URL, such as ChatGPT, connect to the shared HTTP server you host.

Do I need to keep the server running myself?#

For the per-user setup, your client starts and stops it based on its config. For the shared HTTP server, you keep it running like any other service on your host.

Can several people share one server?#

Yes, with the shared HTTP server. Each person sends their own key on every request and sees only their own account.

Where does my API key live?#

For the per-user setup, in your client's config as the TANTRA_API_KEY environment variable. For the shared server, in each person's own client config as a request header. The server itself stores no keys.

Can the assistant spend money through the server?#

No tool takes card details. Reading the plan and previewing prices is available; changing the plan is made on the Billing page unless the person running the server has explicitly enabled billing writes.

Can the server do everything the Tantra app can?#

Almost everything that does not involve a secret or a payment. Connecting accounts, uploading credentials, API keys and plan changes stay in the dashboard.

Related articles#

• Create and manage API keys
• Receive outbound webhooks