> ## Documentation Index
> Fetch the complete documentation index at: https://lava.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Lava MCP Tool Reference

> Every tool the Lava MCP exposes — parameters, returns, and a canonical example for each.

The Lava MCP is a remote MCP server hosted at `https://www.lava.so/mcp`. It exposes the tools below to any AI chat connected to it. Tool names, descriptions, and parameters reflect the registrations in the MCP server. Tools are grouped by what you do with them: **Productivity** (have Lava do work), **Providers** (browse the catalog), **Connected providers** (authorize providers on your behalf), and **Funds** (pay for usage). For working examples in context, see the [Quickstart](/mcp/quickstart) and the how-to guides.

## Productivity

Tools that have Lava do work on your behalf. They span a spectrum of abstraction:

* `list_workflows`, `get_workflow_document`, `save_workflow`, `run_workflow`, `get_workflow_authoring_guide` — author, edit, and run reusable workflows directly from chat.
* `call_mcp` — invoke a single tool on a connected federated MCP service (Linear, Granola, and similar).
* `call_api` — invoke a single HTTP endpoint directly when you already know the `target_url`.
* `ask` — Lava's legacy planner/executor agent. **Deprecated, scheduled for removal 2026-05-15.** Migrate to `call_api` (one-off retrieval) or `save_workflow` + `run_workflow` (repeatable tasks).

The five workflow tools form a single lifecycle:

| Intent                    | Tools                                                                             |
| ------------------------- | --------------------------------------------------------------------------------- |
| Discover what's saved     | `list_workflows`                                                                  |
| Execute a workflow        | `list_workflows` → `run_workflow`                                                 |
| Author a new workflow     | `get_workflow_authoring_guide` → `save_workflow`                                  |
| Edit an existing workflow | `list_workflows` → `get_workflow_document` → `save_workflow` (with `workflow_id`) |

### `list_workflows`

List your saved workflows. The starting point for every other workflow tool — pass a returned `workflow_id` to `run_workflow` (execute), `get_workflow_document` (read source for editing), or `save_workflow` with `workflow_id` (update).

**Parameters**: None.

**Returns**: An object with `total` (count) and `results` (array). Each workflow has `workflow_id`, `name`, `description`, `triggers`, `providers`, and `inputs`.

**Example**:

```text theme={null}
Show me my saved Lava workflows.
```

### `get_workflow_authoring_guide`

Fetch the workflow authoring guide — the YAML frontmatter shape, body conventions, reserved input names, and worked examples. Read once before calling `save_workflow` to author a new workflow. To edit an existing workflow, use `get_workflow_document` instead — its raw source is already valid against this format.

**Parameters**: None.

**Returns**: An object with the full `guide` text plus a `hint` describing how to use it.

**Example**:

```text theme={null}
How do I author a Lava workflow?
```

### `get_workflow_document`

Fetch the raw `document` (YAML frontmatter + markdown body) for one saved workflow. Use this to read a workflow's source before editing it; resubmit the modified document via `save_workflow` with the same `workflow_id`. To execute a workflow instead, use `run_workflow`.

**Parameters**:

* `workflow_id` (string, required): Workflow ID. Obtain from `list_workflows`.

**Returns**: An object with `workflow_id`, `name`, `description`, `triggers`, `providers`, `inputs`, the raw `document` string, and timestamps.

**Example**:

```text theme={null}
Show me the document for my "Weekly engineering update" workflow.
```

### `save_workflow`

Create or update a workflow by submitting a complete document. Omit `workflow_id` to create — pair with `get_workflow_authoring_guide` for the format. Pass `workflow_id` to update — pair with `get_workflow_document` to read the current source first, modify it, then resubmit. Validation matches the dashboard: unknown providers, malformed YAML, reserved input names, or duplicate names within your account return an error.

**Parameters**:

* `document` (string, required): Full workflow document — YAML frontmatter (name, description, triggers, providers, inputs) followed by a markdown body of step-by-step instructions. Up to 8,000 characters.
* `workflow_id` (string, optional): Pass to update an existing workflow. Omit to create a new one.

