AI agents (MCP)

Give an AI assistant safe, scoped access to Hellio. The official Model Context Protocol (MCP) server exposes the whole API as tools an agent can call: SMS, OTP, voice, number lookup, email verification, balance and pricing, webhooks and the full USSD suite.

MCP is an open standard for connecting AI applications to external systems. Point an MCP client such as Claude Desktop, Claude Code or Cursor at the Hellio server and the assistant can, for example, check your balance, estimate the cost of a campaign, send a one-time passcode, or simulate a USSD flow, all through your own token.

Install

Runs locally over stdio. Needs Node.js 18 or newer.

The server is published on npm. You do not need to clone anything; your MCP client launches it on demand with npx.

npx -y @helliosolutions/mcp-server

It reads two environment variables:

HELLIO_API_TOKEN=your-token-here
# optional, defaults to the production API
HELLIO_API_BASE_URL=https://api.helliomessaging.com/v1

Create a scoped token in your dashboard under Settings, then API Keys & Webhooks. The token's abilities decide which tools succeed, so an agent can only do what you granted.

Connect Claude Desktop

Add one entry to your MCP config, then restart.

Open Settings, Developer, Edit Config and add the server:

{
  "mcpServers": {
    "hellio": {
      "command": "npx",
      "args": ["-y", "@helliosolutions/mcp-server"],
      "env": {
        "HELLIO_API_TOKEN": "your-token-here"
      }
    }
  }
}

Restart Claude Desktop. The Hellio tools appear in the tools menu, and you can ask things like "what's my Hellio balance?" or "send an OTP to +233241234567".

Connect Claude Code

One command registers the server.

claude mcp add hellio \
  --env HELLIO_API_TOKEN=your-token-here \
  -- npx -y @helliosolutions/mcp-server

Tools

28 tools, one per API operation. Read-only tools are safe to call freely.

• Account: hellio_get_balance, hellio_get_pricing.
• SMS: hellio_send_sms, hellio_list_messages, hellio_get_message, hellio_list_campaigns, hellio_get_campaign.
• OTP: hellio_send_otp, hellio_verify_otp.
• Voice: hellio_send_voice.
• Lookup and email: hellio_lookup_numbers, hellio_verify_email.
• Webhooks: hellio_list_webhooks, hellio_create_webhook.
• USSD: pricing and availability, app create/update/delete, mode switch and secret rotation, extension rent/release, session listing and detail, and sandbox hellio_ussd_simulate.

Safety

The server is built for agents that can charge your account.

• Clear intent: every billable tool (send SMS, OTP, voice, number lookup, email verification, rent extension) starts its description with "Deducts from your wallet balance" (or USSD balance), so a well-behaved client can confirm before calling it.
• No double charges: sends attach an Idempotency-Key automatically, so a retried call replays the original response instead of billing twice.
• Scoped by token: the agent can only reach the abilities on the token you give it. A 403 or insufficient-scope error means the token lacks that ability. See Authentication for scopes and idempotency.
• Read and write hints: each tool is annotated (read-only or destructive) so clients can gate the risky ones.

Prefer to write code?

MCP is for AI agents. If you are building an application, use one of the SDKs or call the REST API directly. The MCP server is a thin wrapper over that same API, so anything an agent can do, your code can too.