Instant

You run an MCP (Model Context Protocol) server built in Python to expose 38 tools across accounts, campaigns, leads, emails, analytics, and background jobs. It supports remote HTTP deployments and local stdio workflows, loads only the tool categories you need to optimize context usage, and can handle per-request API keys for multi-tenant setups. This guide walks you through practical usage, installation, and configuration to get you running quickly.

How to use

You interact with the MCP server through your MCP client. Start a server in HTTP mode for remote deployments so clients connect over the network. For local development, run in stdio mode and connect directly from your tooling.

How to install

Prerequisites: Python 3.11+ and a working internet connection.

1. Clone or navigate to your project directory.

2. Install the package in editable mode.

3. Install required Python dependencies.

Additional configuration and usage notes

Set your Instantly API key to enable authentication for the MCP server. You can provide it via environment variable INSTANTLY_API_KEY, pass a key through a URL path, or send it in HTTP headers as x-instantly-api-key or Authorization. The server supports per-request API keys for multi-tenant deployments, ensuring isolated usage per client.

Troubleshooting and tips

If you encounter authentication errors, verify that your API key is provided in the expected method (environment variable, URL, or header) and that the key matches the active tenant. If you hit rate limits, the server reports remaining quota and reset times based on the upstream API response headers. For performance, consider lazy loading by loading only the necessary tool categories to minimize the context window.

Security and deployment notes

For multi-tenant HTTP deployments, you can start the server without a default API key and require clients to supply their own per-request API keys via headers. Use HTTPS in production and protect API keys in environment variables or secret management systems. Keep dependencies up to date to benefit from the latest error handling and timeout improvements.

Examples and reference configurations

The following configurations illustrate both HTTP-based and stdio-based MCP server invocations. Use these as exact starting points in your environment.

Project structure and tools overview

The MCP server exposes 38 tools organized into six categories: accounts, campaigns, leads, emails, analytics, and background_jobs. Each tool performs a specific action such as listing accounts, creating campaigns, updating leads, or fetching analytics. Use the appropriate tool in your MCP client to perform operations against your data through the server.

Authentication methods and endpoints

• URL-based authentication: access via a key embedded in the URL path, for example: https://your-server.com/mcp/YOUR\_API\_KEY.

• Header-based authentication: provide the API key in the Authorization header as a bearer or plain value, e.g., Authorization: YOUR_API_KEY.

• Custom header method: use a dedicated header like x-instantly-api-key: YOUR_API_KEY.

• Environment variable: export INSTANTLY_API_KEY=your-api-key-here locally.

Lazy loading and categories

Load only the tool categories you need to minimize the context window. For example, load accounts and campaigns together for a lean set of 14 tools, or leads and analytics for a different workflow.

Multi-tenant HTTP mode

For deployments serving multiple users, you can start the server without a default API key and require per-request keys. Clients supply their key via a header in each request.

Error handling and rate limiting

The server returns detailed, actionable error messages. It also tracks rate limits automatically by inspecting API response headers and exposes remaining quota, total limit, and reset times in its status information.

Getting started with CLI options

Run the HTTP mode server with a specific port to expose it remotely.

Available tools

list_accounts

List email accounts with filtering

get_account

Get account details and warmup status

create_account

Create account with IMAP/SMTP credentials

update_account

Update account settings

manage_account_state

Pause, resume, warmup control, test vitals

delete_account

Permanently delete account

create_campaign

Create email campaign (two-step process)

list_campaigns

List campaigns with pagination

get_campaign

Get campaign details and sequences

update_campaign

Update campaign settings

activate_campaign

Start campaign sending

pause_campaign

Stop campaign sending

delete_campaign

Permanently delete campaign

search_campaigns_by_contact

Find campaigns a contact is enrolled in

list_leads

List leads with filtering

get_lead

Get lead details

create_lead

Create single lead

update_lead

Update lead (replaces custom_variables)

list_lead_lists

List lead lists

create_lead_list

Create lead list

update_lead_list

Update lead list

get_verification_stats_for_lead_list

Get email verification stats

add_leads_to_campaign_or_list_bulk

Bulk add up to 1,000 leads

delete_lead

Permanently delete lead

delete_lead_list

Permanently delete lead list

move_leads_to_campaign_or_list

Move/copy leads between campaigns/lists

list_emails

List emails with filtering

get_email

Get email details

reply_to_email

Send real email reply

count_unread_emails

Count unread inbox emails

verify_email

Verify email deliverability

mark_thread_as_read

Mark email thread as read

get_campaign_analytics

Campaign metrics (opens, clicks, replies)

get_daily_campaign_analytics

Day-by-day performance

get_warmup_analytics

Account warmup metrics

list_background_jobs

List async background jobs with pagination

get_background_job

Get details of a specific background job