Skip to main content

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.

The Lava MCP exposes the tools below to any connected chat client. 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:
  • ask — delegate the whole task. Lava plans across services, fetches what’s needed, and returns a result.
  • list_workflows, save_workflow, run_workflow — save a past ask as a reusable workflow and replay it.
  • 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

Delegate a multi-step task to Lava. Lava plans across connected services, fetches what’s needed, and returns a result. Trigger by saying “ask lava” in your chat. Use ask for cross-service retrieval, multi-step workflows, synthesis, and extraction. For single API calls where you already know the target_url, use call_api instead. Parameters:
  • question (string, required): What you want Lava to do. Up to 10,000 characters.
  • workflow_disabled (boolean, optional): Defaults to false. When true, Lava will not suggest running a saved workflow even if the question matches one.
Returns: A structured result containing Lava’s answer, intermediate steps, any data retrieved, and an ask_session_id you can pass to save_workflow to persist the run. Example: 
Ask Lava: find every mention of "Acme" across my Gmail and Slack from the last week and summarize.

​
list_workflows

List your saved workflows. Use to find a workflow_id for run_workflow. 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.

​
save_workflow

Save a past ask session as a reusable workflow. Returns a review URL that opens in the dashboard. The workflow is not persisted until you confirm it in the dashboard. Parameters:
  • session_id (string, optional): The ask_session_id returned by the relevant ask or run_workflow response. Prefer passing this explicitly. Omit only when no such ID is available — the caller’s most recent ask session is used as a fallback. 1–64 characters.
Returns: An object with review_url (open this in a browser to review the draft) and source metadata. Example: 
Save my last Lava ask as a workflow.

​
run_workflow

Execute a saved workflow by ID. 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.
Returns: A structured result, the same shape as ask (including ask_session_id). Example: 
Run the "Weekly engineering update" workflow.

​
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 Linear to list my open issues.

​
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 ask, 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": "2026-04-29T15: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,maximum10, 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.