How do I use Grounder with LiteLLM?

To use Grounder (grounder.net) with LiteLLM, make a Grounder search key, add one search tool that points LiteLLM's Tavily search at https://api.grounder.net/compat/tavily, and add Grounder as an MCP server that only your chosen keys can see.

Last checked: 5 November 2026. Disclosure: Grounder (grounder.net) publishes this page. LiteLLM is a separate open-source project by BerriAI, and the config below was checked against LiteLLM 1.108.0.

Three ways to use Grounder through LiteLLM

All three use one Grounder search key. The first two share one search_tools entry. The MCP route is separate: it has its own server entry, its own access check and its own cost line.

Make the key

Make a key under Search keys on your Grounder account and store it as GROUNDER_API_KEY where LiteLLM runs; it is shown once. For a gateway that many people share, choose Search only under Access when you create it: that key can search and list providers and can do nothing else on your account. A key made with Full access, the default, also manages your account and workspaces, which is what you want in your own terminal and not in a shared gateway. Grounder does issue new keys; a write-up that says it does not predates search keys. The HTTP API docs describe the key and the OAuth alternative.

The recommended config

This is one config.yaml with all three routes. The model entry stands in for your own.

model_list:
  - model_name: claude-haiku
    litellm_params:
      model: bedrock/anthropic.claude-haiku-4-5-v1:0

litellm_settings:
  callbacks: ["websearch_interception"]
  websearch_interception_params:
    enabled_providers: ["bedrock", "vertex_ai"]
    search_tool_name: grounder

search_tools:
  - search_tool_name: grounder
    litellm_params:
      search_provider: tavily
      api_base: https://api.grounder.net/compat/tavily
      api_key: os.environ/GROUNDER_API_KEY
      input_cost_per_query: 0.019
      max_results: 10
    search_tool_info:
      description: Licensed web search from Grounder, merged and ranked across providers

mcp_servers:
  grounder:
    url: https://api.grounder.net/mcp
    transport: http
    auth_type: bearer_token
    auth_value: os.environ/GROUNDER_API_KEY
    description: Licensed web search from Grounder, merged and ranked across providers
    allowed_tools: ["search", "list_providers"]
    access_groups: ["web-search"]
    mcp_info:
      server_name: "Grounder – Licensed Meta Grounding Service"
      logo_url: https://grounder.net/brand/grounder-icon-256.png
      mcp_server_cost_info:
        tool_name_to_cost_per_query:
          search: 0.019

What each choice does:

• One search tool, grounder. It uses Grounder's Tavily-shaped endpoint, which takes max_results up to 100. enabled_providers lists the LiteLLM providers whose models should search through Grounder; LiteLLM's default is Bedrock only.
• max_results: 10. LiteLLM passes everything in a search tool's litellm_params except search_provider on to the search, although its documentation lists only api_key, api_base, timeout, max_retries and input_cost_per_query. Without it, Grounder returns its default of 5 results.
• allowed_tools. A full Grounder key sees seven MCP tools, among them ones that create, update and delete workspaces. LiteLLM shows and runs only the two listed, whatever key it holds; a call to any other fails with Tool delete_workspace is not allowed for server grounder. LiteLLM accepts the names with or without the grounder- prefix.
• access_groups in place of allow_all_keys. Only LiteLLM keys in the web-search group see the server. A key outside the group gets an empty tool list and a refusal on the server's address. With allow_all_keys: true every key would see the two tools.
• The server key stays grounder. LiteLLM builds the tool names (grounder-search) and the server's address (/grounder/mcp) from it, and users paste this config. LiteLLM refuses a hyphen in a server key, so a longer name could not be written the usual way.
• mcp_info.server_name. The display name is set without changing the key. It changes the server's name in the admin UI's tool views and in the MCP columns of the logs. The card's title in the server list stays grounder, which is the key. The tool names, the address and the server ID were identical with and without it. The name uses an en dash, because LiteLLM refuses a plain hyphen in names.
• Logo and descriptions. logo_url replaces the grey "GR" box on the server's card; description and search_tool_info.description fill the description columns of the server list and the Search Tools page. The logo address is the permanent one for Grounder's square icon, so it will not move.
• Cost on both routes. input_cost_per_query prices each search on the search-tool routes, and tool_name_to_cost_per_query prices each search tool call on the MCP route; list_providers is free. Without the second, LiteLLM logs an MCP search at zero.

Give a key access

A key reaches Grounder's MCP server when it belongs to the web-search group. Make a key with the group from the admin UI, or through LiteLLM's key API:

curl -X POST $LITELLM_URL/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"object_permission": {"mcp_access_groups": ["web-search"]}}'

A LiteLLM team can hold the same group, and a Toolset (under MCP in the admin UI) can hold Grounder's search for a team instead.

To check the guard, list the tools as a key outside the group and as a key inside it:

curl -s $LITELLM_URL/grounder/mcp \
  -H "Authorization: Bearer $LITELLM_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

A key outside the group is refused. A key inside it lists grounder-search and grounder-list_providers, and nothing else. Listing tools does not run a search.

