Skip to main content
This guide covers two different agent setup paths that should not be conflated:
  • MCP flow: your host already runs the Lava MCP server, and the agent should authenticate the current MCP session with login
  • SDK flow: you are writing Node.js agent code and want to call Lava.login() directly
Choose one path and follow only that path.

​
Prerequisites

  • Node.js 18+
  • A terminal

​
MCP flow

Use this when the agent is running inside Claude Code, Claude Desktop, Cursor, or another MCP-capable host with the Lava MCP server configured.

​
1. Install the MCP server

claude mcp add lava -- npx -y @lavapayments/mcp
No pre-provisioned keys are needed — you’ll authenticate in the next step.

​
2. Authenticate the MCP session

Ask the agent to call:
  • login to authenticate via the Lava browser login flow
  • prompt to send chat completions to any AI model (all models use OpenAI format)
  • call to execute any API call through the gateway (non-LLM APIs or native provider format)
  • search to find available API providers by natural language query
  • get_provider_docs to fetch upstream API documentation for a provider
login loads your merchant credentials and auto-provisions a spend key for gateway access. No manual token generation needed.
Use the MCP flow if your goal is to operate Lava from an agent host. Do not import the SDK just to get credentials when the MCP is already available.

​
SDK flow

Use this when you are writing application or CLI code yourself and want to authenticate from Node.js.

​
1. Install the SDK

npm install @lavapayments/nodejs

​
2. Authenticate

Lava.login() opens your browser, lets you sign up or log in, and returns your API credentials automatically. 
import { Lava } from '@lavapayments/nodejs';

const credentials = await Lava.login();

console.log(credentials);
// {
//   secret_key: 'aks_live_...',
//   secret_key_id: 'sk_...',
//   merchant_id: 'mer_...',
//   wallet_id: 'wa_...'
// }
If you don’t have an account yet, Lava.login() will take you through sign-up first. No separate registration step needed.

​
3. What happens under the hood

  1. A local HTTP server starts on a random port
  2. Your browser opens to Lava’s authorization page
  3. You sign up or log in and click “Authorize”
  4. Credentials flow back to your terminal
  5. The local server shuts down
The entire flow takes about 10 seconds.

​
Initialize the SDK

Use the secret key as your SDK credential: 
const lava = new Lava(credentials.secret_key);
Store your credentials in environment variables or a secrets manager. You only need to run Lava.login() once.
# Save to your environment
export LAVA_SECRET_KEY="aks_live_..."
Then initialize without hardcoding: 
// Reads LAVA_SECRET_KEY from environment automatically
const lava = new Lava();

​
Alternative: Exchange an Auth Code Directly

If you’re building a custom auth flow (for example, handling the browser callback yourself), use Lava.exchangeAuthCode() instead: 
const credentials = await Lava.exchangeAuthCode({
  code: 'your_one_time_auth_code'
});
Auth codes expire after 60 seconds and can only be used once.

​
What’s Next?

Route Traffic

Route live traffic after choosing MCP or SDK flow

Bill Your Customers

Set up usage-based pricing and checkout

Manage AI Spend

Create scoped API keys with spend limits

SDK Reference

Full Node.js SDK documentation