Lava MCP Server

An MCP server that lets AI agents use Lava for merchant operations and gateway traffic. You can authenticate a fresh session with lava_login, create billing config, generate forward tokens, and execute real /v1/chat/completions, /v1/messages, /v1/forward, and /v1/rewrite requests through Lava.

Two Different Flows

MCP flow

Use this package when your host is already running an MCP client such as Claude Code, Claude Desktop, or Cursor.

1. Start the MCP server.
2. Call lava_login from the agent if no keys are preconfigured.
3. Use MCP tools like lava_create_meter, lava_generate_forward_token, lava_chat_completions, or lava_forward.

SDK flow

Use @lavapayments/nodejs directly when you are writing application code.

import { Lava } from '@lavapayments/nodejs';

const credentials = await Lava.login();
const lava = new Lava(credentials.secret_key);

The SDK flow is documented separately in /sdk/nodejs. This MCP package is only for the MCP flow.

Quick start

1. Install and run the MCP server

From this repo (monorepo root or packages/lava-mcp):

cd packages/lava-mcp
npm install
npm run build
node dist/index.js

Or with npx (after publishing):

npx @lavapayments/mcp

LAVA_SECRET_KEY is optional. If you omit it, call lava_login once the MCP is running and the server will keep the returned credentials in memory for the current session.

2. Connect from Claude Code

Add to your project's .claude/settings.json (or ~/.claude/settings.json for global):

{
  "mcpServers": {
    "lava": {
      "command": "node",
      "args": ["/absolute/path/to/packages/lava-mcp/dist/index.js"],
      "env": {
        "LAVA_API_URL": "https://api.lava.so",
        "LAVA_APP_URL": "https://www.lava.so"
      }
    }
  }
}

Or if published to npm:

{
  "mcpServers": {
    "lava": {
      "command": "npx",
      "args": ["-y", "@lavapayments/mcp"],
      "env": {
        "LAVA_API_URL": "https://api.lava.so",
        "LAVA_APP_URL": "https://www.lava.so"
      }
    }
  }
}

You can still pre-provision LAVA_SECRET_KEY if you want a non-interactive setup.

3. First-run authentication

Once the MCP is connected, call:

• lava_login to open the existing Lava browser auth flow and load the active secret key, creating one if needed
• lava_generate_forward_token when you need a forward token for customer billing or unmanaged forwarding

4. Connect from Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your platform:

{
  "mcpServers": {
    "lava": {
      "command": "node",
      "args": ["/absolute/path/to/packages/lava-mcp/dist/index.js"],
      "env": {
        "LAVA_API_URL": "https://api.lava.so",
        "LAVA_APP_URL": "https://www.lava.so"
      }
    }
  }
}

5. Connect from Cursor

Edit ~/.cursor/mcp.json or your project's .cursor/mcp.json:

{
  "mcpServers": {
    "lava": {
      "command": "node",
      "args": ["/absolute/path/to/packages/lava-mcp/dist/index.js"],
      "env": {
        "LAVA_API_URL": "https://api.lava.so",
        "LAVA_APP_URL": "https://www.lava.so"
      }
    }
  }
}

LAVA_API_URL defaults to https://api.lava.so. LAVA_APP_URL defaults to https://www.lava.so.

Environment variables

| Variable | Required | Default | Description | |--------------------|----------|---------------------------------|---------------------------------------------------------------| | LAVA_API_URL | No | https://api.lava.so | API base URL. Override only for debugging against a sandbox. | | LAVA_APP_URL | No | https://www.lava.so | Browser app URL used by lava_login. | | LAVA_SECRET_KEY | No | — | Merchant secret key (lava_sk_*). Optional if you will use lava_login. |

The server uses stdio transport: it reads/writes JSON-RPC on stdin/stdout, so the host (Claude Code, Claude Desktop, Cursor, etc.) must spawn it with the env vars above.

What the agent can do

