npm package: @lavapayments/mcp
Description: MCP server for Lava — route API calls through Lava's gateway across 30+ AI model providers and 20+ non-AI service APIs
Author: Lava
Latest version: 0.7.1

# Lava MCP Server

An [MCP](https://modelcontextprotocol.io/) 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.

```typescript
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`):

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

Or with `npx` (after publishing):

```bash
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):

```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"
      }
    }
  }
}
```

Or if published to npm:

```json
{
  "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:

```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"
      }
    }
  }
}
```

### 5. Connect from Cursor

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

```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

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

### Local deploy for Claude Code

Claude Code caches MCP tool lists by server name. When adding or removing tools during development, run:

```bash
npm run dev:deploy
```

This builds the server and patches `.mcp.json` with a unique server name so Claude Code discovers the updated tool list on restart.

## License

MIT