Billforward MCP Server

This MCP server connects LLMs to Billforward through a small always-on tool surface: lookup resolves prefixed IDs and free-text search, while search-tools, describe-tool, and call-api discover and execute operations from an in-package API catalog—covering the full API without registering hundreds of per-endpoint tools.

flowchart LR
  Model --> AlwaysOn
  AlwaysOn --> Lookup
  AlwaysOn --> ToolSearch
  AlwaysOn --> Help
  ToolSearch -->|"matches"| Catalog
  Catalog --> Describe
  Describe --> Call
  Lookup -->|"PREFIX-id"| GetById
  Lookup -->|"email/texto"| SearchV3

Configuration

Primary config: BILLFORWARD_ENVIRONMENTS — a JSON object of named environments (lowercase slugs you choose). Each entry needs token and type (sandbox or production); readonly defaults to true (only JSON false enables writes). Optional baseUrl overrides the default for that type.

BILLFORWARD_ENVIRONMENTS='{"dev":{"token":"your_dev_token","type":"sandbox","readonly":true},"staging":{"token":"your_staging_token","type":"sandbox","readonly":true},"prod":{"token":"your_production_token","type":"production","readonly":true}}'

With one environment configured, tools select it automatically. With two or more, pass the exact name via each tool's environment parameter.

Create a local .env from the template and keep every environment read-only until writes are explicitly needed:

cp .env.example .env

BILLFORWARD_ENVIRONMENTS='{"dev":{"token":"your_dev_token","type":"sandbox","readonly":true},"staging":{"token":"your_staging_token","type":"sandbox","readonly":true},"prod":{"token":"your_production_token","type":"production","readonly":true}}'
BILLFORWARD_TIMEOUT=15000

MCP client setup

.mcp.json (loads .env from workspace root):

{
  "mcpServers": {
    "billforward": {
      "command": "bash",
      "args": ["-lc", "set -a; source .env; set +a; exec npx -y billforward-mcp"]
    }
  }
}

VS Code / Cursor (.vscode/mcp.json):

{
  "servers": {
    "billforward": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "billforward-mcp"],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

Inline env (when the client does not load env files):

{
  "mcpServers": {
    "billforward": {
      "command": "npx",
      "args": ["-y", "billforward-mcp"],
      "env": {
        "BILLFORWARD_ENVIRONMENTS": "{\"dev\":{\"token\":\"your_dev_token\",\"type\":\"sandbox\",\"readonly\":true},\"staging\":{\"token\":\"your_staging_token\",\"type\":\"sandbox\",\"readonly\":true},\"prod\":{\"token\":\"your_production_token\",\"type\":\"production\",\"readonly\":true}}"
      }
    }
  }
}

How to Get Your API Token

1. Log in to your Billforward environment.

2. Go to Setup > Personal > API Keys.

3. Create a token and copy it.

• Sandbox API Keys

• Production API Keys

Available Tools

Discovery (always on)

Typical flow: lookup for IDs and text search → search-tools → describe-tool → call-api for lists and writes.

Convenience

Upgrading to 2.0

Version 2.0 replaces per-endpoint tools with discovery-first tools. Ops are unchanged (npx billforward-mcp + env tokens).

Full changelog: CHANGELOG.md on GitHub

Security

Named environments default to read-only (readonly: true). Only set "readonly": false for environments that should allow writes.

When read-only is active, write catalog entries (create-account, update-subscription, etc.) are blocked with a descriptive error.

Development

pnpm run build
pnpm test