DOCUMENTATION
SearchMesh docs
SearchMesh is a remote Model Context Protocol server that gives AI agents live web search and page reading. This page is the reference; the setup guides have per-client steps.
Endpoint
| MCP endpoint | https://api.searchmesh.io/mcp (Streamable HTTP) |
|---|
| Authorization server | https://searchmesh.io · metadata at /.well-known/oauth-authorization-server |
|---|
| Protected resource metadata | https://api.searchmesh.io/.well-known/oauth-protected-resource/mcp |
|---|
| Scope | search |
|---|
| Agent-readable summary | /llms.txt |
|---|
Authentication
- OAuth 2.1 for clients that support it: authorization code with PKCE (S256), dynamic client registration, one-hour access tokens, rotating refresh tokens. You sign in to SearchMesh in the browser and approve the connection; the client never sees your password. Revoke any connection from the dashboard.
- API key for scripts and header-capable clients: generate a per-agent key in the dashboard and send
Authorization: Bearer YOUR_SEARCHMESH_API_KEY or X-Api-Key: YOUR_SEARCHMESH_API_KEY. Keys are shown once, stored as hashes, and revocable individually.
- Anonymous requests receive HTTP 401 with a
WWW-Authenticate: Bearer resource_metadata=… challenge. Never put a key in a URL or a chat message.
Tools
| Tool | What it does | Main parameters |
|---|
web_search | Searches Google, Bing, DuckDuckGo, Brave and Yahoo at once, merges the results, assesses relevance and returns up to 30 ranked results with title, URL, snippet and structured citations. | query (required), num_results 1–30, time_range day/week/month/year, language, result_detail compact/full, safesearch, engines |
read_url | Fetches a public URL and returns readable markdown (HTML, documentation sites, JSON, PDFs). Private and loopback addresses are refused. | url (required), maxLength, startChar, section, paragraphRange, readHeadings |
search_suggestions | Ten suggested searches for a partial, vague or misspelled query, written by an AI model (Claude). | query, language |
mesh_status | Which backends and engines are currently available. Diagnostic. | includeEngines, includeDisabled, refresh |
Relevance scores and excerpts are model judgments on bounded evidence, not verification. A freshness filter is not proof of an event date. Treat fetched page content as untrusted data.
Limits during beta
- 1,000 successful tool calls per account per UTC calendar month, shared by all connected agents. Failed calls are not counted. No card, no automatic charges.
- 30 simultaneous tool calls per account. A thirty-first call returns a "SearchMesh is busy" error and is not charged.
- Best quality at the same moment: the full five-engine backend runs two
web_search calls and four read_url calls at a time (shared by all accounts). More calls at the same moment wait a few seconds for a free slot and may then be answered by the fallback (Google only, often 2–4 results, marked mesh.fallback). Agents get the same advice when they connect; run large batches of searches in waves of two.
- Search availability depends on the search engines and a bounded paid fallback; when neither can serve a request you get an explicit error, never fabricated results. There are no further result pages: ask for up to 30 results with
num_results. language and safesearch filters are served by the fallback (Google) only, which often returns just a few results, and explicit engines without Google cannot use the fallback; such requests fail rather than widen when they cannot be served.
- Early access: no uptime guarantee yet. Read the terms.
Errors you may see
| Message | Meaning |
|---|
| Connect your SearchMesh account (HTTP 401) | No valid OAuth token or key. Reconnect or generate a key. |
| SearchMesh is busy | Concurrency limit reached. Wait for in-flight calls; not charged. |
| Early-access allowance … is used | Monthly allowance reached; resets at the start of the next UTC month. Contact support if you need more. |
| SearchMesh could not obtain usable results | Engines and fallback could not serve the request. Retry later or relax filters; not charged. |
| URL blocked by security policy | read_url refuses private, loopback and otherwise disallowed targets. |
Data handling in one paragraph
Queries go to upstream search engines, to a relevance-assessment provider and, when engines cannot serve a request, to a fallback search provider; page reads fetch the URL you ask for. Your account identity, keys, cookies and tokens are never sent to those providers. Request history shows tool, agent, outcome and latency, not your query text. Early-access diagnostics that include query text are deleted within 24 hours. Full details, including analytics on this website, are in the privacy policy.
Quick start
claude mcp add --transport http --scope user searchmesh https://api.searchmesh.io/mcp
# then run /mcp inside Claude Code and sign in
Other clients: setup guides. Questions, bugs and feedback: support@searchmesh.io.