API & MCP — Automate Slonge Billing

Slonge Billing ships an official command-line interface (CLI) and an MCP server (Model Context Protocol) for Claude Desktop, Cursor, and Claude Code. With those, you can drive your tenant programmatically or through AI agents — create clients, issue invoices, pull reports — all without clicking through the web UI.

Who is this for?

• CLI users: developers, accountants, or power users who want to automate routine work or embed Slonge into their own scripts.
• AI agent users: anyone using Claude Desktop, Cursor, or Claude Code (or any other MCP-capable agent) who wants to drive Slonge straight from chat — "Create the client Example AG with email …" or "Which invoices are overdue this week?".
• Requirement: the Administrator role in your tenant — only admins can create or revoke API tokens.

5-minute quickstart

Step 1: Create an API token

1. Sign in to Slonge Billing.
2. Open Settings.
3. Switch to the API & MCP tab.
4. Click Create token.
5. Enter a descriptive name (e.g., "Claude Desktop", "CI pipeline").
6. Optionally choose an expiry (30 / 90 / 365 days or "Never").
7. Click Create — the full token appears exactly once. Copy it immediately. After closing the dialog, the cleartext value is gone for good.

Security: Tokens are stored as a SHA-256 hash. Slonge itself can't recover the cleartext after creation. If a token is lost, revoke it and create a new one.

Step 2A: Use the CLI

# One-time: configure
slonge config set api-url https://app.slonge-billing.ch
slonge config set api-token slk_live_YOUR_TOKEN_HERE
slonge config test       # confirms Bearer auth works

# Daily commands
slonge client list
slonge client create --name "Example AG" --email [email protected]
slonge invoice list --status pending --limit 10
slonge invoice create --project-id <id> --amount 1500 --description "Consulting May"
slonge invoice mark-paid <invoice-id>

Global flags (available on every command):

• --json — emit a JSON envelope instead of a table (ideal for scripts)
• --verbose — log HTTP calls to stderr
• --dry-run — validate the input and show the would-be request without sending it

The CLI stores its config at ~/.slonge/config.json (Windows: %USERPROFILE%\.slonge\config.json).

Step 2B: Wire the MCP server into Claude Desktop

1. Add the server to %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

   {
     "mcpServers": {
       "slonge-billing": {
         "command": "node",
         "args": ["<absolute-path>/packages/mcp-server/dist/index.js"],
         "env": {
           "SLONGE_CONFIG_PATH": "<absolute-path>/.slonge/config.json"
         }
       }
     }
   }
   

2. Fully quit Claude Desktop (not just close the window — also the tray icon) and restart it.

3. The chat should show a 🔌 icon with a slonge-billing entry and roughly 20 available tools.

4. Ask in the chat: "List the open invoices in my Slonge tenant" — Claude will call the right tool and show the result inline.

The same steps work in Cursor and Claude Code through their respective MCP configurations.

What you can do

The CLI and the MCP server hit the same API, so functionality is identical.

New tools (Wave 6)

E-invoice (Peppol BIS Billing 3.0)

CLI shortcut:

slonge invoice ubl <id> -o invoice.xml   # write XML to disk
slonge invoice ubl <id>                  # stream XML to stdout

For the full list of MCP tool names (format client_list, invoice_create, etc.), use your MCP client's tools/list call.

Authentication & limits

• Bearer token — every call must send Authorization: Bearer slk_<env>_<token>.
• Tenant-bound — a token knows its tenant; you can't switch tenants on a token. Manage multiple tenants by creating one token per tenant.
• Rate limit — 60 requests per minute per token. Excess requests get 429 Too Many Requests with a Retry-After header.
• Audit log — every call is recorded (timestamp, method, path, status code, latency).

AI quota

Tools that consume OpenAI — currently only expense upload / expense_upload — count toward your plan's monthly AI quota (aiCallsPerMonth).

When the quota is exhausted, the API returns 429 QUOTA_EXCEEDED. Calls against a plan without AI features return 403 FORBIDDEN. The two codes carry distinct meaning — agents can branch between "retry later" (rate limit) and "upgrade plan" (quota).

Error codes

The API always returns the same envelope shape:

{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "...", "details": { } } }

Security & best practices

• Never commit tokens — .gitignore for .env files and ~/.slonge/config.json is mandatory.
• One token per consumer — each CI pipeline, laptop, or agent gets its own token. Revoke individually when a device is lost.
• Use descriptive names — the token's name appears in the audit log and overview; "Claude Desktop — Ben's laptop" beats "Token 1".
• Revoke on suspicion — revocation is immediate and irreversible.
• Use expiry dates — for temporary integrations (a one-off migration run, say) prefer 30 days over "Never".

Streamable HTTP Transport

Alongside the local slonge-mcp (stdio) binary, Slonge Billing exposes a hosted MCP endpoint:

POST https://app.slonge-billing.ch/api/mcp
Authorization: Bearer slk_...
Accept: application/json, text/event-stream

Connect compatible clients (claude.ai, ChatGPT, Cursor with remote-MCP support) directly to this URL — no install needed. The same API tokens work over stdio and HTTP.

Next steps

• Create a token: Settings → API & MCP
• Contact us at [email protected] with setup questions or requests for additional MCP tools.

For developers: The official SDK is @slonge/agent-sdk and contains Zod schemas plus a typed HTTP client. It lives alongside the CLI and the MCP server in the Slonge Billing monorepo.