**Returns**: An object with the saved workflow's `workflow_id`, `name`, `description`, `triggers`, `providers`, `inputs`, and the persisted `document`.

**Example**:

```text theme={null}
Save a workflow that searches Serper for the latest news on a given company.
```

### `run_workflow`

Run a saved workflow by ID. Default behavior returns the prepared instructions so you drive execution via your own tools; opt in to Lava's agent only when you intentionally want it.

**Parameters**:

* `workflow_id` (string, required): Workflow ID. Obtain from `list_workflows`.
* `inputs` (object, optional): Workflow inputs keyed by input name. Each value is a string up to 5,000 characters. Obtain the declared input names from `list_workflows`. Omit for workflows with no declared inputs.
* `use_lava_agent` (boolean, optional, default `false`):
  * `false` (default): Lava returns the workflow steps, bound inputs, resolved provider endpoints, federated MCP services, and per-provider auth status. Drive execution yourself via `call_api`, `call_mcp`, and `connect_service`. For most in-chat usage this is the right path — the calling agent is already the right place to drive execution.
  * `true`: Lava's agent runs the workflow end-to-end and returns the result.

**Returns**:

* Default (`use_lava_agent: false`): An object with `workflow_id`, `name`, `description`, `bound_inputs`, `providers` (each entry includes an `auth_status`), `endpoints`, `mcp_services`, the prepared `instructions` system prompt, and a `hint` flagging any providers that require `connect_service` first.
* With `use_lava_agent: true`: A structured agent result.

**Example**:

```text theme={null}
Run the "Weekly engineering update" workflow.
```

```text theme={null}
Get the steps for the "Weekly engineering update" workflow so I can run them myself.
```

### `call_mcp`

Invoke a tool on a connected federated MCP service (Linear, Granola, and similar). Prerequisite: `connect_service` must have completed for the service.

`call_mcp` speaks the MCP protocol; `call_api` speaks HTTP. They are not substitutes for each other.

**Parameters**:

* `service` (string, required): Connected service name — for example, `"linear"`, `"granola"`. Call `list_providers` for the full list.
* `tool` (string, required): Tool name from the remote service's catalog. Call `get_provider_details` first to list available tools on the service.
* `arguments` (object, optional): Arguments to pass to the remote tool. Defaults to an empty object.

**Returns**: The remote tool's result, decoded.

**Example**:

```text theme={null}
Use Granola to pull the transcript from my last meeting.
```

### `call_api`

Execute an HTTP API call directly through Lava. Use when you already know the `target_url` and want to skip discovery. Auth is automatic.

For external MCP services (such as Linear or Granola), use `call_mcp` instead — `call_api` is for HTTP APIs only.

**Parameters**:

* `target_url` (string, required): Full upstream URL — for example, `https://api.dune.com/...`.
* `method` (enum, optional): One of `"GET"`, `"POST"`, `"PUT"`, `"PATCH"`, `"DELETE"`. Defaults to `"POST"`.
* `headers` (object, optional): Extra request headers. Do not set `Authorization` — Lava handles auth.
* `body_json` (any, optional): JSON request body.
* `body_text` (string, optional): Plain-text request body. Mutually exclusive with `body_json`.
* `filter` (object, optional): Server-side response filters. Only supported by providers whose `get_provider_details` notes mention filter support; ignored elsewhere.

**Returns**: An object with `status` and `body`. The `body` is the upstream provider's response, decoded.

**Example**:

```text theme={null}
Call https://google.serper.dev/search with q="lava payments".
```

```json theme={null}
{
  "status": 200,
  "body": {
    "organic": [
      { "title": "Lava — Payments for AI APIs", "link": "https://lava.so" }
    ]
  }
}
```

## Providers

Tools for browsing the Lava catalog and looking up provider details. Read-only — these don't change account state.

### `list_providers`

Discover what is available in Lava's catalog. Search by keyword. A valid first step when you don't know which provider to use.

