Transaction setup

Before you start

You need a SIMcloud account and a current version of your chosen client with remote HTTP MCP and OAuth support. Your client subscription or organisation policy may affect tool availability.

Server URL · permission api

https://simcloud.co.za/api/mcp.php

Use one connection per permission level. Merge the configuration below into your existing settings; keep any other servers you already use.

01 · Setup guide

Codex

Run these commands in a terminal on the computer where you use Codex. They add a named remote connection, then start the SIMcloud browser sign-in.

codex mcp add simcloud-transactions --url https://simcloud.co.za/api/mcp.php
codex mcp login simcloud-transactions --scopes api

On simcloud.co.za, sign in and approve api. Return to Codex, then run codex mcp list. Open a new conversation or reconnect the server if your current conversation still has the old tool list.

Codex uses its MCP configuration across the CLI and IDE extension. In the desktop app, use the same server URL in MCP settings and reconnect after signing in. The Codex extension for VS Code uses this Codex setup; GitHub Copilot uses the separate VS Code setup below.

Reference: OpenAI MCP setup documentation.

02 · Setup guide

VS Code + GitHub Copilot

In VS Code, run MCP: Add Server from the Command Palette. Choose an HTTP server, enter the URL above and name it simcloud-transactions. Choose a user configuration for personal access, or your workspace when the team needs the same server definition.

{
    "servers": {
        "simcloud-transactions": {
            "type": "http",
            "url": "https://simcloud.co.za/api/mcp.php"
        }
    }
}

Start the server from MCP: List Servers, complete browser sign-in and review the SIMcloud consent screen. In a chat that supports tools, enable the SIMcloud tools and try the balance query below. If you use a Copilot harness, follow the destination offered by the guided flow; its portable configuration differs from the VS Code JSON shown here.

Reference: VS Code MCP setup and configuration reference.

GitHub Copilot in VS Code

GitHub Copilot

Sign in to GitHub Copilot in VS Code with an account that can use agent tools. In the Command Palette, run MCP: Add Server, select HTTP, enter the SIMcloud server URL and name it simcloud-transactions. Choose your user settings or the intended workspace.

{
    "servers": {
        "simcloud-transactions": {
            "type": "http",
            "url": "https://simcloud.co.za/api/mcp.php"
        }
    }
}

Start SIMcloud from MCP: List Servers. Complete the browser sign-in and approve api. Open Copilot chat, select an agent with tool access and enable the SIMcloud tools. Ask it to check your wallet balance, then approve that tool request.

Keep purchase and message approvals enabled. If your organisation manages Copilot, its administrator must allow MCP servers. The Codex extension has separate settings and uses the Codex guide.

Reference: GitHub Copilot and MCP in VS Code.

03 · Setup guide

Claude Code

Add a remote HTTP server for your user account:

claude mcp add --transport http --scope user simcloud-transactions https://simcloud.co.za/api/mcp.php

Open Claude Code and run /mcp. Select this server and follow the authentication prompt. Sign in on SIMcloud and check that the consent screen grants api. Return to Claude Code and enable the connection.

Reference: Claude Code MCP documentation.

04 · Setup guide

Cursor

Add this entry to ~/.cursor/mcp.json for your user, or .cursor/mcp.json for a project:

{
    "mcpServers": {
        "simcloud-transactions": {
            "url": "https://simcloud.co.za/api/mcp.php"
        }
    }
}

Open Cursor’s MCP settings, enable this server and connect when prompted. Complete SIMcloud sign-in, check the api permission and return to the editor. In Agent chat, enable the SIMcloud tools and approve the first balance request when prompted. Connecting the server and approving a tool call are separate steps. Keep approval prompts enabled for tools that take action.

Reference: Cursor MCP documentation.

Google Antigravity CLI

Install Antigravity CLI from Google’s installation guide, run agy and sign in. Add this server to ~/.gemini/config/mcp_config.json for your user, or .agents/mcp_config.json for a workspace:

{
    "mcpServers": {
        "simcloud-transactions": {
            "serverUrl": "https://simcloud.co.za/api/mcp.php"
        }
    }
}

In Antigravity, open /mcp and reload the configuration. Select SIMcloud, choose Authenticate and complete SIMcloud sign-in. Review api, then copy the displayed authorisation code into Antigravity when prompted. After authentication succeeds, return to the MCP panel and ask for your wallet balance. Approve the individual tool request.

The server uses Streamable HTTP. Keep tool permissions set to ask before purchases or messages. Antigravity App and IDE also support remote MCP; their setup screens are described in Google’s documentation.

Reference: Antigravity MCP configuration and authentication.

Gemini CLI

Gemini CLI requires a paid Gemini API key or an eligible Code Assist Standard/Enterprise account for model requests. For personal Google-account access, use Antigravity CLI. Install and authenticate Gemini CLI using Google’s instructions, then add SIMcloud:

gemini mcp add --transport http --scope user simcloud-transactions https://simcloud.co.za/api/mcp.php

{
    "mcpServers": {
        "simcloud-transactions": {
            "type": "http",
            "url": "https://simcloud.co.za/api/mcp.php"
        }
    }
}

Open gemini and run /mcp auth simcloud-transactions. Complete SIMcloud sign-in and approve api. Use /mcp to view the tools, then ask for your wallet balance and approve the request. Keep tool confirmations enabled.

Reference: Gemini CLI MCP and OAuth documentation.

Your first request: check your balance

Ask: “Use SIMcloud to check my wallet balance. Do not place any orders.” Confirm that your client actually calls get_wallet_balance and returns the result. A saved server entry alone does not confirm a working connection.

You should see 17 tools, including reporting and transaction tools. Before spending, ask for the available products or a network lookup, then confirm the final recipient, product and amount. Validate an electricity meter before buying. A queued order is not a delivery confirmation.

Place an order and check its status

Transaction access includes reporting and the tools needed to look up services and submit actions. A clear instruction should distinguish preparation from permission to spend.

1. Prepare the details

   Check the wallet balance. Look up an unknown mobile network. List current data or voucher products, or check the electricity meter. Ask the AI to show the final recipient or meter, product, amount and reference.

2. Confirm the action

   Approve the specific purchase or message. For SMS, review both the recipient and the final text. For account registration, obtain the person’s consent before providing their information.

3. Follow the outcome

   Keep the returned order or request identifier and use its status tool. Pending or queued is not delivered. If a submission times out, query the original reference before considering another purchase.

Example: “Find the available data bundles for this recipient’s network. Show me the product, price and recipient, then wait for my confirmation before ordering.”

See the complete tool reference for the 17 tools, or use the REST API for scheduled application workflows.

Connection troubleshooting

“Couldn’t connect” or authentication failed

Check the exact URL, update your client and reconnect. Complete the SIMcloud consent screen. If switching from reporting to transactions, add the separate connection above and authorise its permission.

Signed in, but no tools appear

Enable the server in your client and refresh its tool list or start a new conversation. In VS Code, use MCP: List Servers to inspect the server output. Organisation policies may block external tools.

Reporting asks for transaction access

Cancel consent. Check that you used /api/reporting-mcp.php and reports:read. Do not approve broader access to make a reporting connection work.

Stop an app accessing your account

Open Connected Apps on SIMcloud and revoke the OAuth connection. Removing a server entry from your editor alone does not revoke its access.

Still stuck? Email customercare@freepaid.co.za with the client name and version, server URL, approximate time and error message. Remove tokens, passwords, OTPs and full OAuth callback URLs before sharing logs.

Privacy notice · Terms · Developer reference