Billforward

npm version npm downloads

A high-performance Model Context Protocol (MCP) server for integrating Billforward's robust billing and subscription management API with LLMs.

🛠 Features

• Entity Discovery: Quickly list and inspect Accounts and Subscriptions.
• Protocol Purity: Zero log leakage to stdout, ensuring 100% reliable JSON-RPC communication.
• Security First: Built-in BILLFORWARD_READ_ONLY=true (default) mode to protect your data with instructional LLM error rejections.
• Modern SDK: Uses the latest @modelcontextprotocol/sdk signatures (registerTool).
• Fully Testable: Includes protocol compliance and unit tests via Vitest.

🔑 How to Get Your API Token

You need an API token to allow the MCP server to communicate with Billforward.

1. Log in to your Billforward environment.
2. Navigate to Setup > Personal > API Keys.
3. Create a new token and copy it.

Quick Links:

• 🟢 Sandbox Environment API Keys
• 🚀 Production Environment API Keys

---

⚙️ Configuration

To run this server with npx (local or published):

{
  "mcpServers": {
    "billforward": {
      "command": "npx",
      "args": [
        "-y",
        "billforward-mcp"
      ],
      "env": {
        "BILLFORWARD_SANDBOX_ACCESS_TOKEN": "your_sandbox_token",
        "BILLFORWARD_PRODUCTION_ACCESS_TOKEN": "your_production_token",
        "BILLFORWARD_READ_ONLY": "true"
      }
    }
  }
}

Configure whichever environments you have — one or both. When both are set, the LLM must pass environment: "sandbox" or "production" on each call; with only one set it is used automatically.

Advanced Environment Variables

The server behaves differently depending on these configurations:

Variable	Default Value	Description
BILLFORWARD_SANDBOX_ACCESS_TOKEN	(none)	API token for the sandbox environment.
BILLFORWARD_PRODUCTION_ACCESS_TOKEN	(none)	API token for the production environment.
BILLFORWARD_ACCESS_TOKEN	(none)	Legacy single token. Still supported; maps to the environment named by BILLFORWARD_ENVIRONMENT (sandbox if unset).
BILLFORWARD_ENVIRONMENT	sandbox	Legacy — only routes the legacy BILLFORWARD_ACCESS_TOKEN. Ignored once you use the per-environment tokens above.
BILLFORWARD_READ_ONLY	true	When true, POST/PUT actions return instructional error messages to the LLM preventing data mutation.
BILLFORWARD_PRODUCTION_URL	https://app.billforward.net/v1/	Base URL used when environment is production.
BILLFORWARD_SANDBOX_URL	https://app-sandbox.billforward.net/v1/	Base URL used when environment is sandbox.
BILLFORWARD_DEFAULT_RESULTS	10	The default number of results parsed per paginated tool response.
BILLFORWARD_MAX_RESULTS	200	The hard limit cap on how many records the LLM can ask for per tool call.
BILLFORWARD_TIMEOUT	15000	Fallback timeout in milliseconds before failing a stuck Axios request.

🧰 Available Tools

� Search & Insights

• search: Parallelized unified search across Accounts, Subscriptions, and Invoices using email, ID, or keyword.
• get-customer-summary: 360-degree dashboard of a customer (profile, subs, recent invoices, dunning status).
• get-metadata-schema: Analyzes metadata keys in use across Accounts, Subscriptions, and Invoices to help filter queries.

�📖 Guidance

• help: Get an overview of available entities and usage patterns.
• get-me: Validate your connection and view profile metadata.

👥 Accounts

• list-accounts: Fetch a paginated list of accounts (limit, offset, metadata, created_after/created_before).
• get-account: Retrieve full details for a specific UUID.
• get-account-by-email: Find an account quickly by its exact email address.

📝 Subscriptions

• list-subscriptions: Fetch a paginated list of subscriptions (limit, offset, period_start_after/period_start_before — Billforward has no native filter on subscription creation date, so this filters by billing period start instead).
• get-subscription: Retrieve full details for a specific UUID.

🧾 Invoices & Payments

• list-invoices / get-invoice: Fetch invoices and draft details. list-invoices supports period_start_after/period_start_before (same caveat as subscriptions — no native created-date filter exists). Unlike accounts/subscriptions, Billforward doesn't embed invoice metadata in the base payload — get-invoice always fetches it from the dedicated metadata sub-resource; list-invoices fetches it per-invoice only when includeMetadata=true is passed (adds one extra API call per invoice, so keep limit small).
• list-payments / get-payment / list-receipts: Fetch payments, a single payment by ID (including the offline payment justification text in its description field), and receipts. created_after/created_before are supported on the list tools but Billforward has no native date filter on these endpoints, so matches are filtered client-side after fetching sorted by created.

💳 Pricing & Catalog

• list-products: List the main product lines.
• list-product-rate-plans: List specific rate plans (the entities that accounts subscribe to).

🛡 Security

Enable Read-Only Mode by ensuring the environment variable BILLFORWARD_READ_ONLY=true is set (it is true by default for safety). If the LLM attempts to use tools like create-account or update-subscription while Read-Only is active, the operation will be blocked, and the LLM will receive a descriptive error instructing it to inform you that modifications are disabled.

🧪 Development

Build

pnpm run build

Test

pnpm test

Includes a special protocol.test.ts to ensure no third-party package ever leaks logs to the MCP stream again.