**Parameters**:

* `query` (string, optional): Short keywords work best — for example, `"search"`, `"blockchain"`, `"slack"`, `"weather"`. Use 1–2 words, not full sentences.
* `category` (string, optional): Optional category filter — `"model"` or `"service"`.

**Returns**: A list of provider summaries. Each entry includes a provider ID, label, summary, category, and an `auth_status` field (`ready`, `user_ready`, or `setup_required`).

**Example**:

```text theme={null}
Find search providers in Lava.
```

```json theme={null}
{
  "results": [
    {
      "provider": "serper",
      "label": "Serper",
      "summary": "Web search API.",
      "auth_status": "user_ready"
    }
  ]
}
```

### `get_provider_details`

Get endpoint URLs, methods, request body format, and `auth_status` for a single provider. Use when you need a `target_url` for `call_api` or to confirm whether a provider needs `connect_service`.

**Parameters**:

* `provider` (string, required): Provider identifier from `list_providers` (for example, `"serper"`, `"dune"`, `"exa"`).

**Returns**: An object with the provider's `id`, `label`, `summary`, `category`, `auth_status`, capability list, and a list of endpoints. Each endpoint includes a `description`, `target_url`, `method`, and optional `body_json` schema. Catch-all providers also return a `routing_hint`.

**Example**:

```text theme={null}
What endpoints does Serper expose?
```

```json theme={null}
{
  "provider": "serper",
  "auth_status": "user_ready",
  "endpoints": [
    {
      "description": "Web search",
      "target_url": "https://google.serper.dev/search",
      "method": "POST"
    }
  ]
}
```

### `get_provider_docs`

Fetch upstream API documentation for a provider. Use when the endpoint examples from `get_provider_details` aren't enough.

**Parameters**:

* `provider` (string, required): Provider ID — for example, `"openai"`, `"anthropic"`, `"serper"`, `"dune"`.

**Returns**: The provider's API reference text, plus `llms.txt` if the provider publishes one. Long responses are truncated with a link to the full source.

**Example**:

```text theme={null}
Get the full Anthropic API docs.
```

### `request_provider`

Request that Lava add a provider that is not already in the catalog. Always call `list_providers` first to confirm the provider isn't already supported.

**Parameters**:

* `provider_name` (string, required): Name of the provider to add — for example, `"Acme"`. Up to 255 characters.
* `provider_url` (string, optional): Website or docs URL for the provider. Up to 1,024 characters.
* `notes` (string, optional): How you would use it, or any other context. Up to 4,000 characters.

**Returns**: A confirmation banner with the request status. The Lava team triages provider requests and may reach out by email.

**Example**:

```text theme={null}
Request that Lava add Acme as a provider. Their docs are at acme.example.com/docs.
```

## Connected providers

Tools for authorizing providers on your behalf. Connecting a provider grants Lava the permission to call it for you — through OAuth, an API-key entry page, or a federation handshake, depending on the service.

### `connect_service`

Connect a provider to Lava. Starts an OAuth flow or opens a secure browser page for API-key entry, depending on what the service requires. Required before `call_api` or `call_mcp` can use a provider with `auth_status: setup_required`.

**Parameters**:

* `service` (string, required): Service ID from the provider catalog — for example, `"slack"`, `"serper"`, `"granola"`. Multi-tenant providers use `"{provider}:{tenant-hostname}"` (currently Canvas — for example, `"canvas:canvas.yale.edu"`).

**Returns**: An object with `url` (the authorization URL the user must open) and `expires_in` (seconds until the URL expires).

**Example**:

```text theme={null}
Connect Slack to Lava.
```

```json theme={null}
{
  "url": "https://www.lava.so/auth/connect/slack?session=...",
  "expires_in": 600
}
```

### `disconnect_service`

Disconnect a provider from Lava. Removes the stored credential for an HTTP provider, or revokes the federation connection for a federated MCP service. Use `connect_service` to reconnect.

**Parameters**:

