> ## Documentation Index > Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt > Use this file to discover all available pages before exploring further. # Brave Search > Web search and LLM-ready grounding context for AI agents through the Brave Search API Brave Search The Brave Search connector exposes the **Brave Search API** as a remote MCP server for AI agents. It bundles two complementary tools — `brave_search` for raw web results and `brave_llm_context` for pre-structured grounding snippets — and returns them in the standard MCP `content` response format. Retrieve recent results from the open web with titles, URLs and snippets Get token-budgeted, pre-formatted context ready to inject into an agent prompt Apply site whitelist / re-ranking rules per call or workspace-wide Exposes a JSON-RPC MCP endpoint that Agent Creator agents can call directly ## Prerequisites * A **Brave Search API account** with an active subscription token ([api-dashboard.search.brave.com](https://api-dashboard.search.brave.com/)) * A plan that exposes both `/res/v1/web/search` **and** `/res/v1/llm/context` (the **Data for AI** plan is required for the LLM Context endpoint) * Your Brave subscription token This connector targets agent web-search scenarios and exposes two MCP tools: `brave_search` and `brave_llm_context`. ## Instance Configuration The **Brave Search** connector is available in your Prisme.ai instance. Before using it from an agent: 1. Open the connector configuration 2. Set the Brave API key in workspace secrets 3. **Add your Brave Goggle in the `Default Goggles` field** (see the "Brave Goggles" section below) — this is required if you want every Brave Search call to be scoped to your whitelist 4. Adjust the other default search options if needed (count, market, token budget…) ## Connector Configuration Set these values in the connector configuration. They define the provider and the default search options used when the agent omits them. | Field | Default | Description | | ---------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Provider** | `brave` | Search provider identifier | | **Default Count** | `5` | Number of web search results when `num_results` is omitted (`brave_search`) | | **Default Market** | `US` | Country code when `market` is omitted (`brave_search`) | | **Default LLM Context Count** | `20` | Number of grounding entries when `count` is omitted (`brave_llm_context`) | | **Default LLM Context Market** | `us` | Country code when `country` is omitted (`brave_llm_context`) | | **Default Max Tokens** | `8192` | Token budget for the LLM context response when `max_tokens` is omitted | | **Default Context Threshold Mode** | `balanced` | Relevance filter for `brave_llm_context` (`strict`, `balanced`, `lenient`, `disabled`) | | **Default Goggles** | *(empty)* | **Primary place to configure a Brave Goggle.** Paste a raw Goggle definition or a hosted URL — applied to every call from this workspace. Leave empty only if you intentionally want unfiltered Brave Search. | The **Default Goggles** field is where you configure the Goggle that applies to every Brave Search call from this workspace. Most deployments will set this once at install time and leave the `goggles` tool argument unused. ## Workspace Secrets Set this value in the workspace secrets panel. It is referenced by the connector configuration and sent as the `x-subscription-token` header on every call to the Brave API. | Secret | Description | | --------------- | ----------------------------------- | | `BRAVE_API_KEY` | Brave Search API subscription token | Keep the Brave API key in workspace secrets. Do not paste the token into the visible connector configuration fields. ## Brave Goggles A **Brave Goggle** is a small text file that re-ranks or filters Brave Search results: whitelist a set of domains, boost some sites, discard the rest. The connector forwards any goggle you provide on every call to `brave_search` and `brave_llm_context`. Reference syntax: [github.com/brave/goggles-quickstart](https://github.com/brave/goggles-quickstart). ### Where to configure **Goggles are configured in the workspace connector configuration**, in the `Default Goggles` field. This is the standard way to apply a Goggle to every Brave Search call from agents in this workspace. Once set, agents don't need to be aware of the goggle — it is applied transparently. A per-call `goggles` MCP argument also exists, but it is an **advanced override** for special cases (A/B testing, dynamic goggles, multi-tenant flows). Day-to-day deployments only need the workspace config. ### Format accepted by `Default Goggles` * **Hosted URL** — point to a publicly reachable goggle file (e.g. a GitHub raw URL). * **Inline raw definition** — paste the goggle content as a multi-line string. ### Syntax rules Every line that targets a site must include an action — `$discard`, `$boost,site=...`, or `$downrank,site=...`. A bare `$site=domain.com` line is **not** valid Goggles syntax and Brave will reject the call. A typical whitelist pattern is `$discard` (drop everything not boosted) followed by one `$boost,site=...` per allowed domain: ```text theme={null} ! name: French finance whitelist ! description: Restrict and boost results to French finance sources ! public: false ! author: Prisme.ai $discard $boost,site=lesechos.fr $boost,site=latribune.fr $boost,site=banque-france.fr ``` ### Precedence By default every Brave Search call uses the workspace `Default Goggles`. The `goggles` MCP tool argument is an **override**: when provided, it fully replaces the workspace default for that call (no merge). Leave both empty only to run a plain, unfiltered Brave Search. To keep large inline goggle definitions safe from URL length limits, the connector calls Brave with `POST` + JSON body (no GET query string). This is transparent to agents — the MCP request/response format does not change. ## Plug into an Agent Creator capability Agents consume MCP servers directly through **Agent Creator** capabilities. This is the preferred way to expose Brave Search to an agent. From the Prisme.ai console, open the workspace that will host the connector and install **Brave Search** from the Imports panel. Set `BRAVE_API_KEY` in workspace secrets, then open the connector configuration and fill in the defaults you need (most importantly **Default Goggles** — see the "Brave Goggles" section above). Still on the connector configuration page, copy the value of **MCP Endpoint**. Switch to **Agent Creator** and open the agent you want to extend. Add a new capability to the agent: * **If a dedicated Brave Search capability exists** — select it. The server URL is already wired; the connector resolves the Brave API key server-side from the workspace configuration. * **Otherwise** — select the generic **`custom_mcp`** capability and paste the **MCP Endpoint** into the *Server URL* field. The endpoint is authenticated with the caller's Prisme.ai principal (user JWT, workspace JWT, or organization API key), so no extra header is required. The agent now has access to `brave_search` and `brave_llm_context`. Wiring the capability is not enough — the agent also needs to know the MCP exists and when to reach for it. Add a short paragraph to the agent's system prompt. Copy-pasteable starter: ```text theme={null} You have access to the Brave Search MCP server. Use it whenever the user asks for information that requires fresh, public web sources — news, regulatory updates, market data, factual lookups, competitor research. Call `brave_search` when you need raw web results (titles, URLs, snippets) and `brave_llm_context` when you only need pre-formatted grounding snippets to cite in your answer. Prefer recent results (`freshness: Day` / `pd` for breaking news) and a market matching the user's language. Always cite the source URLs returned by the tool. ``` Refine the trigger keywords (regulatory areas, market codes, language) so the agent reliably picks up the right intent in your context. ## Available Tools | Tool | Description | | ------------------- | ---------------------------------------------------------------------------------------------- | | `brave_search` | Search the web through Brave Search and return raw results (titles, URLs, snippets, infoboxes) | | `brave_llm_context` | Retrieve LLM-optimized grounding context as pre-formatted Markdown snippets with sources | ### Choosing Between the Two Tools | Tool | Brave endpoint | Response shape | When to use | | ------------------- | --------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------- | | `brave_search` | `/res/v1/web/search` | Stringified Brave JSON | The agent needs the full response (multiple result types, ranking signals, infobox) | | `brave_llm_context` | `/res/v1/llm/context` | Markdown text (`## title` / `Source: url` / snippets) | The agent only needs factual grounding ready to concatenate into its prompt | ### `brave_search` Arguments | Argument | Type | Required | Description | | ------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | Yes | Search query | | `num_results` | number | No | Number of results to request, from 1 to 20 | | `market` | string | No | Market code, for example `en-US` or `fr-FR` (the connector maps it to a 2-letter country code) | | `freshness` | string | No | Recency filter: `Day`, `Week`, or `Month` | | `goggles` | string | No | Advanced per-call override of the workspace `Default Goggles`. URL of a hosted Brave Goggle **or** raw inline goggle definition. Most deployments configure goggles once at the workspace level — see the "Brave Goggles" section. | ### `brave_llm_context` Arguments | Argument | Type | Required | Description | | ------------------------ | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | Yes | Search query (1–400 characters, max 50 words) | | `count` | number | No | Number of grounding entries to request, from 1 to 50 (default 20) | | `country` | string | No | 2-letter country code, for example `us` or `fr` | | `search_lang` | string | No | Search language, for example `en` or `fr` | | `freshness` | string | No | Recency filter: `pd` (past day), `pw` (past week), `pm` (past month), `py` (past year) | | `max_tokens` | number | No | Maximum total tokens in the response, from 1024 to 32768 (default 8192) | | `context_threshold_mode` | string | No | Relevance threshold: `strict`, `balanced`, `lenient`, or `disabled` | | `goggles` | string | No | Advanced per-call override of the workspace `Default Goggles`. URL of a hosted Brave Goggle **or** raw inline goggle definition. Most deployments configure goggles once at the workspace level — see the "Brave Goggles" section. | ## MCP Examples ### Web Search with Defaults ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "brave_search", "arguments": { "query": "latest Brave Search API documentation" } } } ``` ### Web Search on a French Market with Fresh Results ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "brave_search", "arguments": { "query": "actualites intelligence artificielle entreprise", "num_results": 5, "market": "fr-FR", "freshness": "Day" } } } ``` ### LLM Grounding Context with a Token Budget ```json theme={null} { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "brave_llm_context", "arguments": { "query": "European AI Act enforcement timeline", "count": 15, "country": "fr", "search_lang": "en", "freshness": "pm", "max_tokens": 4096, "context_threshold_mode": "strict" } } } ``` ### Web Search with a Per-Call Goggle Override (Advanced) Most workspaces will configure the Goggle once in the connector configuration (`Default Goggles`) and never pass `goggles` in the MCP call. The example below shows the advanced per-call override path. ```json theme={null} { "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "brave_search", "arguments": { "query": "réglementation DORA banque", "num_results": 10, "market": "fr-FR", "goggles": "! name: FR finance whitelist\n! public: false\n$discard\n\n$boost,site=acpr.banque-france.fr\n$boost,site=banque-france.fr\n$boost,site=lesechos.fr" } } } ``` ## Response Format ### `brave_search` Successful calls return the Brave JSON payload serialized as text: ```json theme={null} { "content": [ { "type": "text", "text": "{ \"type\": \"search\", \"web\": { \"results\": [ ... ] }, ... }" } ], "isError": false } ``` ### `brave_llm_context` Successful calls return Markdown sections, one per grounding entry, ready to inject into an agent prompt: ```json theme={null} { "content": [ { "type": "text", "text": "## Result title\nSource: https://example.com/article\nFirst snippet…\nSecond snippet…\n\n## Other result\nSource: https://example.org/post\n…\n" } ], "isError": false } ``` If the Brave API rejects the call or the query is missing, the connector returns `isError: true` with a text error message. ## Troubleshooting **`Error: query parameter is required`** — The MCP call did not include `params.arguments.query`. **`Brave Search API error:
`** — Returned by either tool when Brave rejects the call. Common causes: invalid or expired `BRAVE_API_KEY`, quota exceeded, plan that does not include the requested endpoint, or an unsupported parameter value. **`No grounding context found for this query.`** — `brave_llm_context` did not find any entry above the relevance threshold. Try a more permissive `context_threshold_mode` (for example `lenient`) or broaden the query. **`Brave Search API error: `** — The Goggle definition was rejected by Brave. Common causes: a `$site=...` line with no action (use `$boost,site=...` or `$discard` + `$boost,site=...`), an unreachable hosted URL, or unescaped characters. See [github.com/brave/goggles-quickstart](https://github.com/brave/goggles-quickstart) for the syntax reference. **`Authentication required`** (HTTP 401, JSON-RPC error `-32000`) — The MCP endpoint requires an authenticated principal. Call it with a user JWT, a workspace JWT, or an organization API key. ## Related Compare App and MCP connector usage modes Plug MCP servers into Knowledges agents