MCP Server — Use Ark with AI Assistants

Send emails, check delivery status, and manage your email infrastructure using natural language through AI assistants.

What is MCP? The Model Context Protocol is an open standard that lets AI assistants interact with external services. Instead of writing code, you can simply ask your AI to “send an email” or “check if that message was delivered.”

Why Use MCP?

Natural Language

Just describe what you want. No code required.

Context-Aware

AI understands your intent and handles edge cases.

Safe Defaults

Confirmation prompts, error recovery, safe operations.

Supported AI Assistants

Claude Desktop

Full MCP support

Cursor

AI code editor

VS Code

Claude extension

Windsurf

AI IDE

For detailed IDE setup instructions including troubleshooting, see the IDE Setup Guide.

Quick Setup

Claude Desktop

Get your API key

Create an API key at arkhq.io/org/credentials

Configure Claude Desktop

Open your Claude Desktop configuration file and add the Ark MCP server:

macOS
Windows
Linux

File location: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ark-email": {
      "command": "npx",
      "args": ["-y", "ark-email-mcp"],
      "env": {
        "ARK_API_KEY": "ark_live_your_key_here"
      }
    }
  }
}

File location: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ark-email": {
      "command": "npx",
      "args": ["-y", "ark-email-mcp"],
      "env": {
        "ARK_API_KEY": "ark_live_your_key_here"
      }
    }
  }
}

File location: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ark-email": {
      "command": "npx",
      "args": ["-y", "ark-email-mcp"],
      "env": {
        "ARK_API_KEY": "ark_live_your_key_here"
      }
    }
  }
}

Restart Claude Desktop

Fully quit and reopen Claude Desktop to load the MCP server.

Start sending emails

Try asking:

“Send a test email to my@email.com from hello@yourdomain.com with the subject ‘Hello from Ark!’”

Cursor

One-Click Install
Manual Setup

Click to add Ark to Cursor:

After clicking, update the API key in Cursor’s MCP settings.

Add to your Cursor settings (.cursor/mcp.json):

{
  "mcpServers": {
    "ark-email": {
      "command": "npx",
      "args": ["-y", "ark-email-mcp"],
      "env": {
        "ARK_API_KEY": "ark_live_your_key_here"
      }
    }
  }
}

VS Code

One-Click Install
Manual Setup

Click to add Ark to VS Code:

With the Claude extension, add to VS Code settings:

