> ## 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](https://lava.so/docs/mcp/quickstart.md) and the how-to guides.

## Productivity

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

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

Saved workflows are authored and run in Lava Desktop, not from chat. The MCP
workflow tools were retired on 2026-09-08: the Lava cloud agent is the only
path that writes a workflow, and Lava executes the workflows it saves rather
than handing a recipe to a host model.

### `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.
* `account` (string, optional): The Connector account id from `get_provider_details` `connections`, when several accounts of the service are connected. Omit it to use the default, the account connected first.

**Returns**: The remote tool's result, decoded. When several accounts of the service are connected, `_lava_connector_account` names the one that answered.

**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. To use one of several connected accounts, set `x-lava-connector-account` to its id from `get_provider_details` `connections`; without it the call uses the default, the account connected first.
* `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`, `connections`, capability list, and a list of endpoints. `connections` lists each connected account by `id` and `account_label`; with several accounts of one provider, `default: true` marks the one a call that names none uses, listed first, and `connection_selection` says how to choose. 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`.

Desktop-session apps such as ChatGPT use their own sign-in inside Lava. Open the app to sign in or switch accounts. `connect_service` rejects these apps and does not create an authorization URL.

**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"`).
* `reconnect` (boolean, optional): Re-run authorization for a connected service, to switch or repair its account.
* `add_account` (boolean, optional): Connect another account beside the connected ones, such as a work account next to a personal one. Lava Pay and Desktop-session apps hold one account.
* `account` (string, optional): With `reconnect`, the Connector account id from `get_provider_details` `connections` to repair.

**Returns**: An object with:

* `status`: `already_connected` (nothing to do), `unsupported` (the request cannot be met, for example a second account of a single-account provider), or a status starting with `pending` (a link is out; nothing is stored until the user finishes it).
* `provider`: the provider key the connection is stored under.
* `authorization_url`: on a pending status, the link the user must open.
* `expires_at`: on a pending status, when the link stops working (ISO 8601).
* `hint`: what to tell the user or do next.

A pending link can finish at any time after it is returned. Call `get_provider_details` again before saying whether it did.

**Example**:

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

```json theme={null}
{
  "status": "pending_oauth",
  "provider": "slack",
  "authorization_url": "https://www.lava.so/v1/credentials/slack/connect?...",
  "expires_at": "2026-10-15T18:10:00.000Z",
  "hint": "Open the authorization URL to authorize slack..."
}
```

### `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`.
* `account` (string, optional): The Connector account id from `get_provider_details` `connections` to disconnect. Omit it to disconnect every account of the provider.

**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](https://lava.so/docs/mcp/funds.md).
* `404` — Provider, workflow, or session not found.
* `429` — Rate limit reached. Retry with backoff.

## Related

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.