Lava MCP Tool Reference

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 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:

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:

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:

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:

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:

Run the "Weekly engineering update" workflow.

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:

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:

Call https://google.serper.dev/search with q="lava payments".

{
  "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:

Find search providers in Lava.

{
  "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:

What endpoints does Serper expose?

{
  "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:

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:

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:

Connect Slack to Lava.

{
  "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:

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:

What services do I have connected?

{
  "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:

What's my Lava balance?

{
  "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:

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:

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:

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.
404 — Provider, workflow, or session not found.
429 — Rate limit reached. Retry with backoff.

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

Get Started

Connected Providers

Funds

Reference

Productivity

`list_workflows`

`get_workflow_authoring_guide`

`get_workflow_document`

`save_workflow`

`run_workflow`

`call_mcp`

`call_api`

Providers

`list_providers`

`get_provider_details`

`get_provider_docs`

`request_provider`

Connected providers

`connect_service`

`disconnect_service`

`list_keys`

Funds

`get_balance`

`add_funds`

`get_usage_history`

`create_referral`

Auth Status Values

Error Codes

Get Started

Connected Providers

Funds

Reference

Documentation Index

​Productivity

​list_workflows

​get_workflow_authoring_guide

​get_workflow_document

​save_workflow

​run_workflow

​call_mcp

​call_api

​Providers

​list_providers

​get_provider_details

​get_provider_docs

​request_provider

​Connected providers

​connect_service

​disconnect_service

​list_keys

​Funds

​get_balance

​add_funds

​get_usage_history

​create_referral

​Auth Status Values

​Error Codes

​Related

Productivity

`list_workflows`

`get_workflow_authoring_guide`

`get_workflow_document`

`save_workflow`

`run_workflow`

`call_mcp`

`call_api`

Providers

`list_providers`

`get_provider_details`

`get_provider_docs`

`request_provider`

Connected providers

`connect_service`

`disconnect_service`

`list_keys`

Funds

`get_balance`

`add_funds`

`get_usage_history`

`create_referral`

Auth Status Values

Error Codes

Related