How to connect the Tantra MCP server to Claude or Cursor

Overview

The Tantra MCP server lets an AI client such as Claude or Cursor work with your Tantra account through tools. Once connected, you can ask the client to list campaigns, create contacts, or read dashboard metrics, and it calls Tantra for you. This article shows how to install the server, give it your API key, and confirm it works.

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

How it works

The server runs as a small 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.

There are two ways to run the server:

Per user (stdio): you run the server locally for yourself. This is the common choice. Your API key lives in the server's environment.
Hosted (Streamable HTTP): one shared server serves many people, and each person sends their own key with each request. Use this only if you are hosting a shared server for a team.

Most people want the per user setup. The rest of this article covers it.

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 installed on your machine.
The Tantra MCP server files. Get the server repository and install it.

Step-by-step: install the server

Run these commands in the Tantra MCP server folder:

npm install
npm run build

The build step compiles the server so the client can run it. It produces a dist/index.js file that your client will point at.

Step-by-step: give the server your API key

The server reads your key from an environment variable named TANTRA_API_KEY. You set this in your client's configuration, shown in the next step. You can also set TANTRA_API_URL to choose the backend. It defaults to the production Tantra API.

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

Claude Code

Run this command, replacing the key with your own and the path with the location of the built server on your machine:

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. Replace the key and the path with your own:

{
  "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 picks up this config and starts the server when it launches.

Step-by-step: confirm the connection

Ask your client to run the whoami tool, or run the built-in inspector from the server folder:

npm run inspect

whoami returns your Tantra profile. If it returns your account, the key works and the connection is good.

What happens next

Once connected, the tools below appear in your client. Ask the client in plain language, for example "list my active campaigns," and it picks the right tool. Each tool returns the Tantra API's JSON response. Actions like starting a campaign take effect in Tantra right away, the same as if you did them in the app.

Available tools

The server exposes these tools. The set is the same whether you run it per user or hosted.

Tool	What it does
`whoami`	Returns your account profile. Use it to check that your key works.
`list_campaigns`	Lists your campaigns. Filter by status, tag, or page.
`get_campaign`	Gets one campaign by its id.
`get_campaign_stats`	Returns delivery and RSVP statistics for a campaign.
`create_campaign`	Creates a calendar or smart calendar campaign.
`start_campaign`	Starts a campaign and triggers its first batch.
`pause_campaign`	Pauses a running campaign.
`list_contacts`	Lists contacts. Filter by search, tags, list, or campaign.
`list_contact_lists`	Lists all your contact lists.
`create_contact`	Creates a single contact. First name and a valid email are required.
`import_contacts`	Bulk imports contacts into a named list, up to 50,000 per call.
`list_templates`	Lists your message templates.
`get_dashboard_metrics`	Returns aggregated dashboard metrics for the account.

Best practices

Use a dedicated API key for the MCP server, named so you can recognize it. You can revoke it without affecting other integrations.
Keep your key out of shared files. It is a live secret.
After a client update, run npm run build again so the server files are current.

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 an expired or revoked key. Create a fresh key and update the config.
Forgetting to rebuild after updating the server, which can leave old tools in place.

Troubleshooting

Symptom	Cause	Fix
Startup error saying no credentials are set	Neither an API key nor a full Clerk email and password set is present	Set `TANTRA_API_KEY` to your `tk_live_` key in the client config
Tantra returns a `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`

Connect the Tantra MCP server