@chargly/mcp

Official MCP server for Chargly.

Expose Chargly billing and pricing primitives as MCP tools for agent-native workflows:

wallets
event metering
Stripe top-ups
Pricing Advisor recommendations

Use Chargly MCP when billing and monetization logic needs to be available inside MCP-compatible agents and tool runtimes.

Install

npm install @chargly/mcp

What is Chargly MCP?

Chargly MCP exposes Chargly's billing and pricing primitives as MCP tools. MCP-compatible runtimes (Claude Desktop, Cursor, etc.) can use these tools to:

Inspect wallet balances
Meter AI actions and deduct credits
Create credit top-up checkouts
Inspect and act on Pricing Advisor recommendations

All logic lives in the Chargly API; this server is a thin adapter.

When to use MCP vs SDK

Use case	Recommendation
App integration (Node.js, TypeScript, backend)	Use @chargly/sdk
Agent workflows (Claude, Cursor, other MCP clients)	Use Chargly MCP
Dashboard / UI	Use Chargly API or SDK directly

Installation

npm install @chargly/mcp

Environment variables

Variable	Required	Default	Description
`CHARGLY_API_KEY`	Yes	—	Your Chargly API key
`CHARGLY_BASE_URL`	No	`https://api.chargly.ai`	Chargly API base URL
`LOG_LEVEL`	No	`info`	`debug`, `info`, `warn`, `error`

Running the server

export CHARGLY_API_KEY=sk_...
npm start
# or
npx chargly-mcp

The server uses stdio transport — it reads from stdin and writes to stdout. MCP clients spawn it as a subprocess.

Available tools

Billing

Tool	Description
`chargly.get_wallet`	Fetch wallet balance for a customer
`chargly.meter_event`	Record billable AI action and deduct credits
`chargly.create_checkout`	Create Stripe checkout for credit top-up
`chargly.list_credit_packs`	List available credit packs

Pricing Advisor

Tool	Description
`chargly.get_pricing_rule`	Get pricing rule by feature
`chargly.list_pricing_recommendations`	List recommendations (optional filters)
`chargly.get_pricing_recommendation`	Get recommendation detail
`chargly.explain_pricing_recommendation`	Get human-readable explanation
`chargly.apply_pricing_recommendation`	Apply recommendation (creates new version)
`chargly.reject_pricing_recommendation`	Reject recommendation

Claude Desktop configuration

Add to your Claude Desktop config (replace the path with your install location):

{
  "mcpServers": {
    "chargly": {
      "command": "node",
      "args": ["/path/to/chargly-mcp/dist/index.js"],
      "env": {
        "CHARGLY_API_KEY": "sk_...",
        "CHARGLY_BASE_URL": "https://api.chargly.ai"
      }
    }
  }
}

If installed globally: use "command": "npx", "args": ["chargly-mcp"] instead of node + path.

See examples/claude-desktop-config.example.json and examples/usage.md.

Local development

npm install
cp .env.example .env   # then add your CHARGLY_API_KEY
npm run build
npm run dev    # run with tsx (no build)
npm run test
npm run typecheck

Testing

Tests use Vitest with mocked API responses. No live API required.

npm test

Coverage includes: config validation, all 10 tools (billing + Pricing Advisor), server tool registration.

Prerequisites

Node.js 18+
Chargly API key (create an app in the Chargly dashboard, then create an API key)

charglyai/chargly-mcp