Try free

Last updated 13 October 2026

Use the Brave Search MCP server

The challenge of stale documentation in the terminal

Claude Code works best when it has direct access to your local files and its own training data. However, modern software development moves much faster than any static model. Libraries update their APIs, frameworks release new major versions, and documentation sites change their structure every few weeks. When you ask the agent to implement a feature using a library released very recently, it might hallucinate old patterns or tell you the library does not exist. You need a way to feed it fresh, accurate data from the live web without leaving your terminal environment.

The Brave Search MCP server bridges this gap by allowing the agent to perform real-time searches. Instead of relying on what the model knew when it was built, the agent can use the WebSearch tool to find the latest documentation. This prevents errors caused by deprecated functions and ensures your code remains modern. You can stop copying and pasting text from your browser into the terminal. The agent handles the search, reads the results, and applies the information directly to your project files while you watch it work.

Acquiring your Brave Search API credentials

Before you can connect the service, you must obtain an API key from the Brave Search developer portal. Brave offers a specific API for search results that is designed for AI agents and programmatic access. You will need to create an account on their platform and generate a key. Keep this key secure and do not commit it to your public repositories. The agent will use this key to authenticate every search request it makes on your behalf. If you lose the key, you will need to generate a new one and update your configuration.

Brave offers different tiers for their API usage. You should check their current offerings to see which one fits your development volume. For most individual developers, the basic tier provides enough queries to handle daily coding tasks and research. Once you have the key, you are ready to tell Claude Code how to use it. You will usually provide this key as an environment variable in your configuration so the MCP server can communicate with the Brave servers. This setup ensures that the agent can access the web whenever your prompt requires external knowledge.

Configuring the MCP server in Claude Code

You have two main ways to add the Brave Search MCP server to your environment. The first is using the command line by running "claude mcp" and following the interactive prompts to add a new server. This method is the simplest for most users because it guides you through the naming and setup process. You will need to provide the command to run the MCP server, which is usually a node command if you are using the official Brave Search MCP package from a package registry. The tool will then register the server in your configuration.

The second method involves editing the configuration file directly. You can find your MCP settings in the .mcp.json file. This file allows you to define the name of the server, the command to start it, and any environment variables like your API key. If you want the search capability to be available across all your projects, you should ensure the configuration is global. If you only need it for a specific repository, you can place the configuration in that project root. The agent reads this file every time a session starts to determine which tools are available.

Verifying the connection and available tools

After you have configured the server, you must verify that Claude Code can actually talk to it. Run the "claude doctor" command in your terminal. This tool checks your entire installation, including your environment and MCP connections. It will report if the Brave Search server failed to start or if there are issues with your API key configuration. If everything is correct, the doctor command will show a successful status for your MCP environment. This step is vital to perform before you start a long coding session.

Inside an active session, you can also use the /mcp slash command. This command lists all active MCP servers and the specific tools they provide to the agent. You should see a tool named WebSearch in this list. If the tool appears, the agent is now capable of searching the web. You do not need to tell the agent how to use the tool specifically. It will automatically decide to call WebSearch when you ask a question that it cannot answer using only your local files or its internal memory. The /mcp command confirms the agent knows the tool exists.

Using web search in your daily coding workflow

When you are inside a session, you can trigger a search by asking a direct question about external information. For example, you might ask the agent to find the latest migration guide for a specific database library or the current syntax for a new cloud provider CLI. The agent will then invoke the WebSearch tool, parse the search results, and present you with a plan. It might also use the WebFetch tool to read the full content of a specific documentation page it found in the search results to ensure it has the complete context.

This capability is particularly useful for debugging obscure error messages that have appeared since the last model update. You can paste an error into the terminal and ask the agent to search for recent GitHub issues or Stack Overflow threads related to it. The agent can then summarize the solutions found by other developers and apply the fix to your code. This saves you from switching back and forth between your code editor and your browser, which helps you stay focused on the task at hand. The agent does the research while you review its findings.

Managing context size and session costs

Every time the agent searches the web and reads a page, it adds that text to your current session context. Large documentation pages can quickly fill up the context window. To keep the session responsive and avoid reaching limits, you should use the /compact command periodically. This summarizes the conversation and the information gathered so far, which frees up space for new tasks while keeping the important facts in memory. Managing your context is a key skill when using web-enabled agents.

Web searches and large context windows also affect your overall usage. You can monitor your spend by using the /cost and /usage commands. The /cost command shows you the estimated price of the current session, while /usage provides a broader view of your activity over time. If you find that a session has become too cluttered with search data or is no longer moving in the right direction, you can use /clear to start fresh in the same folder. This resets the context but keeps the MCP tools available for your next prompt.

Handling permissions and tool safety

By default, Claude Code asks for your permission before it runs tools like WebSearch or before it writes changes to your files. This is the default permission mode. If you trust the agent to perform searches without asking every time, you can cycle through different permission modes using Shift+Tab. You can move to the acceptEdits mode or even the bypassPermissions mode if you want a faster experience. However, staying in the default mode or the plan mode allows you to see the search queries before they are sent to the provider.

You can also control specific tool permissions in your settings.json file. Under the permissions key, you can set allow or deny for specific tools. This ensures that the agent only uses the WebSearch tool when you are comfortable with it doing so. If you are working in a sensitive environment, you might want to restrict certain tools or require manual approval for every external network call. These settings give you granular control over how the agent interacts with the internet and your local filesystem.

Organizing searches across multiple projects

If you are working on several different projects at once, managing multiple sessions can become difficult. Each session has its own context and its own set of search results. This is where adhdTerminal becomes useful for your workflow. It allows you to run many Claude Code sessions side by side as tiles on a wall. You can have one tile dedicated to a frontend project searching for modern library documentation and another tile for a backend project searching for updated API specifications. This visual organization helps you keep track of multiple research threads simultaneously.

Each tile in adhdTerminal shows whether the agent is currently working, waiting for your input, or idle. This visual feedback is helpful when you have sent the agent on a long task that involves searching and reading multiple web pages. You can also use the adhdTerminal iPhone app to check the status of your searches while you are away from your computer. The app mirrors your wall of tiles over an encrypted link, letting you see the latest exchanges and even send the next task to an agent that has finished its search and is waiting for instructions.

Questions people ask

How do I stop a search that is taking too long?

Press the Escape key once to interrupt the agent while it is running the WebSearch tool. If you need to go back further in the conversation history because the search results were not helpful, press Escape twice to see a list of earlier messages you can return to.

Can I use other search engines with Claude Code?

Claude Code supports the Model Context Protocol, which means you can connect any search service that has a compatible MCP server. While Brave Search is a popular choice, you can find or build servers for other engines and add them using the "claude mcp" command or by editing the .mcp.json file.

Where is the best place to store my Brave API key?

You should not store the key directly in your project files if you plan to share them on a public repository. Instead, use a local configuration file like .claude/settings.local.json for your overrides or set the key as an environment variable in your shell. This keeps your credentials private while still allowing the MCP server to access them during a session.

Read next

More on claude code basics·All posts