A search-only key is the first guard, and it is Grounder's own: Grounder refuses it the account tool, the workspace tools and the account endpoints, and lists it search and list_providers only, over MCP and the HTTP API. allowed_tools and the access group are a second layer in LiteLLM. Your own client, signed in or with your own full key, still creates, changes and deletes your workspaces as before. Grounder's own deployment shows this: such a key's tool list holds the two tools, and a call to any account tool is refused.

Pricing and the spend log

The config enters that flat figure, so LiteLLM's spend log can run above Grounder's bill. Each Grounder search response carries what the search actually cost, usage.cost_usd: 0 for one of the 50 free searches, otherwise the price on the Pricing page. It is in the response of POST /v1/search, in the structured content of an MCP search call, and as grounder.cost_usd in the Tavily- and Brave-shaped responses. This config does not read it; a gateway that does can log the real charge. The search log under your account shows the real count. A search is one search however many providers Grounder reaches for it.

Claude Desktop through LiteLLM

Claude Desktop can use LiteLLM as its model gateway, and its web searches then run on Grounder through the first route above. Grounder's own test on 4 November 2026 saw this on LiteLLM 1.108.0.

1. In Claude Desktop, open Help → Troubleshooting → Enable Developer Mode, then Developer → Configure Third-Party Inference…. Do not sign in with an Anthropic account first.
2. In Connection, set Inference provider to Gateway, Credential kind to Static API key, and Gateway auth scheme to Bearer.
3. Set Gateway base URL to your LiteLLM address with no /v1 on the end, such as http://localhost:4000, LiteLLM's default address, and Gateway API key to a LiteLLM key.
4. Click Apply Changes, then Save & Restart. The sign-in screen now offers to start in Claude Desktop on 3P with this configuration.

Two things decide how it behaves:

• The first model becomes the default. Desktop reads the models from LiteLLM's GET /v1/models and starts on the first one. List a less expensive model first in model_list: with Opus as the default, one question cost 60 cents. Desktop's model picker shows only IDs that look like Claude models; to show an alias, list it in Desktop's inferenceModels setting, which its gateway documentation ↗ describes.
• Its searches run on Grounder only for providers in enabled_providers. The model Desktop uses must be on one of them.

To confirm a search ran on Grounder, open LiteLLM's spend logs: each search is an asearch row sent to api.grounder.net, and the same search shows in your Grounder account's search log.

To switch back to standard Claude Desktop, choose the Anthropic sign-in on its sign-in screen.

What each MCP admin tab means for Grounder

LiteLLM's admin UI has a tab for each part of its MCP gateway. For Grounder, one takes a decision and the rest need nothing.

What to know before you rely on it

Four bugs in LiteLLM, all open when this page was checked, concern a model's built-in web search, the first route. /v1/search and the MCP route do not go through that code.

Beyond those:

• The model sees title, URL and snippet. LiteLLM reduces each result to those three fields before the model reads it, so the licence and provider information Grounder returns per result does not reach the model on the swapped-in route. The MCP route returns Grounder's full result to the client.
• No recency setting. LiteLLM's search call has no days or date setting, so a swapped-in search cannot be limited to recent pages. Over MCP, the model can set days on Grounder's search tool itself.
• Result count. On the search-tool routes max_results is set in the config; the model does not choose it.
• Interception is for the providers you list. Models on other providers keep their own built-in search.

Where Grounder fits

Grounder is a web search API and MCP server for AI agents. It returns only licensed sources, puts every provider's features behind one call, and marks each result with its provider and why it is licensed. It returns sources, not an answer. The Tavily-shaped endpoint that LiteLLM uses is described in the Tavily migration guide.

FAQ

Which key does LiteLLM need for Grounder?

A Grounder search key, made under Search keys on your account and shown once. Put it in the environment variable GROUNDER_API_KEY; the config reads it from there. LiteLLM sends it to Grounder as a Bearer header on both the search tool and the MCP server.

Can a LiteLLM key that only searches change my Grounder account?

Not when the Grounder key LiteLLM holds is a search-only key. Choose Search only under Access when you make it: it can search and list providers, and Grounder refuses it the account and every workspace tool, so the limit holds even if a LiteLLM key sees more than it should. The MCP server in this guide adds LiteLLM's own limit on top: allowed_tools lists only search and list_providers, and an access group limits which LiteLLM keys see even those two. Your own keys and sign-ins in Claude Code, Codex, Cursor or claude.ai are full, and keep managing your workspaces.

Why does LiteLLM count free searches too?

LiteLLM adds the per-search cost written in its config to every search, including the 50 free searches a day, so its spend log can show more than Grounder charged. Every Grounder search response carries the charge it took, usage.cost_usd, which is 0 for a free search, so a gateway that reads it can log the real charge. Grounder's own search log on your account also shows what each search was charged.

Why do the recommended results come back as 10 and not 5?

Without a setting, Grounder returns 5 results per search. The config sets max_results to 10 on the search tool, and LiteLLM passes it on to Grounder. Raise or lower it between 1 and 100.

Next step

Make a search key, paste the config above into LiteLLM, and set GROUNDER_API_KEY. The MCP docs and the HTTP API describe what each route sends.