@lavapayments/mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,1741 @@
+#!/usr/bin/env node
+/**
+ * Lava MCP Server
+ *
+ * Lets an AI agent use Lava (meters, keys, customers, usage, webhooks, checkout, gateway traffic, etc.)
+ * without opening the dashboard. Configure with LAVA_API_URL and optionally LAVA_SECRET_KEY,
+ * or authenticate interactively via lava_login.
+ */
+import { Lava } from '@lavapayments/nodejs';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { API_TIMEOUT_MS, createLavaClient, gatewayRequest, LavaApiError, parseJsonText, RESERVED_GATEWAY_HEADERS, throwIfNotOk, trimTrailingSlash, } from './client.js';
+// Keep in sync with package.json version
+const VERSION = '0.1.0';
+const TRAILING_SINGLE_SLASH_REGEX = /\/$/;
+const HEADER_NAME_REGEX = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+const HEADER_VALUE_NEWLINE_REGEX = /[\r\n]/;
+const BASE64_BODY_REGEX = /^[A-Za-z0-9+/]*={0,2}$/;
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+const TRUSTED_APP_HOST_SUFFIXES = ['lava.so', 'lavapayments.com'];
+const BASE_URL = process.env.LAVA_API_URL ?? 'https://api.lava.so';
+const APP_URL = process.env.LAVA_APP_URL ?? resolveDefaultAppUrl(process.env.LAVA_API_URL);
+const MAX_GATEWAY_BODY_BASE64_BYTES = 15 * 1024 * 1024;
+// This MCP currently runs over stdio as a single local process, so
+// in-memory auth state is scoped to that one MCP session.
+const authState = {
+    secretKey: process.env.LAVA_SECRET_KEY ?? '',
+    walletKey: process.env.LAVA_WALLET_KEY ?? '',
+    source: process.env.LAVA_SECRET_KEY || process.env.LAVA_WALLET_KEY ? 'env' : 'none',
+};
+function resolveDefaultAppUrl(apiBaseUrl = BASE_URL) {
+    const url = new URL(apiBaseUrl);
+    if (url.hostname === 'localhost' || url.hostname === '127.0.0.1') {
+        return new URL('/', url)
+            .toString()
+            .replace(TRAILING_SINGLE_SLASH_REGEX, '');
+    }
+    if (url.hostname.includes('sandbox')) {
+        return 'https://sandbox.lavapayments.com';
+    }
+    return 'https://www.lava.so';
+}
+function setAuthState(credentials) {
+    authState.secretKey = credentials.secret_key;
+    authState.walletKey = credentials.wallet_key;
+    authState.secretKeyId = credentials.secret_key_id;
+    authState.walletKeyId = credentials.wallet_key_id;
+    authState.merchantId = credentials.merchant_id;
+    authState.walletId = credentials.wallet_id;
+    authState.source = 'login';
+}
+function isLocalHostname(hostname) {
+    return hostname === 'localhost' || hostname === '127.0.0.1';
+}
+function isTrustedAppHostname(hostname) {
+    if (isLocalHostname(hostname)) {
+        return true;
+    }
+    try {
+        if (new URL(APP_URL).hostname.toLowerCase() === hostname) {
+            return true;
+        }
+    }
+    catch {
+        // APP_URL is already normalized at startup; ignore malformed overrides here.
+    }
+    return TRUSTED_APP_HOST_SUFFIXES.some((suffix) => {
+        return hostname === suffix || hostname.endsWith(`.${suffix}`);
+    });
+}
+function normalizeLoginAppUrl(appUrl) {
+    const url = new URL(appUrl);
+    const hostname = url.hostname.toLowerCase();
+    if (!isTrustedAppHostname(hostname)) {
+        throw new LavaApiError(`lava_login only supports Lava app hosts. Received "${hostname}".`, 400, 'invalid_request');
+    }
+    if (url.protocol !== 'https:' && !isLocalHostname(hostname)) {
+        throw new LavaApiError('lava_login requires HTTPS unless you are using localhost for development.', 400, 'invalid_request');
+    }
+    return url.toString().replace(TRAILING_SINGLE_SLASH_REGEX, '');
+}
+function assertGatewayTargetUrl(targetUrl) {
+    const url = new URL(targetUrl);
+    const hostname = url.hostname.toLowerCase();
+    if (url.protocol !== 'https:' && !isLocalHostname(hostname)) {
+        throw new LavaApiError('target_url must use HTTPS unless you are forwarding to localhost for development.', 400, 'invalid_request');
+    }
+}
+function getClient() {
+    if (!authState.secretKey) {
+        throw new LavaApiError('No merchant secret key is available. Set LAVA_SECRET_KEY in the MCP environment or call lava_login first.', 401, 'auth_required');
+    }
+    return createLavaClient({
+        baseUrl: BASE_URL,
+        secretKey: authState.secretKey,
+    });
+}
+function getWalletClient() {
+    if (!authState.walletKey) {
+        throw new LavaApiError('No wallet API key is available. Set LAVA_WALLET_KEY in the MCP environment or call lava_login first.', 401, 'auth_required');
+    }
+    return createLavaClient({
+        baseUrl: BASE_URL,
+        secretKey: authState.walletKey,
+    });
+}
+function getGatewayAuthToken(authToken) {
+    if (authToken) {
+        return authToken;
+    }
+    if (authState.secretKey) {
+        return authState.secretKey;
+    }
+    throw new LavaApiError('No default auth token is available for gateway requests. Call lava_login first, set LAVA_SECRET_KEY, or pass auth_token explicitly.', 401, 'auth_required');
+}
+function buildGatewayHeaders(headers) {
+    return Object.fromEntries(Object.entries(headers ?? {}).flatMap(([key, value]) => {
+        if (value === undefined) {
+            return [];
+        }
+        if (RESERVED_GATEWAY_HEADERS.has(key.toLowerCase())) {
+            throw new LavaApiError(`Header "${key}" is managed by Lava and cannot be overridden.`, 400, 'invalid_request');
+        }
+        if (!HEADER_NAME_REGEX.test(key)) {
+            throw new LavaApiError(`Header "${key}" is not a valid HTTP header name.`, 400, 'invalid_request');
+        }
+        if (HEADER_VALUE_NEWLINE_REGEX.test(value)) {
+            throw new LavaApiError(`Header "${key}" contains an invalid value.`, 400, 'invalid_request');
+        }
+        return [[key, value]];
+    }));
+}
+function encodeGatewayBody(args) {
+    const provided = [
+        args.body_json !== undefined,
+        args.body_text !== undefined,
+        args.body_base64 !== undefined,
+    ].filter(Boolean).length;
+    if (provided > 1) {
+        throw new LavaApiError('Provide only one of body_json, body_text, or body_base64.', 400, 'invalid_request');
+    }
+    if (args.body_json !== undefined) {
+        try {
+            return JSON.stringify(args.body_json);
+        }
+        catch {
+            throw new LavaApiError('body_json must be JSON-serializable.', 400, 'invalid_request');
+        }
+    }
+    if (args.body_text !== undefined) {
+        return args.body_text;
+    }
+    if (args.body_base64 !== undefined) {
+        const normalized = args.body_base64.trim();
+        if ((normalized.length > 0 && normalized.length % 4 !== 0) ||
+            !BASE64_BODY_REGEX.test(normalized)) {
+            throw new LavaApiError('body_base64 must be valid base64.', 400, 'invalid_request');
+        }
+        const decodedBody = Buffer.from(normalized, 'base64');
+        if (decodedBody.byteLength > MAX_GATEWAY_BODY_BASE64_BYTES) {
+            throw new LavaApiError(`body_base64 decodes to ${decodedBody.byteLength} bytes, which exceeds the MCP size limit of ${MAX_GATEWAY_BODY_BASE64_BYTES} bytes. Use the SDK or direct proxy for large binary uploads.`, 400, 'invalid_request');
+        }
+        return decodedBody;
+    }
+    return;
+}
+function assertNoStreamingBody(body) {
+    if (body &&
+        typeof body === 'object' &&
+        'stream' in body &&
+        body.stream !== false &&
+        body.stream !== null &&
+        body.stream !== undefined) {
+        throw new LavaApiError('Streaming responses are not supported through the MCP tools yet. Set stream to false and retry, or use the Lava SDK/direct proxy for streaming.', 400, 'unsupported_request');
+    }
+}
+function createJsonResource(uri, value) {
+    return {
+        contents: [
+            {
+                uri,
+                mimeType: 'application/json',
+                text: typeof value === 'string' ? value : JSON.stringify(value, null, 2),
+            },
+        ],
+    };
+}
+async function withJsonResourceErrorHandling(uri, fn) {
+    try {
+        return createJsonResource(uri, await fn());
+    }
+    catch (err) {
+        return createJsonResource(uri, { error: formatToolError(err) });
+    }
+}
+async function loginWithTimeout(appUrl) {
+    return await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            reject(new LavaApiError('lava_login timed out waiting for browser authentication. Retry when you are ready to complete the login flow.', 408, 'timeout'));
+        }, LOGIN_TIMEOUT_MS);
+        const loginPromise = Lava.login({ baseUrl: appUrl });
+        loginPromise.then((credentials) => {
+            clearTimeout(timeout);
+            resolve(credentials);
+        }, (error) => {
+            clearTimeout(timeout);
+            reject(error);
+        });
+    });
+}
+async function executeGatewayRequest(args) {
+    const authToken = getGatewayAuthToken(args.authToken);
+    const headers = buildGatewayHeaders(args.headers);
+    const body = encodeGatewayBody(args);
+    const hasBody = body !== undefined;
+    const hasContentType = Object.keys(headers).some((key) => key.toLowerCase() === 'content-type');
+    if (args.body_json !== undefined && !hasContentType) {
+        headers['Content-Type'] = 'application/json';
+    }
+    if (args.body_text !== undefined && !hasContentType) {
+        headers['Content-Type'] = 'text/plain; charset=utf-8';
+    }
+    const res = await gatewayRequest({
+        baseUrl: BASE_URL,
+        method: args.method,
+        path: args.path,
+        secretKey: authToken,
+        headers,
+        body,
+    });
+    return {
+        ...res,
+        request: {
+            method: args.method,
+            path: args.path,
+            used_default_auth: !args.authToken,
+            has_body: hasBody,
+        },
+    };
+}
+/** Fetch a public endpoint (no auth). Used for /v1/services so models can be listed without LAVA_SECRET_KEY. */
+async function fetchPublic(path) {
+    const base = trimTrailingSlash(BASE_URL);
+    const url = path.startsWith('/') ? `${base}${path}` : `${base}/${path}`;
+    const res = await fetch(url, {
+        signal: AbortSignal.timeout(API_TIMEOUT_MS),
+    });
+    const text = await res.text();
+    const json = parseJsonText(text);
+    throwIfNotOk(res, json);
+    return json;
+}
+function jsonContent(value) {
+    const text = typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+    return { content: [{ type: 'text', text }] };
+}
+/** Wraps a tool handler so API errors are returned as MCP error content instead of uncaught exceptions. */
+function formatToolError(err) {
+    if (err instanceof LavaApiError) {
+        const metadata = [
+            `status ${err.status}`,
+            ...(err.code ? [`code ${err.code}`] : []),
+        ].join(', ');
+        return metadata ? `${err.message} (${metadata})` : err.message;
+    }
+    if (err instanceof Error) {
+        return err.message;
+    }
+    return String(err);
+}
+function withErrorHandling(fn) {
+    return async (args) => {
+        try {
+            return await fn(args);
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: formatToolError(err) }],
+                isError: true,
+            };
+        }
+    };
+}
+async function main() {
+    const server = new McpServer({
+        name: 'lava',
+        version: VERSION,
+    }, {
+        capabilities: { tools: {}, resources: {}, prompts: {} },
+        instructions: `Lava MCP: manage meters, API keys, customers, usage, webhooks, plans, checkout sessions, and gateway traffic. If no env keys are preconfigured, call lava_login first to bootstrap this MCP session with the existing Lava browser auth flow. Merchant ops use the active merchant secret key; spend key ops use the active wallet key. To onboard an end-user: lava_create_checkout_session(checkout_mode:"onboarding", origin_url). To generate proxy auth: lava_generate_forward_token. To route real traffic through Lava: lava_chat_completions, lava_messages, lava_forward, or lava_rewrite. Resources: lava://models-guide (proxy/chat API), lava://webhook-events, lava://openapi.`,
+    });
+    const listPaginationSchema = {
+        cursor: z
+            .string()
+            .optional()
+            .describe('Pagination cursor from a previous list response'),
+        limit: z
+            .number()
+            .min(1)
+            .max(100)
+            .optional()
+            .default(20)
+            .describe('Max items to return (1-100)'),
+    };
+    const gatewayMethodSchema = z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+    const gatewayHeadersSchema = z
+        .record(z.string())
+        .optional()
+        .describe('Optional request headers to forward. Do not include Authorization or hop-by-hop transport headers; Lava sets those itself.');
+    const gatewayBodySchema = {
+        body_json: z
+            .unknown()
+            .optional()
+            .describe('JSON request body. Provide at most one of body_json, body_text, or body_base64.'),
+        body_text: z
+            .string()
+            .optional()
+            .describe('Raw text request body. Provide at most one of body_json, body_text, or body_base64.'),
+        body_base64: z
+            .string()
+            .optional()
+            .describe('Base64-encoded binary request body. Provide at most one of body_json, body_text, or body_base64.'),
+    };
+    server.registerTool('lava_login', {
+        title: 'Authenticate this MCP session',
+        description: 'Run the existing Lava browser login flow and store the returned merchant secret key plus wallet key in this MCP session. Use this for first-run auth when no LAVA_SECRET_KEY or LAVA_WALLET_KEY is preconfigured.',
+        inputSchema: z.object({
+            app_url: z
+                .string()
+                .url()
+                .optional()
+                .describe('Optional Lava app base URL for the browser login flow. Defaults to LAVA_APP_URL, or is derived from LAVA_API_URL when unset.'),
+        }),
+    }, withErrorHandling(async ({ app_url }) => {
+        const credentials = await loginWithTimeout(normalizeLoginAppUrl(app_url ?? APP_URL));
+        setAuthState(credentials);
+        return jsonContent({
+            authenticated: true,
+            source: authState.source,
+            merchant_id: credentials.merchant_id,
+            wallet_id: credentials.wallet_id,
+            secret_key_id: credentials.secret_key_id,
+            wallet_key_id: credentials.wallet_key_id,
+            message: 'Lava login succeeded. This MCP session now has both merchant and wallet credentials loaded in memory.',
+        });
+    }));
+    server.registerTool('lava_generate_forward_token', {
+        title: 'Generate a forward token',
+        description: 'Generate a base64 forward token for /v1/forward, /v1/rewrite, or direct proxy use. Use null/null for customer_id and meter_slug to create a merchant-billed token; provide both to bill a specific customer with a specific meter.',
+        inputSchema: z.object({
+            customer_id: z
+                .string()
+                .nullable()
+                .optional()
+                .describe('Customer ID to bill. Set null for merchant-billed proxy traffic.'),
+            meter_slug: z
+                .string()
+                .nullable()
+                .optional()
+                .describe('Meter slug to bill against. Set null for merchant-billed proxy traffic.'),
+            provider_key: z
+                .string()
+                .optional()
+                .describe('Optional provider API key for unmanaged/BYOK forwarding.'),
+        }),
+    }, withErrorHandling(({ customer_id, meter_slug, provider_key }) => {
+        const normalizedCustomerId = customer_id ?? null;
+        const normalizedMeterSlug = meter_slug ?? null;
+        if ((normalizedCustomerId === null) !== (normalizedMeterSlug === null)) {
+            throw new LavaApiError('customer_id and meter_slug must either both be set or both be null.', 400, 'invalid_request');
+        }
+        const lava = new Lava(getGatewayAuthToken());
+        const token = normalizedCustomerId === null
+            ? lava.generateForwardToken({
+                customer_id: null,
+                meter_slug: null,
+                ...(provider_key ? { provider_key } : {}),
+            })
+            : lava.generateForwardToken({
+                customer_id: normalizedCustomerId,
+                meter_slug: normalizedMeterSlug,
+                ...(provider_key ? { provider_key } : {}),
+            });
+        return jsonContent({
+            token,
+            mode: normalizedCustomerId === null ? 'merchant_billed' : 'customer_billed',
+            customer_id: normalizedCustomerId,
+            meter_slug: normalizedMeterSlug,
+            has_provider_key: Boolean(provider_key),
+        });
+    }));
+    // ── Meters ──
+    server.registerTool('lava_list_meters', {
+        title: 'List meters',
+        description: 'List all usage meters (products) for the merchant. Use this to see pricing and meter IDs.',
+        inputSchema: z.object(listPaginationSchema),
+    }, withErrorHandling(async ({ cursor, limit }) => {
+        const api = getClient();
+        const res = await api.list('/v1/meters', { cursor, limit });
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_create_meter', {
+        title: 'Create a meter',
+        description: `Create a new usage meter that defines how Lava prices and tracks one type of AI usage. You need at least one meter before you can charge users.
+
+rate_type:
+  "flat"   — one price for all usage (most common). Use a single tier with start "0".
+  "tiered" — price changes at volume thresholds (e.g. cheaper after 1M tokens).
+
+tier_type:
+  "per_unit" — rate is charged per unit of usage. E.g. rate "0.000001" = $0.000001 per token = $1 per million tokens.
+  "flat"     — rate is a flat fee for the entire tier, regardless of how many units.
+
+tiers: array of { start, rate }. The first tier must have start "0". For flat rate_type, one tier is enough.
+rate is always a decimal USD amount as a string. For per_unit token pricing, common values:
+  "0.000001"  = $1 / million tokens
+  "0.000002"  = $2 / million tokens
+  "0.00001"   = $10 / million tokens
+
+Example — simple $1/M token meter:
+  rate_type: "flat", tier_type: "per_unit", tiers: [{ start: "0", rate: "0.000001" }]`,
+        inputSchema: z.object({
+            name: z
+                .string()
+                .min(1)
+                .describe('Display name for the meter (e.g. "Chat API")'),
+            meter_slug: z
+                .string()
+                .optional()
+                .describe('Optional URL-safe slug used in lava_track_request; auto-generated if omitted'),
+            rate_type: z
+                .enum(['flat', 'tiered'])
+                .describe('"flat" = one rate for all usage (most common). "tiered" = rate changes at volume thresholds.'),
+            tier_type: z
+                .enum(['per_unit', 'flat'])
+                .describe('"per_unit" = rate charged per token/character/second. "flat" = flat fee per tier regardless of units.'),
+            tiers: z
+                .array(z.object({
+                start: z
+                    .string()
+                    .describe('Usage count where this tier begins. First tier must be "0".'),
+                rate: z
+                    .string()
+                    .describe('USD rate as decimal string. For per_unit: rate per single unit (e.g. "0.000001" = $1 per million). For flat: total fee for the tier.'),
+            }))
+                .min(1)
+                .describe('Pricing tiers. For flat rate_type, one tier starting at "0" is all you need.'),
+        }),
+    }, withErrorHandling(async (args) => {
+        const api = getClient();
+        const res = await api.post('/v1/meters', args);
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_get_meter', {
+        title: 'Get a meter',
+        description: 'Fetch a single meter by ID.',
+        inputSchema: z.object({ meter_id: z.string().describe('The meter ID') }),
+    }, withErrorHandling(async ({ meter_id }) => {
+        const api = getClient();
+        const res = await api.get(`/v1/meters/${encodeURIComponent(meter_id)}`);
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_update_meter', {
+        title: 'Update a meter',
+        description: 'Update a meter name and/or tiers. Rate type, tier type, and slug cannot be changed.',
+        inputSchema: z.object({
+            meter_id: z.string().describe('The meter ID to update'),
+            name: z.string().min(1).optional().describe('New display name'),
+            tiers: z
+                .array(z.object({
+                start: z.string().describe('Tier start (first tier must be "0")'),
+                rate: z.string().describe('Rate for this tier (decimal string)'),
+            }))
+                .min(1)
+                .optional()
+                .describe('New tiers (replaces existing); first tier start must be 0'),
+        }),
+    }, withErrorHandling(async (args) => {
+        const { meter_id, ...body } = args;
+        const api = getClient();
+        const res = await api.patch(`/v1/meters/${encodeURIComponent(meter_id)}`, body);
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_delete_meter', {
+        title: 'Delete a meter',
+        description: 'Soft-delete a meter. May be subject to cooldown after creation.',
+        inputSchema: z.object({
+            meter_id: z.string().describe('The meter ID to delete'),
+        }),
+    }, withErrorHandling(async ({ meter_id }) => {
+        const api = getClient();
+        const res = await api.delete(`/v1/meters/${encodeURIComponent(meter_id)}`);
+        return jsonContent(res);
+    }));
+    // ── Secret keys ──
+    server.registerTool('lava_list_secret_keys', {
+        title: 'List secret keys',
+        description: 'List API secret keys for the merchant. Use these to authenticate REST and proxy requests.',
+        inputSchema: z.object(listPaginationSchema),
+    }, withErrorHandling(async ({ cursor, limit }) => {
+        const api = getClient();
+        const res = await api.list('/v1/secret_keys', { cursor, limit });
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_create_secret_key', {
+        title: 'Create a secret key',
+        description: 'Create a new API secret key. The secret value is only returned once at creation.',
+        inputSchema: z.object({
+            name: z
+                .string()
+                .min(1)
+                .describe('Label for the key (e.g. "Production" or "Dev")'),
+        }),
+    }, withErrorHandling(async (args) => {
+        const api = getClient();
+        const res = await api.post('/v1/secret_keys', args);
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_revoke_secret_key', {
+        title: 'Revoke a secret key',
+        description: 'Permanently revoke a secret key by ID. You must keep at least one key. May be subject to cooldown after creation.',
+        inputSchema: z.object({
+            secret_key_id: z.string().describe('The secret key ID to revoke'),
+        }),
+    }, withErrorHandling(async ({ secret_key_id }) => {
+        const api = getClient();
+        const res = await api.delete(`/v1/secret_keys/${encodeURIComponent(secret_key_id)}`);
+        return jsonContent(res);
+    }));
+    // ── Customers (end-users linked to merchant) ──
+    server.registerTool('lava_list_customers', {
+        title: 'List customers',
+        description: 'List end-user customers linked to your merchant. Useful to see who has onboarded and their subscription status.',
+        inputSchema: z.object(listPaginationSchema),
+    }, withErrorHandling(async ({ cursor, limit }) => {
+        const api = getClient();
+        const res = await api.list('/v1/customers', { cursor, limit });
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_get_customer', {
+        title: 'Get a customer',
+        description: 'Fetch a single customer by ID (includes subscription summary if active).',
+        inputSchema: z.object({
+            customer_id: z.string().describe('The customer ID'),
+        }),
+    }, withErrorHandling(async ({ customer_id }) => {
+        const api = getClient();
+        const res = await api.get(`/v1/customers/${encodeURIComponent(customer_id)}`);
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_get_customer_subscription', {
+        title: 'Get customer subscription',
+        description: 'Get the active subscription and current cycle for a customer.',
+        inputSchema: z.object({
+            customer_id: z.string().describe('The customer ID'),
+        }),
+    }, withErrorHandling(async ({ customer_id }) => {
+        const api = getClient();
+        const res = await api.get(`/v1/customers/${encodeURIComponent(customer_id)}/subscription`);
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_delete_customer', {
+        title: 'Delete a customer',
+        description: 'Permanently remove a customer from your merchant.',
+        inputSchema: z.object({
+            customer_id: z.string().describe('The customer ID to delete'),
+        }),
+    }, withErrorHandling(async ({ customer_id }) => {
+        const api = getClient();
+        const res = await api.delete(`/v1/customers/${encodeURIComponent(customer_id)}`);
+        return jsonContent(res);
+    }));
+    // ── Usage ──
+    server.registerTool('lava_get_usage', {
+        title: 'Get usage',
+        description: 'Get aggregated usage for the merchant within a date range. Optionally filter by customer or meter.',
+        inputSchema: z.object({
+            start: z
+                .string()
+                .describe('Start date (ISO 8601, e.g. 2025-01-01T00:00:00Z)'),
+            end: z
+                .string()
+                .optional()
+                .describe('End date (ISO 8601). Omit for open-ended.'),
+            customer_id: z.string().optional().describe('Filter by customer ID'),
+            meter_id: z.string().optional().describe('Filter by meter ID'),
+            metadata_filters: z
+                .array(z.tuple([z.string(), z.string()]))
+                .optional()
+                .describe('Filter by metadata key-value pairs, e.g. [["user_id", "u_123"]]'),
+        }),
+    }, withErrorHandling(async (args) => {
+        const api = getClient();
+        const params = { start: args.start };
+        if (args.end) {
+            params.end = args.end;
+        }
+        if (args.customer_id) {
+            params.customer_id = args.customer_id;
+        }
+        if (args.meter_id) {
+            params.meter_id = args.meter_id;
+        }
+        if (args.metadata_filters && args.metadata_filters.length > 0) {
+            params.metadata_filters = JSON.stringify(args.metadata_filters);
+        }
+        const res = await api.get('/v1/usage', params);
+        return jsonContent(res);
+    }));
+    // ── Plans ──
+    server.registerTool('lava_list_plans', {
+        title: 'List plans',
+        description: 'List plans that customers can subscribe to.',
+        inputSchema: z.object(listPaginationSchema),
+    }, withErrorHandling(async ({ cursor, limit }) => {
+        const api = getClient();
+        const res = await api.list('/v1/plans', { cursor, limit });
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_get_plan', {
+        title: 'Get a plan',
+        description: 'Fetch a single plan by ID.',
+        inputSchema: z.object({
+            plan_id: z.string().describe('The plan ID'),
+        }),
+    }, withErrorHandling(async ({ plan_id }) => {
+        const api = getClient();
+        const res = await api.get(`/v1/plans/${encodeURIComponent(plan_id)}`);
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_create_plan', {
+        title: 'Create a plan',
+        description: 'Create a new plan with an optional recurring fee, included credit, linked meters, and optional credit bundles.',
+        inputSchema: z.object({
+            name: z.string().min(1),
+            period_amount: z
+                .string()
+                .describe('Price per period (decimal string, e.g. "9.99")'),
+            billing_interval: z.enum(['day', 'week', 'month', 'year']),
+            rollover_type: z.enum(['full', 'none']).optional(),
+            bundle_rollover_type: z.enum(['full', 'none']).optional(),
+            included_credit: z
+                .string()
+                .optional()
+                .describe('Included credit amount (decimal string)'),
+            default_auto_top_up_bundle_index: z
+                .number()
+                .int()
+                .nullable()
+                .optional()
+                .describe('Optional index into credit_bundles to mark the default auto top-up bundle.'),
+            meter_ids: z.array(z.string()).optional().describe('Linked meter IDs'),
+            credit_bundles: z
+                .array(z.object({
+                name: z.string(),
+                cost: z.string(),
+                credit_amount: z.string(),
+            }))
+                .optional(),
+        }),
+    }, withErrorHandling(async (args) => {
+        const api = getClient();
+        const res = await api.post('/v1/plans', args);
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_update_plan', {
+        title: 'Update a plan',
+        description: 'Update a plan name, rollover settings, included credit, linked meters, or credit bundles. period_amount and billing_interval are immutable.',
+        inputSchema: z.object({
+            plan_id: z.string(),
+            name: z.string().min(1).optional(),
+            rollover_type: z.enum(['full', 'none']).optional(),
+            bundle_rollover_type: z.enum(['full', 'none']).optional(),
+            included_credit: z.string().optional(),
+            meter_ids: z.array(z.string()).optional(),
+            credit_bundles: z
+                .array(z.object({
+                credit_bundle_id: z.string().optional(),
+                name: z.string(),
+                cost: z.string(),
+                credit_amount: z.string(),
+                is_deleted: z.boolean().optional(),
+            }))
+                .optional(),
+        }),
+    }, withErrorHandling(async (args) => {
+        const { plan_id, ...body } = args;
+        const api = getClient();
+        const res = await api.patch(`/v1/plans/${encodeURIComponent(plan_id)}`, body);
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_delete_plan', {
+        title: 'Delete a plan',
+        description: 'Soft-delete a plan. Fails if it has active subscriptions.',
+        inputSchema: z.object({ plan_id: z.string() }),
+    }, withErrorHandling(async ({ plan_id }) => {
+        const api = getClient();
+        const res = await api.delete(`/v1/plans/${encodeURIComponent(plan_id)}`);
+        return jsonContent(res);
+    }));
+    // ── Webhooks ──
+    server.registerTool('lava_list_webhooks', {
+        title: 'List webhooks',
+        description: 'List webhook endpoints that receive Lava events.',
+        inputSchema: z.object(listPaginationSchema),
+    }, withErrorHandling(async ({ cursor, limit }) => {
+        const api = getClient();
+        const res = await api.list('/v1/webhooks', { cursor, limit });
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_create_webhook', {
+        title: 'Create a webhook',
+        description: 'Register a URL to receive Lava event notifications.',
+        inputSchema: z.object({
+            name: z.string().min(1).describe('Label for the webhook'),
+            url: z
+                .string()
+                .url()
+                .describe('HTTPS URL that will receive POST events'),
+        }),
+    }, withErrorHandling(async (args) => {
+        const api = getClient();
+        const res = await api.post('/v1/webhooks', args);
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_get_webhook', {
+        title: 'Get a webhook',
+        description: 'Fetch a single webhook by ID.',
+        inputSchema: z.object({ webhook_id: z.string() }),
+    }, withErrorHandling(async ({ webhook_id }) => {
+        const api = getClient();
+        const res = await api.get(`/v1/webhooks/${encodeURIComponent(webhook_id)}`);
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_update_webhook', {
+        title: 'Update a webhook',
+        description: 'Update a webhook name and/or URL.',
+        inputSchema: z.object({
+            webhook_id: z.string(),
+            name: z.string().min(1).optional(),
+            url: z.string().url().optional(),
+        }),
+    }, withErrorHandling(async (args) => {
+        const { webhook_id, ...body } = args;
+        const api = getClient();
+        const res = await api.patch(`/v1/webhooks/${encodeURIComponent(webhook_id)}`, body);
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_delete_webhook', {
+        title: 'Delete a webhook',
+        description: 'Permanently delete a webhook.',
+        inputSchema: z.object({ webhook_id: z.string() }),
+    }, withErrorHandling(async ({ webhook_id }) => {
+        const api = getClient();
+        const res = await api.delete(`/v1/webhooks/${encodeURIComponent(webhook_id)}`);
+        return jsonContent(res);
+    }));
+    // ── Spend keys (require an active wallet key in env or via lava_login) ──
+    const spendLimitSchema = z
+        .object({
+        amount: z.string().describe('Decimal spend limit (e.g. "10.00")'),
+        cycle: z.enum(['daily', 'weekly', 'monthly', 'total']),
+    })
+        .nullable();
+    const requestLimitSchema = z
+        .object({
+        count: z.number().int().min(1).describe('Max number of requests'),
+        cycle: z.enum(['daily', 'weekly', 'monthly', 'total']),
+    })
+        .nullable();
+    const rateLimitSchema = z
+        .object({
+        rpm: z.number().int().min(1).describe('Max requests per minute'),
+        burst: z
+            .number()
+            .int()
+            .nullable()
+            .optional()
+            .describe('Max burst size; must be ≤ rpm'),
+    })
+        .nullable();
+    server.registerTool('lava_list_spend_keys', {
+        title: 'List spend keys',
+        description: 'List spend keys owned by the active wallet key in this MCP session. Spend keys are scoped service keys for client-side or restricted proxy access.',
+        inputSchema: z.object(listPaginationSchema),
+    }, withErrorHandling(async ({ cursor, limit }) => {
+        const api = getWalletClient();
+        const res = await api.list('/v1/spend_keys', { cursor, limit });
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_create_spend_key', {
+        title: 'Create a spend key',
+        description: 'Create a spend key for the active wallet key in this MCP session. The full key value is only returned once at creation. Optionally restrict by allowed models, providers, spend, request count, rate, or expiry.',
+        inputSchema: z.object({
+            name: z.string().min(1).max(255).describe('Label for the key'),
+            status: z
+                .enum(['active', 'paused'])
+                .optional()
+                .describe('Initial status; defaults to active'),
+            request_shape: z
+                .enum(['openai', 'anthropic'])
+                .optional()
+                .describe('Expected request format; defaults to openai'),
+            allowed_models: z
+                .array(z.string())
+                .nullable()
+                .optional()
+                .describe('Model IDs this key may use; null = all models'),
+            allowed_providers: z
+                .array(z.string())
+                .nullable()
+                .optional()
+                .describe('Provider names this key may use; null = all providers'),
+            spend_limit: spendLimitSchema
+                .optional()
+                .describe('Spend cap; null = no limit'),
+            request_limit: requestLimitSchema
+                .optional()
+                .describe('Request count cap; null = no limit'),
+            rate_limit: rateLimitSchema
+                .optional()
+                .describe('Rate limit; null = no limit'),
+            expires_at: z
+                .string()
+                .datetime()
+                .nullable()
+                .optional()
+                .describe('ISO 8601 expiry; null = never expires'),
+        }),
+    }, withErrorHandling(async (args) => {
+        const api = getWalletClient();
+        const res = await api.post('/v1/spend_keys', args);
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_get_spend_key', {
+        title: 'Get a spend key',
+        description: 'Fetch a single spend key by ID (includes current spend and request counts).',
+        inputSchema: z.object({
+            spend_key_id: z.string().describe('The spend key ID'),
+        }),
+    }, withErrorHandling(async ({ spend_key_id }) => {
+        const api = getWalletClient();
+        const res = await api.get(`/v1/spend_keys/${encodeURIComponent(spend_key_id)}`);
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_update_spend_key', {
+        title: 'Update a spend key',
+        description: "Update a spend key's name, status, restrictions, or expiry. All fields are optional; omitted fields are unchanged. Pass null to a limit field to remove that limit.",
+        inputSchema: z.object({
+            spend_key_id: z.string().describe('The spend key ID to update'),
+            name: z.string().min(1).max(255).optional(),
+            status: z.enum(['active', 'paused']).optional(),
+            request_shape: z.enum(['openai', 'anthropic']).optional(),
+            allowed_models: z
+                .array(z.string())
+                .nullable()
+                .optional()
+                .describe('null = allow all models'),
+            allowed_providers: z
+                .array(z.string())
+                .nullable()
+                .optional()
+                .describe('null = allow all providers'),
+            spend_limit: spendLimitSchema
+                .optional()
+                .describe('null = remove spend limit'),
+            request_limit: requestLimitSchema
+                .optional()
+                .describe('null = remove request limit'),
+            rate_limit: rateLimitSchema
+                .optional()
+                .describe('null = remove rate limit'),
+            expires_at: z
+                .string()
+                .datetime()
+                .nullable()
+                .optional()
+                .describe('null = never expires'),
+        }),
+    }, withErrorHandling(async (args) => {
+        const { spend_key_id, ...body } = args;
+        const api = getWalletClient();
+        const res = await api.put(`/v1/spend_keys/${encodeURIComponent(spend_key_id)}`, body);
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_delete_spend_key', {
+        title: 'Delete a spend key',
+        description: 'Permanently revoke a spend key. The key will immediately stop working for proxy requests.',
+        inputSchema: z.object({
+            spend_key_id: z.string().describe('The spend key ID to delete'),
+        }),
+    }, withErrorHandling(async ({ spend_key_id }) => {
+        const api = getWalletClient();
+        const res = await api.delete(`/v1/spend_keys/${encodeURIComponent(spend_key_id)}`);
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_rotate_spend_key', {
+        title: 'Rotate a spend key',
+        description: 'Generate a new secret for a spend key. The old secret is immediately invalidated. The new full key value is returned once — save it.',
+        inputSchema: z.object({
+            spend_key_id: z.string().describe('The spend key ID to rotate'),
+        }),
+    }, withErrorHandling(async ({ spend_key_id }) => {
+        const api = getWalletClient();
+        const res = await api.post(`/v1/spend_keys/${encodeURIComponent(spend_key_id)}/rotate`, {});
+        return jsonContent(res);
+    }));
+    // ── Checkout sessions ──
+    server.registerTool('lava_create_checkout_session', {
+        title: 'Create a checkout session',
+        description: 'Create a checkout session URL so an end-user can onboard, subscribe, or top up. Return the URL to the user to open in a browser.',
+        inputSchema: z.object({
+            checkout_mode: z.enum([
+                'onboarding',
+                'topup',
+                'subscription',
+                'credit_bundle',
+            ]),
+            origin_url: z
+                .string()
+                .url()
+                .describe('URL to return to after checkout (your app)'),
+            customer_id: z
+                .string()
+                .optional()
+                .describe('Required for topup/credit_bundle; optional for subscription'),
+            plan_id: z
+                .string()
+                .optional()
+                .describe('Required for subscription mode (plan ID)'),
+            credit_bundle_id: z
+                .string()
+                .optional()
+                .describe('Required for credit_bundle mode'),
+        }),
+    }, withErrorHandling(async (args) => {
+        const api = getClient();
+        const body = {
+            checkout_mode: args.checkout_mode,
+            origin_url: args.origin_url,
+        };
+        if (args.customer_id !== undefined) {
+            body.customer_id = args.customer_id;
+        }
+        if (args.plan_id !== undefined) {
+            body.plan_id = args.plan_id;
+        }
+        if (args.credit_bundle_id !== undefined) {
+            body.credit_bundle_id = args.credit_bundle_id;
+        }
+        const res = await api.post('/v1/checkout_sessions', body);
+        return jsonContent(res);
+    }));
+    // ── Subscriptions ──
+    server.registerTool('lava_list_subscriptions', {
+        title: 'List subscriptions',
+        description: 'List subscriptions (customer + plan associations). Filter by customer_id to check a specific customer\'s subscription. status defaults to "active"; pass "cancelled" or "all" to see others.',
+        inputSchema: z.object({
+            ...listPaginationSchema,
+            customer_id: z
+                .string()
+                .optional()
+                .describe("Filter by customer ID (e.g. to check one customer's subscription)"),
+            status: z
+                .enum(['active', 'cancelled', 'all'])
+                .optional()
+                .default('active')
+                .describe('Filter by status; default is "active"'),
+        }),
+    }, withErrorHandling(async (args) => {
+        const api = getClient();
+        const params = {};
+        if (args.cursor) {
+            params.cursor = args.cursor;
+        }
+        if (args.limit !== undefined) {
+            params.limit = String(args.limit);
+        }
+        if (args.customer_id) {
+            params.customer_id = args.customer_id;
+        }
+        if (args.status) {
+            params.status = args.status;
+        }
+        const res = await api.get('/v1/subscriptions', params);
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_update_subscription', {
+        title: 'Update a subscription',
+        description: 'Update subscription settings (e.g. auto top-up bundle) by active subscription ID.',
+        inputSchema: z.object({
+            subscription_id: z.string().describe('Active subscription ID'),
+            auto_top_up_bundle_id: z
+                .string()
+                .nullable()
+                .describe('Credit bundle ID for auto top-up, or null to clear'),
+        }),
+    }, withErrorHandling(async (args) => {
+        const { subscription_id, ...body } = args;
+        const api = getClient();
+        const res = await api.patch(`/v1/subscriptions/${encodeURIComponent(subscription_id)}`, body);
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_cancel_subscription', {
+        title: 'Cancel a subscription',
+        description: 'Schedule subscription cancellation at end of current billing cycle.',
+        inputSchema: z.object({
+            subscription_id: z
+                .string()
+                .describe('Active subscription ID to cancel'),
+        }),
+    }, withErrorHandling(async ({ subscription_id }) => {
+        const api = getClient();
+        const res = await api.delete(`/v1/subscriptions/${encodeURIComponent(subscription_id)}`);
+        return jsonContent(res);
+    }));
+    // ── Credit bundles ──
+    server.registerTool('lava_list_credit_bundles', {
+        title: 'List credit bundles',
+        description: 'List credit bundles (optionally filter by plan_id).',
+        inputSchema: z.object({
+            ...listPaginationSchema,
+            plan_id: z.string().optional(),
+        }),
+    }, withErrorHandling(async (args) => {
+        const api = getClient();
+        const params = {};
+        if (args.cursor) {
+            params.cursor = args.cursor;
+        }
+        if (args.limit !== undefined) {
+            params.limit = String(args.limit);
+        }
+        if (args.plan_id) {
+            params.plan_id = args.plan_id;
+        }
+        const res = await api.get('/v1/credit_bundles', params);
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_get_credit_bundle', {
+        title: 'Get a credit bundle',
+        description: 'Fetch a single credit bundle by ID.',
+        inputSchema: z.object({ credit_bundle_id: z.string() }),
+    }, withErrorHandling(async ({ credit_bundle_id }) => {
+        const api = getClient();
+        const res = await api.get(`/v1/credit_bundles/${encodeURIComponent(credit_bundle_id)}`);
+        return jsonContent(res);
+    }));
+    // ── Requests (proxy request history + manual tracking) ──
+    server.registerTool('lava_list_requests', {
+        title: 'List requests',
+        description: 'List recent AI proxy requests (usage events) for debugging or auditing. Supports metadata_filters to find requests tagged with specific key-value pairs.',
+        inputSchema: z.object({
+            ...listPaginationSchema,
+            customer_id: z.string().optional(),
+            meter_id: z.string().optional(),
+            metadata_filters: z
+                .array(z.tuple([z.string(), z.string()]))
+                .optional()
+                .describe('Filter by metadata key-value pairs, e.g. [["user_id", "u_123"], ["session", "s_456"]]'),
+        }),
+    }, withErrorHandling(async (args) => {
+        const api = getClient();
+        const params = {};
+        if (args.cursor) {
+            params.cursor = args.cursor;
+        }
+        if (args.limit !== undefined) {
+            params.limit = String(args.limit);
+        }
+        if (args.customer_id) {
+            params.customer_id = args.customer_id;
+        }
+        if (args.meter_id) {
+            params.meter_id = args.meter_id;
+        }
+        if (args.metadata_filters && args.metadata_filters.length > 0) {
+            params.metadata_filters = JSON.stringify(args.metadata_filters);
+        }
+        const res = await api.get('/v1/requests', params);
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_get_request', {
+        title: 'Get a request',
+        description: 'Fetch a single proxy request by ID (usage event detail).',
+        inputSchema: z.object({
+            request_id: z.string().describe('The request ID'),
+        }),
+    }, withErrorHandling(async ({ request_id }) => {
+        const api = getClient();
+        const res = await api.get(`/v1/requests/${encodeURIComponent(request_id)}`);
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_track_request', {
+        title: 'Track a manual request',
+        description: "Record a usage event for billing outside the AI proxy — e.g. if you call an AI provider directly and want Lava to meter and charge for it. Idempotent: submitting the same request_id twice returns the existing record. The meter is identified by meter_slug (not meter_id). Usage units depend on the meter's tier_type: pass input_tokens/output_tokens for token-based meters, input_characters/output_characters for character-based meters, or input_seconds/output_seconds for time-based meters.",
+        inputSchema: z.object({
+            request_id: z
+                .string()
+                .describe('Unique ID for this request (caller-generated, used for idempotency)'),
+            customer_id: z
+                .string()
+                .describe('The customer ID of the end-user being charged'),
+            meter_slug: z
+                .string()
+                .describe('The slug of the meter to bill against (see lava_list_meters)'),
+            input_tokens: z
+                .number()
+                .min(0)
+                .optional()
+                .describe('Input token count (for token-based meters)'),
+            output_tokens: z
+                .number()
+                .min(0)
+                .optional()
+                .describe('Output token count (for token-based meters)'),
+            input_characters: z
+                .number()
+                .min(0)
+                .optional()
+                .describe('Input character count (for character-based meters)'),
+            output_characters: z
+                .number()
+                .min(0)
+                .optional()
+                .describe('Output character count (for character-based meters)'),
+            input_seconds: z
+                .number()
+                .min(0)
+                .optional()
+                .describe('Input duration in seconds (for time-based meters)'),
+            output_seconds: z
+                .number()
+                .min(0)
+                .optional()
+                .describe('Output duration in seconds (for time-based meters)'),
+            metadata: z
+                .record(z.string())
+                .optional()
+                .describe('Key-value metadata to attach to the request (queryable via metadata_filters)'),
+        }),
+    }, withErrorHandling(async (args) => {
+        const api = getClient();
+        const res = await api.post('/v1/requests', args);
+        return jsonContent(res);
+    }));
+    // ── Models (catalog is public; no merchant auth required for list) ──
+    server.registerTool('lava_list_models', {
+        title: 'List Lava models',
+        description: `List all AI models and services available through Lava's gateway (OpenAI, Anthropic, Google, etc.). Returns model id, provider, pricing, and capabilities. Use these model ids when calling the proxy (POST /v1/chat/completions). Read the lava://models-guide resource to explain how to use them. No API key required.`,
+        inputSchema: z.object({}),
+    }, withErrorHandling(async () => {
+        const res = await fetchPublic('/v1/services');
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_chat_completions', {
+        title: 'Call /v1/chat/completions',
+        description: "Execute a real request against Lava's unified OpenAI-compatible chat endpoint. Pass the exact JSON body you would normally send to /v1/chat/completions. Uses the current MCP merchant session by default, or pass auth_token explicitly. Streaming is not supported through the MCP wrapper.",
+        inputSchema: z.object({
+            body_json: z
+                .unknown()
+                .describe('OpenAI-compatible chat completions request body.'),
+            auth_token: z
+                .string()
+                .optional()
+                .describe('Optional explicit auth token (for example a forward token or spend key). Defaults to the active MCP merchant session key.'),
+            headers: gatewayHeadersSchema,
+        }),
+    }, withErrorHandling(async ({ body_json, auth_token, headers }) => {
+        assertNoStreamingBody(body_json);
+        const normalizedHeaders = buildGatewayHeaders(headers);
+        normalizedHeaders['Content-Type'] = 'application/json';
+        const res = await executeGatewayRequest({
+            method: 'POST',
+            path: '/v1/chat/completions',
+            authToken: auth_token,
+            headers: normalizedHeaders,
+            body_json,
+        });
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_messages', {
+        title: 'Call /v1/messages',
+        description: "Execute a real request against Lava's Anthropic-compatible messages endpoint. Pass the exact JSON body you would normally send to /v1/messages. Uses the current MCP merchant session by default, or pass auth_token explicitly. Streaming is not supported through the MCP wrapper.",
+        inputSchema: z.object({
+            body_json: z
+                .unknown()
+                .describe('Anthropic-compatible messages request body.'),
+            auth_token: z
+                .string()
+                .optional()
+                .describe('Optional explicit auth token (for example a forward token or spend key). Defaults to the active MCP merchant session key.'),
+            headers: gatewayHeadersSchema,
+        }),
+    }, withErrorHandling(async ({ body_json, auth_token, headers }) => {
+        assertNoStreamingBody(body_json);
+        const normalizedHeaders = buildGatewayHeaders(headers);
+        normalizedHeaders['Content-Type'] = 'application/json';
+        if (!Object.keys(normalizedHeaders).some((key) => key.toLowerCase() === 'anthropic-version')) {
+            normalizedHeaders['anthropic-version'] = '2023-06-01';
+        }
+        const res = await executeGatewayRequest({
+            method: 'POST',
+            path: '/v1/messages',
+            authToken: auth_token,
+            headers: normalizedHeaders,
+            body_json,
+        });
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_forward', {
+        title: 'Call /v1/forward',
+        description: "Generic passthrough to Lava's native provider proxy. Use this for LLM and non-LLM provider APIs such as TTS, transcription, phone calls, search, and profile lookup. target_url must be a Lava-supported provider URL.",
+        inputSchema: z.object({
+            target_url: z
+                .string()
+                .url()
+                .describe('Full upstream provider URL that Lava should forward to.'),
+            method: gatewayMethodSchema
+                .optional()
+                .default('POST')
+                .describe('HTTP method to use for the forwarded request.'),
+            auth_token: z
+                .string()
+                .optional()
+                .describe('Optional explicit auth token (for example a forward token or spend key). Defaults to the active MCP merchant session key.'),
+            headers: gatewayHeadersSchema,
+            ...gatewayBodySchema,
+        }),
+    }, withErrorHandling(async (args) => {
+        assertNoStreamingBody(args.body_json);
+        assertGatewayTargetUrl(args.target_url);
+        const res = await executeGatewayRequest({
+            method: args.method,
+            path: `/v1/forward?u=${encodeURIComponent(args.target_url)}`,
+            authToken: args.auth_token,
+            headers: args.headers,
+            body_json: args.body_json,
+            body_text: args.body_text,
+            body_base64: args.body_base64,
+        });
+        return jsonContent(res);
+    }));
+    server.registerTool('lava_rewrite', {
+        title: 'Call /v1/rewrite',
+        description: "Generic passthrough to Lava's rewrite proxy for cross-provider request/response translation. Use this when your client request format differs from the upstream provider format. target_url must be a Lava-supported provider URL. Streaming is not supported through the MCP wrapper.",
+        inputSchema: z.object({
+            client_format: z
+                .enum(['openai', 'anthropic', 'google', 'bedrock'])
+                .describe('The request/response format your client is sending and expects back.'),
+            target_url: z
+                .string()
+                .url()
+                .describe('Full upstream provider URL that Lava should call after translation.'),
+            method: gatewayMethodSchema
+                .optional()
+                .default('POST')
+                .describe('HTTP method to use for the rewrite request.'),
+            auth_token: z
+                .string()
+                .optional()
+                .describe('Optional explicit auth token (for example a forward token or spend key). Defaults to the active MCP merchant session key.'),
+            input_format: z
+                .enum(['openai', 'anthropic', 'google', 'bedrock'])
+                .optional()
+                .describe('Optional x-lava-input-format override when Lava should treat the request body as a different format than client_format.'),
+            headers: gatewayHeadersSchema,
+            ...gatewayBodySchema,
+        }),
+    }, withErrorHandling(async (args) => {
+        assertNoStreamingBody(args.body_json);
+        assertGatewayTargetUrl(args.target_url);
+        const normalizedHeaders = buildGatewayHeaders(args.headers);
+        if (args.input_format) {
+            normalizedHeaders['x-lava-input-format'] = args.input_format;
+        }
+        const res = await executeGatewayRequest({
+            method: args.method,
+            path: `/v1/rewrite/${args.client_format}?u=${encodeURIComponent(args.target_url)}`,
+            authToken: args.auth_token,
+            headers: normalizedHeaders,
+            body_json: args.body_json,
+            body_text: args.body_text,
+            body_base64: args.body_base64,
+        });
+        return jsonContent(res);
+    }));
+    // Resource: how to use Lava's models (for the AI to explain to the user)
+    server.registerResource('lava_models_guide', 'lava://models-guide', {
+        title: 'How to use Lava models',
+        description: "Explains how to call Lava's proxy to use the listed models. Use when the user or agent asks how to use the models, how to send requests, or how to integrate the gateway.",
+        mimeType: 'text/plain',
+    }, () => {
+        const base = trimTrailingSlash(BASE_URL);
+        const guide = `How to use Lava's models and proxy endpoints
+=============================================
+
+1. List models
+   Call lava_list_models (or GET ${base}/v1/services) to get the full catalog:
+   model id, provider, pricing (tokens_1m, free, etc.), and capabilities
+   (chat, streaming, embeddings, etc.).
+
+   GET ${base}/v1/models returns the same list in OpenAI API format
+   ({ object: "list", data: [{ id, owned_by }] }) for SDK compatibility.
+
+2. Chat completions — OpenAI-compatible unified endpoint
+   The simplest way to use any model regardless of its native provider.
+
+   POST ${base}/v1/chat/completions
+
+   Headers:
+     Authorization: Bearer <your_key>
+     Content-Type: application/json
+
+   Body:
+     { "model": "<model_id>", "messages": [{"role": "user", "content": "Hello"}] }
+
+   Use the exact "id" from lava_list_models as "model".
+   Examples: "gpt-4o", "claude-opus-4-5", "gemini-2.0-flash", "deepseek-chat".
+   The Lava API supports streaming, but these MCP tools do not. For MCP usage,
+   keep "stream": false and use the SDK or direct proxy if you need streaming.
+
+   Lava authenticates the key, routes to the right provider, meters usage,
+   and bills according to the merchant's meter config.
+
+3. Forward proxy — drop-in SDK replacement (no format translation)
+   Point any existing SDK at Lava without changing your code.
+   Lava forwards the request as-is to the provider and handles auth + billing.
+
+   URL structure:
+     ${base}/v1/forward/<provider_url>
+
+   The provider URL can omit the scheme (https:// is assumed).
+
+   Examples:
+
+   a) OpenAI SDK pointing at Lava:
+      Change base URL from https://api.openai.com
+                        to ${base}/v1/forward/api.openai.com
+      The SDK appends /v1/chat/completions → Lava forwards to OpenAI.
+
+   b) Anthropic SDK pointing at Lava:
+      Change base URL from https://api.anthropic.com
+                        to ${base}/v1/forward/api.anthropic.com
+      The SDK appends /v1/messages → Lava forwards to Anthropic.
+
+   Auth: send your Lava key as the Bearer token.
+   Lava substitutes it with the real provider key server-side.
+
+4. Rewrite proxy — cross-format translation
+   Send requests in one SDK format, have Lava translate them to any provider's
+   native format (and translate the response back). Lets you use a single SDK
+   across all providers, including Bedrock and Google native APIs.
+
+   URL structure:
+     ${base}/v1/rewrite/<clientFormat>/<provider_url>
+
+   <clientFormat> is the format YOUR code sends and expects back:
+     openai | anthropic | google | bedrock
+
+   <provider_url> is the full provider endpoint URL (scheme required).
+   The provider's native format is auto-detected from the hostname.
+
+   Auth: send your Lava key as Bearer. Lava injects the real provider key.
+
+   Optional header:
+     x-lava-input-format: <format>   Override auto-detected input format
+                                      (useful when request and response formats differ)
+
+   The Lava API supports streaming, but these MCP tools do not. For MCP usage,
+   keep "stream": false and use the SDK or direct proxy if you need streaming.
+
+   Examples:
+
+   a) OpenAI SDK → Anthropic (use claude models with the OpenAI SDK):
+      POST ${base}/v1/rewrite/openai/https://api.anthropic.com/v1/messages
+      Body: OpenAI chat completions format { model, messages, ... }
+      Response: OpenAI chat completions format (translated from Anthropic)
+
+   b) Anthropic SDK → OpenAI (use GPT models with the Anthropic SDK):
+      POST ${base}/v1/rewrite/anthropic/https://api.openai.com/v1/chat/completions
+      Body: Anthropic messages format { model, messages, max_tokens, ... }
+      Response: Anthropic messages format (translated from OpenAI)
+
+   c) OpenAI SDK → Bedrock (use Bedrock models with the OpenAI SDK):
+      POST ${base}/v1/rewrite/openai/https://bedrock-runtime.us-east-1.amazonaws.com/model/anthropic.claude-3-5-sonnet-20241022-v2:0/converse
+      Body: OpenAI chat completions format
+      Response: OpenAI chat completions format (translated from Bedrock Converse)
+      Note: Bedrock streaming auto-rewrites /converse → /converse-stream.
+
+   d) Anthropic SDK → Bedrock:
+      POST ${base}/v1/rewrite/anthropic/https://bedrock-runtime.us-east-1.amazonaws.com/model/anthropic.claude-3-5-sonnet-20241022-v2:0/converse
+      Body: Anthropic messages format
+      Response: Anthropic messages format (translated from Bedrock Converse)
+
+   e) OpenAI SDK → Google (Gemini native API):
+      POST ${base}/v1/rewrite/openai/https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent
+      Body: OpenAI chat completions format
+      Response: OpenAI chat completions format (translated from Google)
+
+   Provider URL → format auto-detection (by hostname):
+     *.amazonaws.com          → bedrock
+     *.googleapis.com         → google
+     api.anthropic.com        → anthropic
+     everything else          → openai (any OpenAI-compatible API)
+
+   Input format auto-detection (for x-lava-input-format override or ambiguous cases):
+   Resolution order:
+     1. x-lava-input-format header (explicit override — always wins)
+     2. anthropic-version header present → anthropic
+     3. x-goog-api-key header present   → google
+     4. Body structure heuristics:
+          contents[] array                     → google
+          messages[] without model field        → bedrock
+          max_tokens or system + no system role → anthropic
+          default                               → openai
+
+   Other notes:
+   - anthropic-version: 2023-06-01 is auto-injected for Anthropic targets.
+   - Bedrock streaming auto-rewrites /converse → /converse-stream in the URL.
+   - Use lava_list_models to find the correct model IDs for each provider.
+
+5. Anthropic Messages endpoint (direct Anthropic SDK compatibility)
+   An alternative to the rewrite proxy specifically for Anthropic SDK users.
+   Accepts the Anthropic Messages API format natively — no format specified in URL.
+
+   POST ${base}/v1/messages
+
+   Headers:
+     Authorization: Bearer <your_key>
+     anthropic-version: 2023-06-01
+     Content-Type: application/json
+
+   Body (Anthropic Messages format):
+     { "model": "claude-opus-4-5", "max_tokens": 1024,
+       "messages": [{"role": "user", "content": "Hello"}] }
+
+   Response: Anthropic Messages format.
+
+   Use this when you want to point an existing Anthropic SDK at Lava by changing
+   only the base URL to ${base} — no URL rewriting needed.
+   For full cross-provider format translation, use /v1/rewrite instead (section 4).
+
+6. Authentication and keys
+   MCP bootstrap:
+   - If the MCP server starts without LAVA_SECRET_KEY / LAVA_WALLET_KEY, call
+     lava_login. It runs the same browser auth flow as Lava.login() from the
+     Node SDK and stores the returned keys in this MCP session.
+   - To create proxy auth from the active merchant session, call
+     lava_generate_forward_token.
+
+   - Merchant secret key (lava_sk_...): full merchant access; use for server-side
+     proxy calls on behalf of the merchant.
+   - Wallet key (lava_wk_...): authenticates on behalf of an end-user's wallet;
+     used to manage spend keys.
+   - Spend key: a scoped key owned by a wallet. Can restrict to specific models,
+     providers, spend limits, request counts, rate limits, and expiry.
+     Manage via lava_create_spend_key / lava_list_spend_keys (requires an active wallet key from env or lava_login).`;
+        return {
+            contents: [
+                {
+                    uri: 'lava://models-guide',
+                    mimeType: 'text/plain',
+                    text: guide,
+                },
+            ],
+        };
+    });
+    // Resource: merchant overview (read-only summary)
+    server.registerResource('lava_overview', 'lava://overview', {
+        title: 'Lava account overview',
+        description: 'Summary of the Lava account (meters, keys, customers count). Use when the user asks "what do I have set up?"',
+        mimeType: 'application/json',
+    }, async () => {
+        return await withJsonResourceErrorHandling('lava://overview', async () => {
+            const api = getClient();
+            const [metersRes, keysRes, customersRes] = await Promise.all([
+                api.list('/v1/meters', {
+                    limit: 5,
+                }),
+                api.list('/v1/secret_keys', { limit: 5 }),
+                api.list('/v1/customers', { limit: 5 }),
+            ]);
+            const meters = metersRes.data;
+            const keys = keysRes.data;
+            const customers = customersRes.data;
+            return {
+                summary: 'Lava account overview (first 5 of each)',
+                meters_count: meters.length,
+                secret_keys_count: keys.length,
+                customers_count: customers.length,
+                meters: meters.map((m) => ({ id: m.meter_id, name: m.name })),
+                recent_customers: customers.map((c) => c.customer_id),
+            };
+        });
+    });
+    // Resource: full OpenAPI spec (for agent self-discovery of schemas and endpoints)
+    server.registerResource('lava_openapi', 'lava://openapi', {
+        title: 'Lava OpenAPI spec',
+        description: 'Full OpenAPI 3.x spec for the Lava REST API. Use when you need exact request/response schemas, field names, or to discover endpoints not exposed as MCP tools.',
+        mimeType: 'application/json',
+    }, async () => {
+        return await withJsonResourceErrorHandling('lava://openapi', async () => {
+            return await fetchPublic('/v1/openapi');
+        });
+    });
+    // Resource: webhook event types reference
+    server.registerResource('lava_webhook_events', 'lava://webhook-events', {
+        title: 'Lava webhook event types',
+        description: 'Reference for all webhook event types Lava sends to registered webhook URLs. Use when setting up webhooks or handling incoming webhook payloads.',
+        mimeType: 'text/plain',
+    }, () => {
+        const guide = `Lava Webhook Events
+===================
+
+Lava sends POST requests to your registered webhook URL when these events occur.
+Register a URL with lava_create_webhook; Lava will POST JSON to it for each event.
+
+Event types
+-----------
+
+customer.created
+  Fired when an end-user completes the onboarding checkout flow and is linked to your merchant.
+  Use this to provision access, send a welcome message, or update your database.
+
+customer.wallet.balance.updated
+  Fired when a wallet's balance changes — e.g. after a top-up, a usage charge, or a credit allocation.
+  Use this to show the user their new balance or trigger low-balance warnings.
+
+customer.deleted
+  Fired when a customer relationship is removed (either by the merchant or the user).
+  Use this to revoke access or clean up associated records.
+
+Payload shape
+-------------
+Every webhook POST has this JSON body:
+
+{
+  "event": "<event_type>",
+  "data": {
+    "customer_id": "cus_...",
+    "merchant_id": "mer_...",
+    "wallet_id": "wal_...",
+    "account": { ... },
+    "email": { ... },
+    "phone": { ... }
+  }
+}
+
+Verification
+------------
+Lava signs each request with an HMAC-SHA256 signature in the X-Webhook-Signature header.
+Verify it using the webhook secret from your dashboard to ensure the payload is authentic.`;
+        return {
+            contents: [
+                {
+                    uri: 'lava://webhook-events',
+                    mimeType: 'text/plain',
+                    text: guide,
+                },
+            ],
+        };
+    });
+    // Prompt: how to sign up an end-user for Lava
+    server.registerPrompt('lava_sign_up_user', {
+        title: 'Sign up a user for Lava',
+        description: 'Use when the user or developer wants to sign up an end-user for Lava (create wallet, link to merchant). Returns exact steps and tool call.',
+    }, async () => ({
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `The user wants to sign up an end-user for Lava. Do this:
+
+1. Call lava_create_checkout_session with:
+   - checkout_mode: "onboarding"
+   - origin_url: the URL of the app or page the end-user should return to after completing sign-up (must be a valid URL the merchant controls)
+
+2. The API returns a checkout_url. Tell the user to open that URL in a browser. The end-user will complete Lava sign-up (e.g. phone/email, wallet creation) and then be redirected back to origin_url.
+
+3. After onboarding, the end-user becomes a customer on the merchant; use lava_list_customers to see them. To let them subscribe or top up later, use lava_create_checkout_session with checkout_mode "subscription" or "topup" and the customer_id.
+
+Run lava_create_checkout_session now if you have an origin_url (ask for it if not).`,
+                },
+            },
+        ],
+    }));
+    // Prompt: guide for new users
+    server.registerPrompt('lava_get_started', {
+        title: 'Get started with Lava',
+        description: 'Use when the user wants to set up Lava, understand what Lava can do, or get step-by-step guidance. Returns a concrete ordered flow from zero to charging users.',
+    }, async () => ({
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `You're helping someone get started with Lava (usage-based billing for AI). Walk them through the exact steps to go from zero to charging real users. Be concrete and offer to run each tool for them.
+
+**What Lava is in one sentence**: Lava is a billing layer you drop in front of any AI API — your users pay Lava, Lava pays you, and you set the prices.
+
+**Zero-to-charging-users in 5 steps**:
+
+Step 0 — Authenticate this MCP session
+  If the MCP was started without env keys, call lava_login first. That loads both the merchant secret key and wallet key into this MCP session.
+
+Step 1 — Create a meter (how you price usage)
+  Call lava_create_meter. A meter defines what you count (tokens, requests, etc.) and what you charge.
+  Simplest example: flat rate, $1 per million tokens:
+    name: "Chat API", slug: "chat-api", unit_label: "token"
+    rate_type: "flat", tier_type: "per_unit"
+    tiers: [{ start: "0", rate: "0.000001" }]
+  Ask: "What do you want to charge for? Tokens, requests, or something else?"
+
+Step 2 — Create a plan (optional but recommended)
+  Call lava_create_plan to create a plan that can include an optional recurring fee, included credit, and linked meters.
+    Example: name: "Pro", period_amount: "10", billing_interval: "month", included_credit: "10.00", meter_ids: ["mtr_..."]
+  Skip this step if you just want pay-as-you-go with no monthly fee.
+
+Step 3 — Sign up your first user
+  Call lava_create_checkout_session with checkout_mode: "onboarding" and origin_url (your app's URL).
+  Give the returned checkout_url to your user to open in a browser. They create a Lava wallet and get linked to you.
+  After they complete it, call lava_list_customers to see them. They now have a customer_id.
+
+Step 4 — Point your app at Lava's proxy
+  Change your AI client's base URL to https://api.lava.so and use a Lava forward token as the bearer token.
+  The proxy bills the user automatically for every request. No code changes beyond base URL + auth.
+  If you want to prove the route inside this MCP before changing app code, call lava_chat_completions, lava_messages, lava_forward, or lava_rewrite directly.
+  Or, if you run your own integration, call lava_track_request after each AI call to record usage manually.
+
+**After that**: call lava_get_usage to see billing data, lava_list_customers to see your users, lava_create_checkout_session (mode "topup" or "subscription") to let users add funds or subscribe.
+
+Ask the user which step they want to start with, then run the relevant tool.`,
+                },
+            },
+        ],
+    }));
+    // Prompt: how to integrate Lava into an existing app
+    server.registerPrompt('lava_integrate', {
+        title: 'Integrate Lava into your app',
+        description: "Use when the user wants to add Lava billing to an existing app. Returns concrete code examples for pointing OpenAI/Anthropic SDKs at Lava's proxy.",
+    }, async () => ({
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `You're helping a developer integrate Lava billing into their existing app. Show them the exact code change needed — it's just changing a base URL and auth token. Be concrete.
+
+**The core idea**: Lava's proxy accepts standard OpenAI, Anthropic, and other AI API formats. You point your existing SDK at Lava instead of the AI provider, and Lava handles billing automatically.
+
+**What you need first**:
+- A merchant auth context. Inside this MCP, either call lava_login or use an existing merchant secret key from lava_list_secret_keys / lava_create_secret_key.
+- A forward token (from lava_generate_forward_token) or another valid Lava bearer token for the gateway
+- Your user must have an active Lava customer record (created via lava_create_checkout_session with checkout_mode "onboarding")
+
+**Code examples**:
+
+Python (OpenAI SDK → Lava proxy):
+\`\`\`python
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="https://api.lava.so/v1",
+    api_key="YOUR_LAVA_GATEWAY_TOKEN",  # forward token or spend key
+)
+
+response = client.chat.completions.create(
+    model="openai/gpt-4o",   # prefix with provider: openai/, anthropic/, google/, etc.
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+\`\`\`
+
+TypeScript/JavaScript (OpenAI SDK → Lava proxy):
+\`\`\`typescript
+import OpenAI from 'openai';
+
+const client = new OpenAI({
+  baseURL: 'https://api.lava.so/v1',
+  apiKey: 'YOUR_LAVA_GATEWAY_TOKEN',  // forward token or spend key
+});
+
+const response = await client.chat.completions.create({
+  model: 'openai/gpt-4o',
+  messages: [{ role: 'user', content: 'Hello!' }],
+});
+\`\`\`
+
+Python (Anthropic SDK → Lava proxy using /v1/messages):
+\`\`\`python
+import anthropic
+
+client = anthropic.Anthropic(
+    base_url="https://api.lava.so",
+    api_key="YOUR_LAVA_GATEWAY_TOKEN",
+)
+
+message = client.messages.create(
+    model="anthropic/claude-sonnet-4-6",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+\`\`\`
+
+TypeScript (Anthropic SDK → Lava proxy):
+\`\`\`typescript
+import Anthropic from '@anthropic-ai/sdk';
+
+const client = new Anthropic({
+  baseURL: 'https://api.lava.so',
+  apiKey: 'YOUR_LAVA_GATEWAY_TOKEN',
+});
+\`\`\`
+
+**Model names**: Prefix with the provider slug. Examples:
+- OpenAI: \`openai/gpt-4o\`, \`openai/gpt-4o-mini\`
+- Anthropic: \`anthropic/claude-opus-4-6\`, \`anthropic/claude-sonnet-4-6\`
+- Google: \`google/gemini-2.0-flash\`
+Call lava_list_models to see all available models and their exact slugs.
+
+**Per-customer billing**: Generate one forward token per customer using lava_generate_forward_token with the customer_id and meter_slug. When the user makes a request, pass that forward token as the bearer token so Lava bills the right customer and meter.
+
+**If you can't change the base URL** (e.g. third-party lib): Use lava_track_request after each AI call to manually record usage. You'll need the customer_id, meter_slug, and token counts.
+
+Ask which language/SDK they use and offer to help adapt the example.`,
+                },
+            },
+        ],
+    }));
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    // biome-ignore lint/suspicious/noConsole: ok
+    console.error(`Lava MCP failed to start: ${message}`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map