* `service` (string, required): Service ID. Same format as `connect_service`.

**Returns**: A confirmation that the service was disconnected.

**Example**:

```text theme={null}
Disconnect Slack from Lava.
```

### `list_keys`

List the providers you have authorized, with credential fingerprints. Only shows providers you have connected — providers Lava manages do not appear.

**Parameters**: None.

**Returns**: An array of connected services, each with a service ID, connection timestamp, and credential fingerprint.

**Example**:

```text theme={null}
What services do I have connected?
```

```json theme={null}
{
  "data": [
    { "service": "slack", "connected_at": "2024-01-01T00:00:00Z" }
  ]
}
```

## Funds

Tools for paying for usage. Lava bills paid providers from your account balance.

### `get_balance`

Check your Lava account balance.

**Parameters**: None.

**Returns**: An object with `balance` (USD, expressed as a decimal string) and an optional `addFundsUrl` for one-click funding.

**Example**:

```text theme={null}
What's my Lava balance?
```

```json theme={null}
{
  "balance": "47.50"
}
```

### `add_funds`

Add funds to your Lava account. Three modes depending on the parameters you pass.

**Parameters**:

* `amount` (string, optional): USD amount — for example, `"25.00"`. Minimum $10, maximum $10,000.
* `payment_method_id` (string, optional): Charge a saved payment method directly.
* `use_checkout` (boolean, optional): Open a browser page to add funds. Use when you have no saved payment method or prefer the browser flow.

**Returns**: One of three shapes:

* Called with no arguments: a list of saved payment methods plus current account state.
* Called with `payment_method_id` and `amount`: the funding result, with the new balance.
* Called with `use_checkout: true`: an object with `status: "browser_flow_required"`, `url`, and `expires_in`.

**Example**:

```text theme={null}
Add $25 to my Lava account using my saved card.
```

### `get_usage_history`

View MCP-originated usage. Two modes: `"summary"` (default, daily aggregates) and `"requests"` (row-level list of individual calls).

**Parameters**:

* `mode` (enum, optional): `"summary"` (default) returns daily spend and request counts. `"requests"` returns individual calls.
* `start` (string, optional): ISO 8601 start date. Summary mode only. Defaults to 7 days ago.
* `end` (string, optional): ISO 8601 end date. Summary mode only. Defaults to now.
* `cursor` (string, optional): Pagination cursor. Requests mode only.
* `limit` (integer, optional): Results per page. Requests mode only. 1–100, default 10.

**Returns**: In summary mode, daily aggregates of spend and request counts. In requests mode, a paginated list of individual calls with provider, model, cost, and status.

**Example**:

```text theme={null}
Show me my Lava usage for the last 7 days.
```

### `create_referral`

Invite a friend to Lava by email. You earn matching credits up to \$10 when they sign up and add funds.

**Parameters**:

* `email` (string, required): Email address to invite.

**Returns**: A confirmation banner with the referral status.

**Example**:

```text theme={null}
Invite alice@example.com to Lava.
```

## Auth Status Values

Several tools return an `auth_status` field. The values:

* `ready` — Lava manages the credential. Call the provider directly.
* `user_ready` — You have connected your own credential. Call the provider directly.
* `setup_required` — Call `connect_service` first.

## Error Codes

Common errors returned by the tools above:

* `401` — Unauthorized. Provide a valid Lava secret key as a Bearer token.
* `402` — Insufficient account balance. See [How to Fund Your Lava Account](/mcp/funds).
* `404` — Provider, workflow, or session not found.
* `429` — Rate limit reached. Retry with backoff.

## Related

* [How to Install the Lava MCP](/mcp/install) — claude.ai (web), Claude Desktop, Claude Code, and Team or Enterprise installs.
* [Quickstart](/mcp/quickstart) — install Lava and make your first call.
* [How to Connect Services through Lava MCP](/mcp/connect-services) — connect, verify, and remove providers.
* [How to Fund Your Lava Account](/mcp/funds) — fund your account and review usage.