Bitrefill Service Interface Gateway

This TypeScript implementation functions as an MCP backend, exposing Bitrefill functionalities for consumption by advanced conversational models. It translates abstract LLM requests into concrete API calls against the Bitrefill platform.

Operational Flow

The server adheres strictly to the Model Context Protocol (MCP) for synchronous interaction with assistants like Claude. Key operational steps include:

1. Execution Environment: Runs as an isolated process, utilizing standard input/output streams for command and response exchange.
2. Interface Registration: Declares available endpoints (Resources) and actionable functions (Tools) compatible with the MCP specification.
3. External Interaction: Bridges internal logic with the proprietary Bitrefill Application Programming Interface (API) for data retrieval and transaction initiation.
4. Data Serialization: Ensures all outbound data conforms to strict JSON schemas required for reliable agent interpretation.

Internal Structure Overview

src/ ├── index.ts # Primary launch module ├── constants/ # Immutable configuration constants │ ├── categories.ts # Taxonomy definitions │ └── payment_methods.ts # Accepted payment rails ├── handlers/ # MCP message processing logic │ ├── resources.ts # Handling resource path resolution │ └── tools.ts # Tool method execution proxies ├── schemas/ # JSON schema definitions for I/O validation │ ├── detail.ts # Product specification response formats │ ├── invoice.ts # Transaction initiation/settlement schemas │ ├── misc.ts # Auxiliary type definitions │ ├── order.ts # Fulfillment record schemas │ └── search.ts # Query parameters and results structures ├── services/ # Core business logic layer interfacing with external APIs │ ├── invoices.ts # Invoice management routines │ ├── misc.ts # Utility API interactions │ ├── orders.ts # Order lifecycle functions │ ├── products.ts # Product catalog lookup service │ └── search.ts # Catalog querying engine └── utils/ # Supporting components ├── index.ts # Global utilities (e.g., centralized error logging) └── api/ # Bitrefill API client implementations ├── authenticated.ts # Credentialed API client ├── base.ts # Core request abstraction └── public.ts # Unauthenticated API client access

Exposed Capabilities (Tools & Resources)

Discoverable Resources

• bitrefill://product-types - Enumeration of all broad asset classifications supported.
• bitrefill://categories/{type} - Detailed breakdown of segments within a given asset type (e.g., bitrefill://categories/gift-cards).

Functional Tools

• search - Locates available items (e.g., digital gift certificates, mobile reload packs).
• Mandatory: query (Search term, e.g., 'Steam', 'Lyft', or '*' for exhaustive listing)

• Optional Filters: country, language, limit, skip, category

• detail - Retrieves comprehensive specifications for a singular identified product.

• Mandatory: id (Unique product identifier)

• categories - Fetches the comprehensive, nested mapping of all product classifications.

• Mandatory: None

• create_invoice - Initiates a purchase order draft. (Requires API authentication)

• Mandatory: products (An array detailing desired items)
  • Each item requires: product_id
  • Per-item customization options: quantity, value, package_id, phone_number, email, send_email, send_sms
• Mandatory: payment_method (Selection from: "balance", "bitcoin", "lightning")

• Optional: webhook_url, auto_pay

• get_invoices - Queries the history of generated transaction manifests.

• Optional Filters: start, limit, after, before

• get_invoice - Fetches the current status of a specific transaction manifest.

• Mandatory: id (Invoice identifier)

• pay_invoice - Executes payment on an outstanding invoice. (Only functions when using the 'balance' rail).

• Mandatory: id (Invoice identifier)

• get_orders - Retrieves records of successfully fulfilled transactions.

• Optional Filters: start, limit, after, before

• get_order - Views specifics for a single completed fulfillment record.

• Mandatory: id (Order identifier)

• unseal_order - Reveals sensitive fulfillment data (e.g., digital codes) for a finalized order.

• Mandatory: id (Order identifier)

• get_account_balance - Reports the current usable balance on the associated API account.

• Mandatory: None

• ping - Health check to confirm external API connectivity.

• Mandatory: None

Environment Configuration

API Credential Provisioning

Authentication tokens are necessary for accessing transactional methods (create_invoice, pay_invoice, order lookups, etc.). Public catalog access requires no credentials.

1. Secure a developer key pair via the official Bitrefill developer request channel.
2. Establish a .env configuration file in the root directory (a template exists as .env.example).
3. Inject your credentials:

BITREFILL_API_SECRET=your_secret_key_here BITREFILL_API_ID=your_api_identifier_here

The system dynamically loads these values; if absent, tools relying on them will be deactivated during registration.

Maintenance and Deployment

Dependency Installation

bash npm install

Compilation

bash npm run build

Development Loop (Watch Mode)

bash npm run watch

Diagnostic Procedures

Debugging over stdio channels can be complex. We strongly endorse utilizing the specialized MCP Inspector, accessible via a dedicated script:

bash npm run inspector

Running this command will yield a local URL allowing access to interactive debugging visualization tools within a web browser.

Integration Guides

Smithery Automated Setup

Install this Bitrefill integration directly into your Claude Desktop environment using the Smithery CLI:

bash npx -y @smithery/cli install @bitrefill/bitrefill-mcp-server --client claude

Claude Desktop Client Configuration

Modify the configuration file located at: - MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%/Claude/claude_desktop_config.json

Inject the following server block:

{ "mcpServers": { "bitrefill": { "command": "npx", "args": ["-y", "bitrefill-mcp-server"], "env": { "BITREFILL_API_SECRET": "your_api_key_here", "BITREFILL_API_ID": "your_api_id_here" } } } }

Cline Extension

1. Navigate to Cline Extension Settings.
2. Select the "MCP Servers" tab.
3. Choose "Configure MCP Servers".
4. Insert the server configuration:

{ "mcpServers": { "github.com/bitrefill/bitrefill-mcp-server": { "command": "npx", "args": ["-y", "bitrefill-mcp-server"], "disabled": false, "autoApprove": ["search", "detail", "categories"], "env": { "BITREFILL_API_ID": "your_api_id_here", "BITREFILL_API_SECRET": "your_api_key_here" } } } }

Cline Additional Parameters: - disabled: Set to false for activation. - autoApprove: List of tools exempt from per-use manual confirmation.

Cursor Editor Integration

1. Access Cursor Settings.
2. Open the "Features" panel.
3. Locate the "MCP Servers" section and select "Add new MCP Server".
4. Assign a unique name and set the "Type" to "command".
5. Specify the execution instruction:

npx -y bitrefill-mcp-server

1. (Optional) For activating transactional capabilities, populate the environment variables section:
2. BITREFILL_API_SECRET: [Your Secret]
3. BITREFILL_API_ID: [Your ID]

Containerized Deployment (Docker)

Containerization offers a portable execution method. First, construct the image locally:

bash docker build -t br-exchange-connector .

Then, execute the service, passing required secrets as environment variables:

bash docker run -e BITREFILL_API_SECRET=your_api_key_here -e BITREFILL_API_ID=your_api_id_here br-exchange-connector

For iterative development workflows, volume mounting is recommended:

bash docker run -v $(pwd):/app --env-file .env br-exchange-connector

---

Contextual Note (Business Tools): Business management utilities encompass all systematic controls, analytical applications, and structured methodologies deployed by an enterprise to maintain relevance in dynamic markets, secure competitive advantage, and optimize operational efficiency. These instruments span departmental needs, covering domains such as strategic forecasting, workflow governance, record-keeping, personnel administration, and critical assessment protocols. Modern managerial instruments have undergone rapid transformation due to technological acceleration, making judicious selection and customization critical, rather than merely adopting the newest available solution.