{
  "claude.mcpServers": {
    "ark-email": {
      "command": "npx",
      "args": ["-y", "ark-email-mcp"],
      "env": {
        "ARK_API_KEY": "ark_live_your_key_here"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "ark-email": {
      "command": "npx",
      "args": ["-y", "ark-email-mcp"],
      "env": {
        "ARK_API_KEY": "ark_live_your_key_here"
      }
    }
  }
}

What You Can Do

Send Emails

Just describe what you want in natural language:

Simple emails

“Send a welcome email to john@example.com with the subject ‘Welcome to Acme!’”

“Email user@example.com saying their order has shipped”

“Send a test email to myself at my@email.com”

Password resets & notifications

“Send a password reset email to user@example.com with a reset link”

“Notify the engineering team that the deployment is complete”

“Send an alert email about the failed payment”

Formatted emails

“Send an HTML email to customer@example.com with their invoice details in a nice table format”

“Email the report as a formatted newsletter”

Batch emails

“Send the same announcement to these 10 email addresses: …”

“Email all team leads about the upcoming meeting”

Check Delivery Status

Delivery verification

“Was the email to customer@example.com delivered?”

“Check the status of the last email I sent”

“Did john@acme.com receive the welcome email?”

Troubleshooting

“Why didn’t the email to user@domain.com go through?”

“Show me recent bounces”

“What happened to the email sent to invalid@example.com?”

Manage Suppressions

Check suppression status

“Is john@example.com on our suppression list?”

“Why is user@domain.com suppressed?”

“Show me all suppressed emails”

Modify suppression list

“Remove user@example.com from the suppression list”

“Add bounced@example.com to the suppression list”

“Clear the suppression for this customer who fixed their mailbox”

Configure Domains

Domain setup

“Help me set up mail.mydomain.com as a sending domain”

“Show me the DNS records I need to add for mydomain.com”

“What domains do I have configured?”

Verification

“Verify my domain configuration for mydomain.com”

“Check if the DNS records for mail.acme.com are correct”

Available Tools

The MCP server exposes these tools to AI assistants:

Email Operations

Tool	Description
`send_email`	Send a transactional email to one or more recipients
`send_batch`	Send multiple different emails in one request (up to 100)
`send_raw`	Send a raw MIME message for advanced use cases
`get_email`	Get details and delivery status of a sent email
`list_emails`	List sent emails with filtering by status, date, tags
`retry_email`	Retry delivery of a failed email
`get_deliveries`	Get all delivery attempts for an email

Suppression Management

Tool	Description
`check_suppression`	Check if an email address is suppressed and why
`add_suppression`	Add an email to the suppression list
`bulk_add_suppressions`	Add multiple emails to the suppression list
`remove_suppression`	Remove an email from the suppression list
`list_suppressions`	List all suppressed email addresses

Domain Management

Tool	Description
`create_domain`	Register a new sending domain
`list_domains`	List all configured sending domains
`get_domain`	Get details and DNS records for a domain
`verify_domain`	Trigger DNS verification for a domain
`delete_domain`	Remove a sending domain

Webhook Management

Tool	Description
`create_webhook`	Create a webhook endpoint for events
`list_webhooks`	List all configured webhooks
`update_webhook`	Modify webhook URL or events
`test_webhook`	Send a test event to a webhook
`delete_webhook`	Remove a webhook

Tracking Domains

Tool	Description
`create_tracking_domain`	Set up a custom tracking domain
`list_tracking_domains`	List tracking domain configurations
`verify_tracking_domain`	Verify tracking domain DNS
`delete_tracking_domain`	Remove a tracking domain

Testing

To test email sending, use your verified domain:

“Send a test email from hello@yourdomain.com to myemail@gmail.com”

You must have a verified sending domain to send emails. See our domain setup guide for instructions.

Example Conversations

Sending a Welcome Email

Checking Delivery Status

Troubleshooting a Bounce

Security

API Key Storage

Your API key is stored locally in your configuration file on your machine. It’s:

Never sent to Anthropic, OpenAI, or other AI providers
Only transmitted directly to Ark’s servers (api.arkhq.io) over HTTPS
Only accessible by the local MCP server process

How MCP Works

You <-> AI Assistant <-> Local MCP Server <-> Ark API

The AI assistant talks to a local MCP server running on your machine. The MCP server makes API calls directly to Ark. Your API key never leaves your computer except to authenticate with Ark.

Permissions

The MCP server has the same permissions as your API key. To limit access:

Create a restricted API key with only the permissions needed
Use read-only keys for monitoring/analytics use cases
Rotate keys regularly at arkhq.io/org/credentials

Rate Limits

The MCP server respects Ark’s rate limits:

Operation	Rate Limit
Most operations	5 requests/second
Batch sending	1 request/second (up to 100 emails)

If rate limited, the AI assistant will wait and retry automatically. For high-volume operations, the AI will pace requests appropriately.

Troubleshooting

MCP server not loading

Symptoms: AI assistant doesn’t recognize email commands, no Ark tools available.Solutions:

Ensure Node.js 20+ is installed: node --version
Check your config file for JSON syntax errors (use a JSON validator)
Restart your AI assistant completely (fully quit, not just close window)
Check logs:
- Claude Desktop: Help > Show Logs
- Cursor: View > Output > MCP
- VS Code: Output panel > Claude

Authentication errors

Symptoms: “Invalid API key” or “Unauthorized” errors.Solutions:

Verify your API key is correct (no extra spaces)
Ensure the key starts with ark_live_ or ark_test_
Check the key hasn’t been revoked at arkhq.io/org/credentials
Try generating a new API key

Emails not sending

Symptoms: Send command succeeds but email never arrives.Solutions:

Domain: Ensure your sending domain is verified
DNS: Verify DNS records are configured correctly
Suppression: Check if recipient is on suppression list
Spam folder: Check recipient’s spam/junk folder
Status: Ask “What’s the status of the last email I sent?”

Slow responses

Symptoms: MCP commands take a long time to complete.Solutions:

Large batch operations naturally take longer
Check your internet connection
The first request after startup may be slow (npm package download)
Check Ark status page for any issues

FAQ

Is this free?

The MCP server itself is free and open source. You pay for Ark usage based on your plan — Starter (

29/mo for 50K emails), Growth (

99/mo for 250K emails), or Scale ($499/mo for 2M emails). New organizations start on a free trial. See Plans & Billing for details.

Can I use this for marketing emails?

Ark is designed for transactional emails - password resets, order confirmations, notifications, etc. For bulk marketing campaigns, use a dedicated email marketing platform.

Does the AI see my email content?

The AI assistant processes your requests locally. Email content is sent directly from the MCP server to Ark’s API. However, if you type email content in your chat, it becomes part of your conversation with the AI provider.

Can I self-host the MCP server?

Yes! The MCP server is open source. Clone the repository and run locally:

git clone https://github.com/ArkHQ-io/ark-nodejs
cd packages/mcp
npm install
ARK_API_KEY=your_key npm start

Resources

npm Package

ark-email-mcp on npm

GitHub Repository

Source code, issues, contributions

MCP Documentation

Learn more about the Model Context Protocol

Ark API Reference

Full REST API documentation

Overview

Languages

AI Integration

IDE Setup

​Why Use MCP?

Natural Language

Context-Aware

Safe Defaults

​Supported AI Assistants

Claude Desktop

Cursor

VS Code

Windsurf

​Quick Setup

​Claude Desktop

​Cursor

​VS Code

​Windsurf

​What You Can Do

​Send Emails

​Check Delivery Status

​Manage Suppressions

​Configure Domains

​Available Tools

​Email Operations

​Suppression Management

​Domain Management

​Webhook Management

​Tracking Domains

​Testing

​Example Conversations

​Sending a Welcome Email

​Checking Delivery Status

​Troubleshooting a Bounce

​Security

​Rate Limits

​Troubleshooting

​FAQ

​Resources

npm Package

GitHub Repository

MCP Documentation

Ark API Reference

Why Use MCP?

Supported AI Assistants

Quick Setup

Claude Desktop

Cursor

VS Code

Windsurf

What You Can Do

Send Emails

Check Delivery Status

Manage Suppressions

Configure Domains

Available Tools

Email Operations

Suppression Management

Domain Management

Webhook Management

Tracking Domains

Testing

Example Conversations

Sending a Welcome Email

Checking Delivery Status

Troubleshooting a Bounce

Security

Rate Limits

Troubleshooting

FAQ

Resources