# MCP Server

> Use the SendPing MCP server to give your AI agent native access to the full SendPing platform over natural language.

## What is an MCP server?

MCP (Model Context Protocol) is an open protocol that standardizes how applications provide context to LLMs. Among other benefits, it gives LLMs tools to act on your behalf.

## What can the SendPing MCP server do?

The SendPing MCP server gives your AI agent native access to the full SendPing platform through a single integration. You can manage your email infrastructure using natural language:

- **Emails** — send, list, get, cancel, update, and batch-send emails. Supports HTML, plain text, attachments (local file, URL, or base64), CC/BCC, reply-to, scheduling, and topic-based sending.
- **Received emails** — list and read inbound emails; list and download received attachments.
- **Contacts** — create, list, get, update, and remove contacts. Manage segment memberships, topic subscriptions, and CSV imports, with custom contact properties.
- **Campaigns** — create, send, list, get, update, and remove campaigns, with scheduling, personalization placeholders, and preview text.
- **Domains** — create, list, get, update, remove, and verify sender domains. Configure tracking, TLS, and sending/receiving capabilities.
- **Segments** — create, list, get, and remove audience segments.
- **Topics** — create, list, get, update, and remove subscription topics.
- **Contact properties** — create, list, get, update, and remove custom contact attributes.
- **API keys** — list your API keys and see when each was last used. Creating, re-scoping, and revoking keys are **dashboard-only** and cannot be done by any agent holding a key: those calls return `403 dashboard_only`. Do them yourself at the **API Keys** page.
- **Webhooks** — create, list, get, update, and remove webhooks for event notifications.

> **Note:** The server also includes `create-contact-import`, `get-contact-import`, and `list-contact-imports` tools to upload CSV files, check import status, and review previous imports.

## Prerequisites

The SendPing MCP server is published on NPM as `sendping-mcp` and runs with `npx` in any supported MCP client. Before you start:

