## Documentation Index

Fetch the complete documentation index at: [/docs/llms.txt](/content/docs/llms.txt)

Use this file to discover all available pages before exploring further.

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.

Looking for full SDK reference? See the [Node.js SDK](/content/docs/sdk/nodejs/index.html) and [Checkout SDK](/content/docs/sdk/checkout/index.html) pages for complete method documentation.

## 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 Code

- Codex

- Manual JSON

```
claude mcp add lava -- npx -y @lavapayments/mcp
```

```
codex mcp add lava https://www.lava.so/mcp
```

Add the following to your MCP config file:

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

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:

```javascript
// 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](/content/docs/agents/route-traffic/index.html)

[**Bill Your Customers** \\  Set up usage-based pricing and checkout](/content/docs/agents/bill-customers/index.html)

[**Manage AI Spend** \\  Create scoped API keys with spend limits](/content/docs/agents/manage-spend/index.html)

[**SDK Reference** \\  Full Node.js SDK documentation](/content/docs/sdk/nodejs/index.html)