OpenHands MCP web search / 2026
How to Add Web Search to OpenHands with MCP in 2026
OpenHands is most useful when it can validate a coding decision against current public documentation instead of relying only on model knowledge. Its native MCP command supports remote HTTP servers, so Webstractor needs no local server process. This guide focuses on discovery: finding a small ordered set of public pages before OpenHands chooses which source to read.
Quick answer
Add one remote HTTP server, then verify it with /mcp.
OpenHands can register remote HTTP MCP servers from its CLI. Add the Webstractor endpoint, start a new conversation, confirm that webstractor is active with /mcp, and ask the agent to use search_web for a source-finding task.
openhands mcp add webstractor --transport http https://webstractor.com/mcpBefore you begin
What you need
- OpenHands CLI 1.0 or later
- Network access to webstractor.com
- A model in OpenHands that supports tool calling
Step-by-step setup
Connect Webstractor to OpenHands
Register Webstractor as a remote HTTP server
Run the command once in your terminal. OpenHands stores the entry in ~/.openhands/mcp.json and enables it by default. Webstractor does not require an authentication header for the public allowance.
openhands mcp add webstractor --transport http https://webstractor.com/mcpConfirm the server before researching
Use the list command outside a session, then start OpenHands and enter /mcp. The interactive command is a status view: it should show webstractor among the active servers. If OpenHands was already running, restart the conversation so it mounts the new configuration.
openhands mcp list
openhandsRun a bounded search test
Name the server and tool in the first test so tool selection is unambiguous. Ask for URLs and brief evidence rather than an answer from memory.
# Paste into OpenHands
Use the webstractor search_web tool to find the current Astro upgrade guide. Return the 5 best source URLs with one sentence explaining each result.Research workflow
Search first, read second, implement last
Let search_web identify candidate sources, then tell OpenHands to call extract_public_url on the one or two pages that actually answer the question. This keeps the context smaller and makes the final code change easier to audit.
For repository-specific work, use the site filter instead of asking for a broad search. For example, restrict an Astro question to docs.astro.build or a package question to its official documentation hostname.
- Request 3–5 results for focused questions
- Keep result URLs in the plan or final answer
- Read the selected page before editing code
Troubleshooting
When OpenHands does not call the search tool
Check `openhands mcp get webstractor`, ensure the server is enabled, and begin a new conversation after configuration changes. In the prompt, say “use webstractor search_web” once; OpenHands documentation notes that configured tools become available automatically, but the model still decides when a tool is useful.
If the server is present but a request fails, test network access to the HTTPS hostname and inspect the CLI error. Do not add an Authorization header unless your account setup explicitly requires one.
Available data
What you can extract
- Ordered public web results with titles, URLs, and snippets
- Up to 10 results per search request
- Optional language, country, and hostname restrictions
- Direct PDF-source discovery when the agent requests PDF results
AI workflows
Where normalized data helps
- Find current library documentation before changing code
- Locate migration notes and release information
- Discover primary sources for an implementation plan
- Restrict research to a project or vendor domain
Boundaries
Public data only
- Search is for discovery; the agent should extract a selected URL when it needs the full page.
- A newly added server is mounted when a new OpenHands conversation starts.
- Only public sources are available; credentials and private URLs must not be sent.
webstractor.com does not bypass CAPTCHAs, login walls, paywalls, access controls, or regional restrictions. Review the source’s terms and applicable law before collecting or reusing data.
Common questions
OpenHands and Webstractor FAQ
Does OpenHands need a local Webstractor process?
No. OpenHands supports remote HTTP MCP servers, and the hosted Webstractor URL is sufficient.
Why does /mcp show a pending change?
OpenHands mounts MCP configuration at conversation startup. Restart the conversation after adding or editing a server.
Can OpenHands search only one website?
Yes. Ask it to pass the target hostname in the search_web site parameter.
Ready to try it?