MCP Server

The MailAfrica MCP server exposes 20 tools over the Model Context Protocol, letting AI assistants manage your email programmatically.

How It Works

The MCP server runs as a stdio transport — no network listener. Your AI assistant (Claude Desktop, Cursor, etc.) spawns the process and communicates through stdin/stdout. This means:

• No open ports — the server is only accessible to the MCP client that launched it
• Secure by default — no authentication needed beyond who can execute the process
• Works locally — runs on your machine, talking to MailAfrica’s API over HTTPS

Starting the Server

uv run mailafrica-agent mcp

This starts the FastMCP server, reads your .env file for credentials, and waits for tool calls from the connected AI assistant.

Tool Categories

The 20 tools are organized into 6 categories:

Outbound Email

send_email

Send an email through MailAfrica. Optionally specify a verified sending domain.

send_email(
    to=["recipient@example.com"],
    subject="Hello from MailAfrica",
    text_body="This is a plain text email.",
    html_body="<p>This is an HTML email.</p>",
    cc=["cc@example.com"],
    bcc=["bcc@example.com"],
    from_domain_id=1,
    from_address="you@yourdomain.com"
)

Parameters:

list_outbound_emails

List recent outbound emails.

list_outbound_emails(limit=20)

get_outbound_email

Fetch a single outbound email by its ID.

get_outbound_email(message_id=123)

Inbound Email

list_inbound_addresses

List all receiving email addresses on your account.

list_inbound_addresses()

create_inbound_address

Create a new inbound email address.

create_inbound_address(local_part="support", label="Customer Support")

delete_inbound_address

Remove a receiving address.

delete_inbound_address(address_id=5)

list_inbound_messages

List messages received at an address.

list_inbound_messages(address_id=1, unread=True, limit=20)

get_inbound_message

Fetch the full content of an inbound message.

get_inbound_message(message_id=456)

Returns the message with headers, body, sender, subject, and timestamps.

Sending Domains

list_sending_domains

List all registered sending domains with their verification status and DNS records.

list_sending_domains()

add_sending_domain

Register a new sending domain. Returns the DNS records (DKIM, CNAME) you need to publish.

add_sending_domain(domain="yourdomain.com")

verify_sending_domain

Re-check DNS records with ZeptoMail to verify domain setup.

verify_sending_domain(domain_id=2)

Webhooks

list_webhooks

List webhooks configured on an inbound address.

list_webhooks(address_id=1)

create_webhook

Create a signed webhook on an address.

create_webhook(
    address_id=1,
    url="https://your-server.com/webhooks/mailafrica",
    secret="your_webhook_secret"
)

delete_webhook

Remove a webhook.

delete_webhook(webhook_id=3)

test_webhook

Trigger a test ping to a webhook endpoint.

test_webhook(webhook_id=3)

Agent & Auto-Reply

agent_config

Configure auto-reply behavior for an inbound address.

agent_config(
    address_id=1,
    mode="auto",
    persona="You are a friendly support agent for Acme Corp.",
    reply_from_domain_id=2,
    reply_from_address="support@acme.com"
)

Modes:

• auto — Generate and send replies automatically
• draft — Generate replies but don’t send (review first)
• off — Disable auto-reply

agent_get_config

Fetch the current auto-reply config for an address.

agent_get_config(address_id=1)

agent_status

Show the auto-reply status for all configured addresses.

agent_status()

agent_draft

Generate a one-off draft reply without sending. Useful for testing.

agent_draft(
    address_id=1,
    subject="Re: Meeting request",
    text_body="Hi, thanks for your message. Let me check my calendar..."
)

agent_handle_message

Manually trigger the auto-reply pipeline for a specific inbound message.

agent_handle_message(message_id=789, address_id=1)

Billing & Info

wallet_balance

Check your current MailAfrica wallet balance in TZS.

wallet_balance()

list_models

List available LLM models from the Ngamia gateway.

list_models()

Connecting from Different Clients

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mailafrica-agent": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/MailAfrica-Agent",
        "mailafrica-agent",
        "mcp"
      ]
    }
  }
}

Claude Code

Add to your MCP configuration:

{
  "mcpServers": {
    "mailafrica-agent": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/MailAfrica-Agent",
        "mailafrica-agent",
        "mcp"
      ]
    }
  }
}

Cursor

Add via Settings > MCP > Add new global MCP server:

{
  "mailafrica-agent": {
    "command": "uv",
    "args": [
      "run",
      "--directory",
      "/path/to/MailAfrica-Agent",
      "mailafrica-agent",
      "mcp"
    ]
  }
}

Other MCP Clients

Any client that supports the MCP stdio transport can connect by running:

uv run --directory /path/to/MailAfrica-Agent mailafrica-agent mcp