Guide to using agents with the HostAfrica API

Three ways to interact with the HostAfrica API - compare costs, flexibility, and the right fit for your workflow before you commit to a path.

Choosing an approach

This guide compares three ways to interact with the HostAfrica API:

• Method 1: Agent uses MCP tools - the agent calls structured MCP tools that map directly to API operations.
• Method 2: Agent uses CLI (ha) - the agent runs the HostAfrica ha CLI tool and pipes output through jq to filter responses.
• Method 3: Direct HTTP API - you (or your code) call the REST API directly with curl or an HTTP client.

Methods 1 and 2 involve an AI agent doing the work - you still interact in plain language. Method 3 puts you in direct control, with no agent in the loop.

MCP is the simpler path for agent use: configure the MCP server with your token, and the agent has immediate access to all operations through structured tools with built-in parameter guidance. It works out of the box with no shell access required. The trade-off is that every tool response returns the full API payload, which is fed into the agent's context window verbatim - some responses are large regardless of how simple the query is. This increases LLM token consumption and therefore the cost of running the agent.

CLI gives the agent more control: it runs ha subcommands and can filter responses with jq before they reach its context, significantly reducing token usage. It also isn't constrained by fixed tool schemas, so it can work around API limitations more easily. The trade-off is that the agent needs shell access, a good understanding of the ha subcommands, and explicit instruction to filter responses - without that, the cost advantage disappears.

Direct API is the most flexible option. No agent, no CLI - you send HTTP requests and receive JSON responses. Best for scripting, CI pipelines, or integrating with your own tooling.

For most users managing a small number of servers, MCP is the easiest starting point. For cost-conscious or high-frequency agent use, the CLI approach with response filtering is substantially cheaper. For automation and integration work, the direct API gives you full control.

Method 1: Agent via MCP tools

The agent uses pre-defined tools, one per API operation. Each tool call returns the full API response regardless of what the agent actually needs.

Setup

Configure the MCP server in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "hostafrica-api": {
      "type": "http",
      "url": "https://api.hostafrica.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Open Cursor and describe what you want in plain language - the agent handles the rest. For the full connection walkthrough, see Connecting to the API with MCP.

Example interactions

Ordering a new VPS:

User: Create a C3 VPS with Ubuntu 24.04, hostname myserver.co.za
Agent: [calls get_catalogue] -> resolves plan and config IDs
Agent: [calls validate_pricing] -> confirms pricing with user
Agent: [calls create_order] -> order placed

Listing firewall rules:

User: List my firewall rules
Agent: [calls list_firewall_rules]
-> Returns full JSON including 90+ macros, 80+ protocols, and available interfaces
   regardless of whether any rules exist

Pros

• No API knowledge required - tool schemas guide the agent; less chance of malformed requests.
• No shell access required - works in sandboxed or restricted environments.
• Structured error handling - tool errors are typed responses the agent can reason about.
• Discoverable - the agent can enumerate available tools without prior knowledge.

Cons

• Large response payloads - tools always return full API responses; metadata like macros and protocols lists is fed into model context verbatim even when irrelevant.
• No response filtering - the agent receives everything the API returns, not just what it needs.
• Fixed tool schemas - some tools only expose a subset of fields (for example, update_firewall_rule only accepts pos, comment, and rule_action); this reflects the underlying API, not an MCP limitation.

Method 2: Agent via CLI (ha)

The HostAfrica CLI is a command-line tool with one subcommand per API operation. Install it from the ha-cli repository, then configure your credentials:

export HA_SERVER=https://api.hostafrica.com
export HA_TOKEN=<your-bearer-token>

The agent runs ha commands via its shell tool and pipes output through jq to extract only what it needs.

Example interactions

Ordering a new VPS:

User: Create a C3 VPS with Ubuntu 24.04, hostname myserver.co.za
Agent: [runs ha get-catalogue | jq '...plan and option IDs only...']
Agent: [runs ha create-order --products '[...]']
-> Order placed

Listing firewall rules:

User: List my firewall rules
Agent: [runs ha list-firewall-rules --service_id 3893 | jq '.data.rules']
-> Returns: [] - macros and protocols metadata discarded

These are the commands the agent constructs and runs. You can run them yourself too - the CLI is a first-class tool, not just for agent use.

Pros

• Full response control - the agent filters with jq; irrelevant metadata never reaches the context window.
• More flexible - the agent can combine calls, loop over results, and build reusable scripts.
• Works around tool limitations - the agent isn't constrained by fixed tool schemas.
• Scriptable - the agent can produce scripts the user saves and runs independently.

Cons

• Requires shell access - doesn't work in restricted or sandboxed environments.
• Requires a shell invocation to discover commands - unlike MCP tools, which are enumerated at session start, the agent must run ha --help to discover subcommands; this is self-contained but adds a small overhead on first use.
• No schema guardrails - parameter validation happens at the API level; errors are less descriptive.

Method 3: Direct HTTP API

The HostAfrica REST API is available at https://api.hostafrica.com. You can call it directly with any HTTP client - no agent, no CLI required. This is the most suitable approach for scripts, CI pipelines, and custom integrations.

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer <your-token>

Example requests

List VPS services:

curl -s -X POST https://api.hostafrica.com/vps/list-vps-services \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"service_id": 3893}'

Explore the full API reference for more details.

Pros

• No agent required - full control with standard HTTP tools; no LLM costs.
• No CLI to install - works anywhere curl or an HTTP library is available.
• Best for automation - easily integrated into scripts, CI pipelines, and backend services.
• Precise requests - you control exactly what is sent and received; no intermediary layer.

Cons

• No natural language interface - you need to know the endpoints, parameters, and request format.
• No guardrails - errors are raw HTTP responses; you handle validation yourself.
• More verbose - each request requires headers, URL construction, and JSON encoding.

Reducing token usage

The CLI approach significantly reduces token usage because the agent filters API responses before they enter its context window. MCP tools always return the full response. However, the agent should actively filter responses with jq before they enter its context. This doesn't happen automatically - the agent must be instructed to do so, either via an explicit user instruction, the system prompt, or your AGENTS.md file. Without filtering guidance, an agent running ha list-firewall-rules without jq will receive the full response just like MCP, making the costs comparable.

To realise the CLI cost advantage, add guidance like this to your AGENTS.md:

When using the ha CLI, always pipe responses through jq and extract only the fields
relevant to the task. Never return raw full API responses to context.

A note on tool schema caching

Cursor and most LLM providers cache repeated tool schema tokens, so the roughly 50 MCP tool definitions (around 7-10k tokens) are billed at a steep discount on repeat calls. This reduces cost but not context window usage - those tokens are still consumed on every request.

Caching only covers the schemas themselves, not the data returned by tool calls. Response payloads (like the macros and protocols list from list_firewall_rules) are always billed at full rate. The cost comparison above reflects response payload costs, which caching does not affect.

Tips to reduce token usage when using MCP

• Pre-populate AGENTS.md with known plan IDs and config option IDs to skip catalogue lookups.
• Use specific prompts - providing IDs directly (for example, plan_id 302, config options 21:26, 22:30) avoids a get_catalogue call.
• Batch operations - combine multiple instructions in one message rather than separate turns.

Recommendation

MCP is the simplest agent path. However, the CLI approach uses 90%+ fewer tokens on response payloads by filtering before they enter the context window, making it significantly more cost-effective for regular agent use. The direct API skips the agent entirely - no token costs at all - and is the right choice for scripts, pipelines, and integrations where you don't need natural language interaction.

For general support and feedback, submit a query through your client area.