- [Create an API key](https://www.sendping.co/docs/api-keys/overview).
- [Verify your domain](https://www.sendping.co/docs/domains/managing).

## Stdio transport (default)

The server supports two transport modes: **stdio** (default) and **HTTP**. Replace `mb_xxxxxxxxx` with your actual key in every example below.

**Claude Code**

```bash
claude mcp add sendping -e SENDPING_API_KEY=mb_xxxxxxxxx -- npx -y sendping-mcp
```

**Codex**

```bash
codex mcp add sendping \
  --env SENDPING_API_KEY=mb_xxxxxxxxx \
  -- npx -y sendping-mcp
```

**Cursor**

```json
{
  "mcpServers": {
    "sendping": {
      "command": "npx",
      "args": ["-y", "sendping-mcp"],
      "env": {
        "SENDPING_API_KEY": "mb_xxxxxxxxx"
      }
    }
  }
}
```

**Claude Desktop**

```json
{
  "mcpServers": {
    "sendping": {
      "command": "npx",
      "args": ["-y", "sendping-mcp"],
      "env": {
        "SENDPING_API_KEY": "mb_xxxxxxxxx"
      }
    }
  }
}
```

**Windsurf**

```json
{
  "mcpServers": {
    "sendping": {
      "command": "npx",
      "args": ["-y", "sendping-mcp"],
      "env": {
        "SENDPING_API_KEY": "mb_xxxxxxxxx"
      }
    }
  }
}
```

**Copilot**

```json
// Add to your VS Code settings.json:
{
  "mcp": {
    "servers": {
      "sendping": {
        "command": "npx",
        "args": ["-y", "sendping-mcp"],
        "env": {
          "SENDPING_API_KEY": "mb_xxxxxxxxx"
        }
      }
    }
  }
}
```

**Gemini CLI**

```json
{
  "mcpServers": {
    "sendping": {
      "command": "npx",
      "args": ["-y", "sendping-mcp"],
      "env": {
        "SENDPING_API_KEY": "mb_xxxxxxxxx"
      }
    }
  }
}
```

**OpenCode**

```json
// Add to your opencode.json config:
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sendping": {
      "type": "local",
      "command": ["npx", "-y", "sendping-mcp"],
      "enabled": true,
      "environment": {
        "SENDPING_API_KEY": "mb_xxxxxxxxx"
      }
    }
  }
}
```

## HTTP transport

Run the server over HTTP for remote or web-based integrations. In HTTP mode, each client authenticates by passing its SendPing API key as a Bearer token in the `Authorization` header.

**Start the server**

```bash
npx -y sendping-mcp --http --port 3000
```

The server listens on `http://127.0.0.1:3000` and exposes the MCP endpoint at `/mcp` using Streamable HTTP.

**Claude Code**

```bash
claude mcp add sendping --transport http http://127.0.0.1:3000/mcp --header "Authorization: Bearer mb_xxxxxxxxx"
```

**Cursor**

```json
{
  "mcpServers": {
    "sendping": {
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer mb_xxxxxxxxx"
      }
    }
  }
}
```

You can also set the port via the `MCP_PORT` environment variable: `MCP_PORT=3000 npx -y sendping-mcp --http`.

## Options

Pass additional arguments to configure the server:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `--key` | string | No | Your SendPing API key (stdio mode only — HTTP mode uses the client Bearer token). |
| `--sender` | string | No | Default sender email address from a verified domain. |
| `--reply-to` | string | No | Default reply-to address (can be specified multiple times). |
| `--http` | flag | No | Use HTTP transport instead of stdio (default: stdio). |
| `--port` | number | No | HTTP port when using `--http` (default: 3000, or `MCP_PORT`). |

### Environment variables

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `SENDPING_API_KEY` | string | No | Your API key. Required for stdio; optional for HTTP since clients pass it via Bearer token. |
| `SENDER_EMAIL_ADDRESS` | string | No | Default sender address from a verified domain (optional). |
| `REPLY_TO_EMAIL_ADDRESSES` | string | No | Comma-separated reply-to addresses (optional). |
| `MCP_PORT` | number | No | HTTP port when using `--http` (optional). |

> **Note:** If you do not provide a sender email address, the MCP server asks you to provide one each time you call a send tool.

## Local development

To run from a local build instead of `npx`, clone and build the project, then point your client at the built entry file.

**Clone and build**

```bash
git clone https://github.com/sendping/sendping-mcp.git
pnpm install
pnpm run build
```

Then replace the `npx` command with the path to your local build:

**Claude Code (stdio)**

```bash
claude mcp add sendping -e SENDPING_API_KEY=mb_xxxxxxxxx -- node ABSOLUTE_PATH_TO_PROJECT/dist/index.js
```

**Cursor (stdio)**

```json
{
  "mcpServers": {
    "sendping": {
      "command": "node",
      "args": ["ABSOLUTE_PATH_TO_PROJECT/dist/index.js"],
      "env": {
        "SENDPING_API_KEY": "mb_xxxxxxxxx"
      }
    }
  }
}
```

**HTTP**

```bash
node ABSOLUTE_PATH_TO_PROJECT/dist/index.js --http --port 3000
```

### Testing with MCP Inspector

After building, start the inspector to verify the server and list its tools:

```bash
export SENDPING_API_KEY=mb_your_key_here
pnpm inspector
```

- **Stdio** — choose *stdio (launch a process)*, set **Command** to `node`, **Args** to `dist/index.js`, and **Env** to `SENDPING_API_KEY=mb_your_key_here`. Click **Connect**, then **List tools**.
- **HTTP** — start the server with `node dist/index.js --http --port 3000`, then in the inspector choose *Streamable HTTP*, set **URL** to `http://127.0.0.1:3000/mcp`, add header `Authorization: Bearer mb_your_key_here`, and click **Connect**.