Reporting 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 reports:read

https://simcloud.co.za/api/reporting-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-reporting --url https://simcloud.co.za/api/reporting-mcp.php
codex mcp login simcloud-reporting --scopes reports:read

On simcloud.co.za, sign in and approve reports:read. 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-reporting. Choose a user configuration for personal access, or your workspace when the team needs the same server definition.

{
    "servers": {
        "simcloud-reporting": {
            "type": "http",
            "url": "https://simcloud.co.za/api/reporting-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-reporting. Choose your user settings or the intended workspace.

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

Start SIMcloud from MCP: List Servers. Complete the browser sign-in and approve reports:read. 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-reporting https://simcloud.co.za/api/reporting-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 reports:read. 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-reporting": {
            "url": "https://simcloud.co.za/api/reporting-mcp.php"
        }
    }
}

Open Cursor’s MCP settings, enable this server and connect when prompted. Complete SIMcloud sign-in, check the reports:read 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-reporting": {
            "serverUrl": "https://simcloud.co.za/api/reporting-mcp.php"
        }
    }
}

In Antigravity, open /mcp and reload the configuration. Select SIMcloud, choose Authenticate and complete SIMcloud sign-in. Review reports:read, 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-reporting https://simcloud.co.za/api/reporting-mcp.php

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

Open gemini and run /mcp auth simcloud-reporting. Complete SIMcloud sign-in and approve reports:read. 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 7 reporting tools and no purchase or send tools. Try a transaction history query with a specific date range of at most 90 days, or check an existing order that belongs to your account.

Query reports and order status

Ask for a specific report, then let your AI call the relevant tools. Reporting stays within the connected account and excludes voucher PINs and electricity tokens.

• Account overview: “Check my SIMcloud wallet balance and show transactions for the last seven days.”
• Transaction review: “List my data transactions for October, including the amount, reference and outcome. Follow all result pages.” Use date ranges of no more than 90 days per request.
• Order follow-up: “Check the current status of this existing airtime order.” Supply the order identifier or reference supported by the tool. Order queries are restricted to your account.

The seven tools are get_wallet_balance, get_transaction_history, get_airtime_order, get_data_order, get_sms_status, get_vas_order and get_electricity_order. To create an order or send a message, use the separate transaction connection.

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