All operations are scoped to the currently active merchant session, which comes from either preconfigured env keys or lava_login.

Tools

The MCP exposes the same operations as the merchant-authenticated REST API (Authorization: Bearer <secret_key>).

• Models: lava_list_models — list all AI models and services, including provider API reference URLs; no API key required
• Provider Docs: lava_get_provider_api_reference — fetch { provider, api_reference } for the official upstream API reference URL
• Auth: lava_login — bootstrap merchant and wallet credentials into the current MCP session
• Meters: lava_list_meters, lava_create_meter, lava_get_meter, lava_update_meter, lava_delete_meter
• Secret keys: lava_list_secret_keys, lava_create_secret_key, lava_revoke_secret_key
• Customers: lava_list_customers, lava_get_customer, lava_get_customer_subscription, lava_delete_customer
• Usage: lava_get_usage — aggregated usage with optional metadata_filters
• Plans: lava_list_plans, lava_get_plan, lava_create_plan, lava_update_plan, lava_delete_plan
• Subscriptions: lava_list_subscriptions (filterable by customer_id and status), lava_update_subscription, lava_cancel_subscription
• Webhooks: lava_list_webhooks, lava_create_webhook, lava_get_webhook, lava_update_webhook, lava_delete_webhook
• Credit bundles: lava_list_credit_bundles, lava_get_credit_bundle
• Checkout: lava_create_checkout_session
• Requests: lava_list_requests (filterable by metadata_filters), lava_get_request, lava_track_request — track usage from outside the proxy for billing
• Gateway auth: lava_generate_forward_token
• Gateway execution: lava_chat_completions, lava_messages, lava_forward, lava_rewrite
• Spend keys: lava_list_spend_keys, lava_create_spend_key, lava_get_spend_key, lava_update_spend_key, lava_delete_spend_key, lava_rotate_spend_key

Resources

• lava://models-guide – How to use Lava's models (proxy URL, auth, POST /v1/chat/completions). Use when the user or agent asks how to call the gateway or integrate the models.
• lava://overview – Short account overview (counts and first few meters/customers). Use when the user asks "what do I have set up?".
• lava://openapi – Full OpenAPI spec for the Lava REST API. Use when you need exact request/response schemas or want to discover additional endpoints.
• lava://webhook-events – Reference for all webhook event types (customer.created, customer.wallet.balance.updated, customer.deleted) with payload shapes and verification notes.

Prompts

• lava_sign_up_user – Step-by-step for signing up an end-user (onboarding checkout URL). Use when the user asks how to sign up a user for Lava.
• lava_get_started – Concrete zero-to-charging-users flow (meter → plan → onboard user → proxy). Use when the user asks how to set up Lava or what they can do.
• lava_integrate – Copy-paste code examples for pointing OpenAI/Anthropic SDKs at Lava's proxy. Use when the user wants to add Lava billing to an existing app.

Example prompts (for the user)

• "List my Lava meters."
• "What is the API reference for Anthropic?"
• "Create a meter named Chat API, tiered, $0.01 per 1K tokens."
• "Show me my Lava customers."
• "What's my usage this month?"
• "Create a plan with an optional monthly fee, 50 credits, and a linked meter."
• "Add a webhook for https://myapp.com/webhooks/lava."
• "Create a checkout link so a customer can subscribe to my $10 plan."
• "Track a usage event: 500 input tokens, 200 output tokens for customer cus_xxx on meter chat-api."

The agent will pick the right tools and parameters.

API coverage

The MCP covers merchant-authenticated REST API operations, spend key operations, session bootstrap via lava_login, forward-token generation, and direct gateway execution helpers.

Security

• Never commit or share LAVA_SECRET_KEY. Keep it in env or a local config that's not in version control.
• The secret key has full access to your merchant's Lava resources (keys, meters, webhooks, etc.). Prefer a dedicated key for the MCP server if possible.

Development

cd packages/lava-mcp
npm install
npm run build
npm run typecheck

License

MIT