Build a local Agent / MCP integration

The SendAfrica Agent is a local MCP server and CLI that gives AI coding assistants direct access to the SendAfrica API. Run it on the developer’s machine or behind your own trusted service boundary. Never expose API keys to the public internet or embed them in browser code.

Source: github.com/SendAfrica/AGENT Full docs: docs-agent.sendafrica.online

Install and run

From the agent repository:


git clone https://github.com/SendAfrica/AGENT.git
cd AGENT
uv sync
export SENDAFRICA_API_BASE=https://api.sendafrica.online/v1
export SENDAFRICA_API_KEY=SA-your-key
uv run sendafrica-agent mcp

MCP client configuration

For a desktop MCP client (Claude Desktop, VS Code, etc.), configure a local stdio process using an environment variable so the key is never written into the JSON file:


{
  "mcpServers": {
    "sendafrica": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/AGENT", "sendafrica-agent", "mcp"],
      "env": {
        "SENDAFRICA_API_KEY": "${SENDAFRICA_API_KEY}"
      }
    }
  }
}

Adjust --directory to the location where you cloned the agent.

Tools provided

Once connected, the agent exposes a set of tools to the model. Use sendafrica-agent --help or consult the docs at docs-agent.sendafrica.online for the full tool list. Common tools include:

SMS sending and logging — send messages, check delivery status
Credit balance and history — inspect credits before sending
Rate lookup — check country-specific rates
Contact list management — list, create, import contacts
Sender ID operations — list, check requirements, submit requests

Safe operating rules

Inspect first. Before performing a bulk or campaign send, have the agent preview the affected contacts and message content.
Confirm in your own UI. The agent should present what it is about to do and wait for an explicit human confirmation before any mutating action.
Keep credentials in the environment. Use SENDAFRICA_API_KEY and SENDAFRICA_API_BASE in the process environment; never write the key into a config file or JSON.
Do not expose MCP over the network without your own authentication and authorization layer.
Log request IDs, not secrets. Persist the request_id returned on every API response. Never log API keys, webhook secrets, or raw bearer tokens.
Use JSON output everywhere. When calling the CLI from the same agent workflow, always pass -o json and never parse the default table format.

API compatibility

The agent’s tool surface is a thin wrapper around the public SendAfrica REST API documented on this site. The public developer surface is the source of truth: see the API reference, SMS API, and Webhooks.

Internal agent architecture, model gateways, provider routes, and operational service credentials are intentionally not documented.