MCP Server

Official Model Context Protocol (MCP) server for Posthawk. Let AI agents like Claude, Cursor, and Windsurf send emails, manage contacts, and check domain status through natural language.

SDKnpx posthawk-mcp

Run the MCP server directly with npx — no global install needed. The server connects via stdio by default, which is what most MCP clients (Claude Code, Cursor, Windsurf) expect.

Example

bash

npx posthawk-mcp

SDKclaude mcp add --transport http posthawk

Connect to the hosted Posthawk MCP server with OAuth. No API key needed — Claude Code opens your browser for authorization. Your credentials persist across sessions.

Example

bash

# One command — opens browser for OAuth authorization
claude mcp add --transport http posthawk https://mcp.posthawk.dev/mcp

# That's it! Claude Code will:
# 1. Open your browser to app.posthawk.dev
# 2. You log in and pick a workspace
# 3. Click "Authorize" — API key is created automatically
# 4. Token is stored and refreshed automatically

SDKclaude mcp add posthawk

If you prefer to use an API key directly, add the server via stdio transport with your key from the dashboard.

Example

bash

# Add with API key via stdio
claude mcp add posthawk -e POSTHAWK_API_KEY=ck_live_... -- npx posthawk-mcp

SDK.cursor/mcp.json

Add Posthawk to Cursor or Windsurf by creating an MCP configuration file in your project root.

Example

json

// .cursor/mcp.json or .windsurf/mcp.json
{
  "mcpServers": {
    "posthawk": {
      "command": "npx",
      "args": ["posthawk-mcp"],
      "env": {
        "POSTHAWK_API_KEY": "ck_live_..."
      }
    }
  }
}

SDKhttps://mcp.posthawk.dev/mcp

Posthawk runs a hosted MCP server at mcp.posthawk.dev with full OAuth 2.1 support (PKCE, dynamic client registration, refresh tokens). This is what Claude Code connects to by default.

Example

bash

# Hosted server endpoints
https://mcp.posthawk.dev/mcp                              # MCP endpoint
https://mcp.posthawk.dev/.well-known/oauth-authorization-server  # OAuth metadata
https://mcp.posthawk.dev/health                            # Health check
https://mcp.posthawk.dev/register                          # Dynamic client registration

# Self-hosted HTTP server (for running your own)
MCP_TRANSPORT=http MCP_PORT=3002 npx posthawk-mcp

# OAuth flow:
# 1. Client discovers OAuth metadata
# 2. Registers via /register (dynamic client registration)
# 3. Redirects to app.posthawk.dev/mcp/authorize
# 4. User picks workspace and authorizes
# 5. Client receives access token + refresh token

SDK16 tools

The MCP server exposes 16 tools across 6 categories that AI agents can call. All tools return structured JSON responses.

Example

text

# Emails
send-email          Send an email (immediate or scheduled)
get-email           Check delivery status of a sent email

# Scheduled
list-scheduled      List all scheduled emails
get-scheduled       Get details of a scheduled email
cancel-scheduled    Cancel a pending scheduled email
reschedule-email    Change the delivery time

# Contacts
list-contacts       List contacts with optional tag filter
get-contact         Get a single contact by ID
create-contact      Create a new contact
update-contact      Update contact fields or tags
delete-contact      Delete a contact

# Domains
list-domains        List all verified sending domains
get-domain          Get domain details and DNS status
verify-domain       Trigger domain verification

# Templates
render-template     Render a template with variables

# Webhooks
list-webhooks       List webhook endpoints
create-webhook      Register a new webhook endpoint
delete-webhook      Remove a webhook endpoint

SDK2 resources, 3 prompts

The server also provides MCP resources (live data the agent can read) and prompts (reusable instruction templates).

Example

text

# Resources (read-only data)
posthawk://domains     Summary of all sending domains and their status
posthawk://webhooks    Summary of all webhook endpoints

# Prompts (instruction templates)
draft-email            Guide for composing transactional emails
  args: purpose, tone

debug-deliverability   Step-by-step domain DNS debugging guide
  args: domain

import-contacts        Format guide for bulk contact imports
  args: format (csv | json)

SDKPOSTHAWK_BASE_URL

Point the MCP server at your self-hosted Posthawk instance by setting the base URL environment variable.

Example

json

{
  "mcpServers": {
    "posthawk": {
      "command": "npx",
      "args": ["posthawk-mcp"],
      "env": {
        "POSTHAWK_API_KEY": "ck_live_...",
        "POSTHAWK_BASE_URL": "https://api.yourdomain.com"
      }
    }
  }
}

Error Handling