The web-research-mcp server acts as a persistent, version-aware cache for web research, enabling host AI models to store, retrieve, and validate documentation without re-researching the same sources every session.
Browse the cache hierarchy: View a structured tree of cached technologies → versions → topics, including freshness flags, without fetching content.
Check freshness/existence: Quickly verify if a specific tech/topic reference is cached and current — returns status, staleness info, and slug without fetching full content.
Retrieve cached docs: Fetch complete markdown content for a cached reference by slug, or retrieve just a specific section/heading.
Full-text search: Search across topic names, summaries, content, and tags — optionally scoped to a specific technology.
Store new research: Save researched documentation (tech, topic, version, summary, content, tags, sources) into the cache; atomically supersedes older versions and warns about possible duplicate topics.
Invalidate references: Mark a cached entry as stale by slug, prompting re-research on next use.
Self-update guidance: Detect newer server versions on GitHub and return the update command, delegating execution to a background agent to avoid blocking workflow.
Enforce consultation (optional): Install a pre-edit hook requiring the host model to consult cached references before editing code for tracked technologies.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@web-research-mcp Check if we have React server components documentation cached."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that keeps a persistent, version-aware cache of web research so the host model (Claude, Codex, …) writes modern, non-deprecated code without re-researching the same docs every session.
The server never browses the web itself — the host does the searching when the user asks. This server only stores what was found, answers "do we already have this? is it current?" cheaply, and serves the cached reference back.
One line — no clone needed:
curl -LsSf https://raw.githubusercontent.com/jcsoftdev/web-research-mcp/main/install.sh | bashOr from a checkout:
./install.shInteractive: installs uv if missing, installs the web-research-mcp binary, then
asks which hosts to register into (Claude Code, Codex, Gemini, Claude Desktop,
Cursor) and wires each one up. The DB autocreates on first use.
# Claude Code
claude mcp add web-research -s user -- web-research-mcp
# Codex
codex mcp add web-research -- web-research-mcpOther hosts (JSON config):
{
"mcpServers": {
"web-research": { "command": "web-research-mcp", "args": [] }
}
}Related MCP server: wellread
Tool | Cost | Behavior |
| minimal | Hierarchy tech → version → topics (names + |
| low |
|
| low | Loops |
| low-high | check + fetch in one round-trip; |
| low | Audits a full stack ( |
| med-high | Full markdown doc; optional section returns one heading block. |
| med | FTS5 over topic + summary + content + tags. |
| write | Stores a doc; atomically supersedes older versions (PEP 440 compare); rejects redundant saves over a fresh entry unless |
| write | Forces a reference stale. |
| minimal | Hit-rate, top missed techs (your research queue), estimated tokens saved by cache hits. |
Freshness is a structured field (status_tag, stale) placed first in every
response, and a stale entry carries an explicit advice field — the model can't
overlook deprecation buried in prose.
A miss is {"exists": false} plus a nearby list of what is cached for that
tech, when anything is:
{"exists": false,
"nearby": [{"tech": "openrouter", "topic": "free-models",
"slug": "openrouter/free-models", "similarity": 0.43}]}A bare exists: false cannot distinguish never researched from you
misspelled the slug, and a caller who can't tell the two apart stops calling —
the cache goes unused rather than getting corrected. nearby prefers other
topics under the same tech; only when the tech itself is unknown does it look
for a near-miss on the tech name (open-router → openrouter). It is omitted
entirely when nothing is close, so an empty cache still answers a flat
{"exists": false}.
Known alias spellings of the same recurring topic (whats-new,
latest-changes, new-features, ...) are folded into one canonical topic
(latest-version) before a slug is built or looked up — in save_research,
check_reference, resolve_reference, check_reference_batch, and
get_reference (which also accepts an alias slug directly). This is
structural, not advisory: two hosts spelling the same topic differently
land on the same cache entry instead of forking it. The alias map is a static
seed (core/canonical.py); DB-backed, runtime-taught aliases are a deliberate
v2.
save_research guards against forking the same concept under different topic
names (server-components vs servercomponents). Before inserting it looks for
similar existing topics for that tech and, if any, returns them in a
possible_duplicates field so the host reuses an existing slug instead of
creating a duplicate. It is advisory, non-blocking — unlike canonicalization,
above, it doesn't rewrite the topic, it only flags a candidate for the host to
reuse. Matching is lexical today (near-spellings, spacing, truncated
abbreviations); synonyms and non-truncation abbreviations (rsc vs
server-components) need embeddings, which swap in at the same call site via
EmbeddingProvider when EMBEDDINGS_ENABLED=1.
The MCP instructions only ask the model to call check_reference before
writing code or searching the web — nothing enforces it, and an ephemeral
subagent picked via tool-search never even sees the server's instructions
(only each tool's own description). The installer can wire host hooks that
turn the ask into a guarantee, at two points:
web-research-mcp hook --host {claude|codex|gemini|cursor}Pre-edit gate — if you are about to edit code for a cached tech and the
current session never consulted its reference, the edit is denied until
you do. Detects tracked techs via strong signals only (real JS/TS imports or
package.json dependency keys — never prose) and checks the session
transcript for a prior check_reference / get_reference call.
Post-search reminder (Claude Code only) — after every WebSearch /
WebFetch, a PostToolUse note asks for the finding to be cached. It fills in
what it can already tell: a WebFetch reminder names the tech derived from the
host (pkg.go.dev → tech="go", docs.python.org → tech="python"), and a
WebSearch reminder quotes the query. A guess costs one correction; no
suggestion at all costs the save.
Save-debt gate (Claude Code only) — the harder version, because a reminder
still loses to whatever the model is currently chasing: measured in a real
session, six consecutive searches produced six reminders and zero
save_research calls. A deny does not lose. Set WEB_RESEARCH_SEARCH_DEBT=N and the Nth search with
no intervening save_research is refused until the earlier ones are cached.
Off by default (0). 3 tolerates a one-off lookup and stops a chain. It
counts searches without judging whether each deserved caching — that cannot be
told from a query string — so the cost of a false deny is one save_research
the model would have skipped, against a cache that otherwise never fills.
WEB_RESEARCH_SEARCH_DEBT=3 web-research-mcp hook --host claudeSearch-redundancy gate (Claude Code only) — symmetric, for the other
direction: WebSearch / WebFetch is denied when the query/URL names a
tech that already has a fresh cached entry and it wasn't consulted this
session (call resolve_reference instead of re-researching). A PostToolUse
hook on the same tools injects a (best-effort) reminder to call save_research right after
a search completes — this fires for the main thread, Task-spawned
subagents, and Workflow agent() calls alike (all three verified empirically
to receive Claude Code hooks).
Detection is conservative by design in both gates: a false deny blocks legitimate work.
Install is opt-in (default no) because a deny is disruptive. Support:
host | event | status |
Claude Code |
| verified |
Codex |
| experimental |
Gemini CLI |
| experimental (schema unverified) |
Cursor |
| experimental |
The hook fails open: any parse error, unknown host, or unreadable DB allows the action — a bug in the gate must never wedge your editor.
var | default | purpose |
|
| DB location (global — reused across projects) |
|
| TTL for non-version-locked entries |
|
| vector search (post-MVP) |
|
| advertise updates so the host auto-delegates them; set |
The server never installs anything itself. It exposes a check_for_update tool
and, via its MCP instructions, asks the host to delegate a background agent to
run the update when a newer version exists on GitHub — so the update never blocks
you and takes effect on the next launch. The host does the work; the server only
detects and advises.
With WEB_RESEARCH_AUTO_UPDATE=0 the tool still exists but the instructions no
longer ask the host to auto-delegate — call check_for_update yourself when you
want it.
uv sync
uv run pytestWhether a newer server version exists on GitHub.
If update_available, the host should delegate a background agent to run
the returned command so the server stays current.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains the tool returns whether an update is available and suggests an action. It does not mention auth or rate limits, but for a simple read-like operation, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, and each sentence adds value. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters or output schema, the description is adequately complete. It explains the tool's purpose and the action to take based on the result, though the exact return format could be more explicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. The description adds meaning by explaining the return values (update_available and command), which helps the agent understand the tool's output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks for a newer server version on GitHub, with specific details about update_available and command. It is distinct from sibling tools that deal with references and research.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a conditional usage guideline: if update_available, delegate a background agent to run the returned command. It lacks explicit when-not-to-use or alternatives, but sibling tools are in different domains.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cheap existence/freshness check. No content. Omit version for the latest.
| Name | Required | Description | Default |
|---|---|---|---|
| tech | Yes | ||
| topic | Yes | ||
| version | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description discloses the tool is cheap and returns no content, which suggests non-destructive behavior. It adds version behavior hint but lacks detail on return format or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, efficient and to the point. Every word adds value, though a more structured approach could improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing explanations for return value (e.g., boolean or timestamp), parameter meanings, and broader usage context. For 3 parameters with no output schema and no annotations, more detail is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%; description only adds meaning for the version parameter ('omit version for the latest'). Tech and topic parameters are not explained beyond their names, which are vague.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool performs an existence/freshness check and notes it returns no content. It distinguishes from siblings that likely provide content or search, but does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use when a lightweight check is needed ('cheap') and when content is not required ('no content'). However, it does not specify when to use siblings like get_reference or search_reference, nor does it give explicit when-to-use or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full cached doc for a slug. Optional section returns one heading block.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| section | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must cover behavioral context. It mentions 'cached' but lacks details on staleness, performance, error handling, or whether network calls are involved. The optional section behavior is described, but otherwise the tool's side effects and reliability are opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no extraneous information. The primary purpose is front-loaded, and the optional parameter is explained in the second sentence. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two parameters, no output schema, and no annotations, the description is insufficient. It fails to explain return values, error conditions, caching semantics, or what 'heading block' means, leaving an agent without enough context to use the tool reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description explains both parameters: 'slug' identifies the doc, and 'section' optionally returns one heading block. This adds meaningful context beyond the raw schema, though it does not specify formats or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('get') and resource ('full cached doc for a slug'), and distinguishes itself from siblings by specifying a unique function. The optional section parameter is also explained, providing a specific purpose for a common variant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing a cached doc or a specific section, but does not explicitly state when to prefer this tool over siblings like search_reference or check_reference. No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Force a reference stale so the next check advises re-research.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. The term 'stale' is undefined, and the description does not explain what the invalidation entails (e.g., irreversible? affects other references?), leaving the agent uncertain about side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence), but it omits necessary detail for correct usage. While brevity is valued, under-specification reduces its utility.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and a single undocumented parameter, the description is insufficient. It fails to explain prerequisites, return values, or the effect on the system.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'slug' is not described in the schema or the tool description. Given 0% schema coverage, the description should clarify what a 'slug' is to aid correct invocation, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('force a reference stale') and the resource ('reference'), with a clear outcome ('next check advises re-research'). It distinguishes from sibling tools like 'check_for_update' and 'get_reference' by indicating a direct invalidation action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as when a reference is known to be outdated or requires re-research. There is no mention of associated prerequisites or when invalidation is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cached hierarchy tech -> version -> topics (names + flags, no content).
| Name | Required | Description | Default |
|---|---|---|---|
| tech | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions 'cached' (important for potential staleness) and 'no content' (lightweight nature). However, with no annotations, it fails to disclose other behaviors like cache refresh triggers, authentication requirements, or any destructive side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using a single sentence to convey the core output. It front-loads key information (cached, hierarchy, content exclusion). However, the conciseness sacrifices completeness, especially regarding parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single parameter with no schema descriptions, no output schema, and no annotations, the description is incomplete. It lacks details on how the tech parameter affects output, what names/flags represent, and how to interpret the hierarchy structure, leaving significant gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has one optional parameter 'tech' with no descriptions; schema description coverage is 0%. The description does not explain the parameter's role, how it filters the hierarchy, or the behavior when omitted (e.g., returns all? top-level?). This is insufficient for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a cached hierarchy from tech to version to topics, with names and flags but no content. It is specific about the resource and scope, and somewhat distinguishes from siblings like search_reference, but could be more explicit about the caching behavior and what 'topics' entails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as check_for_update or search_reference. The description implies it's for retrieving a cached tree, but lacks context on appropriate scenarios or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store host-researched docs. Supersedes older versions atomically.
Only tech/topic/summary/content are required. Omit version for a general (not version-bound) reference; status_tag defaults to "current".
Response includes possible_duplicates when a similar topic already
exists for this tech — reuse or consolidate instead of forking naming.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| tech | Yes | ||
| topic | Yes | ||
| content | Yes | ||
| sources | No | ||
| summary | Yes | ||
| version | No | ||
| status_tag | No | current | |
| version_locked | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses atomic superseding and duplicate detection, but omits auth needs, error behavior, or side effects beyond version control.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, no fluff, front-loaded with key action. Could be more structured for clarity on parameters, but efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 params, no output schema, and no annotations, the description is incomplete. Lacks explanation of return values beyond possible_duplicates, error conditions, and full param semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet description only explains a few parameters (required ones, version, status_tag). Leaves 'tags', 'sources', 'version_locked' undefined, insufficient for a 9-param tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it stores research docs with atomic superseding. However, it does not explicitly differentiate from sibling tools like search_reference or check_reference, though the purpose is distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance on required fields, optional version, and default status_tag. Mentions possible_duplicates response hinting at reuse. Does not explicitly state when not to use or alternatives, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search over cached references when the exact topic is unknown.
| Name | Required | Description | Default |
|---|---|---|---|
| tech | No | ||
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It indicates a read-only search operation across cached data, which is helpful but lacks details on caching semantics, response format, or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no extraneous information. It is appropriately sized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With two parameters (one optional and undocumented) and no output schema, the description falls short. It does not explain the 'tech' parameter or what the search returns, leaving gaps for effective usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not elaborate on the 'query' or 'tech' parameters. The optional 'tech' parameter is left unexplained, failing to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('full-text search'), the resource ('cached references'), and a specific use case ('when the exact topic is unknown'). It effectively distinguishes from siblings like get_reference, which is likely for known references.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'when the exact topic is unknown' provides implicit guidance on when to use this tool versus related tools like get_reference. However, it does not explicitly name alternatives or contraindications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0check_for_updatecheck_referenceget_referenceinvalidate_referencelist_treesave_researchsearch_referenceEach tool has a clearly distinct purpose: server version checking, reference existence/content/invalidation, hierarchy listing, research saving, and full-text search. There is no overlap or ambiguity.
All tool names follow a consistent verb_noun pattern with underscores: check_for_update, check_reference, get_reference, invalidate_reference, list_tree, save_research, search_reference. No deviations or mixed conventions.
With 7 tools, the count is well-scoped for a web research server. It covers all essential operations without being excessive or insufficient.
The tool set covers create (save_research), read (get_reference), search (search_reference), list (list_tree), and update/invalidate (invalidate_reference). A possible gap is the lack of a true delete operation, but invalidate serves a similar purpose. Overall, the surface is nearly complete for its domain.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Versioned documentation registry and semantic search for AI tools and coding assistants.
Collaborative, cache-first web search for agents — cited answers from a shared live-web pool.
Web research for agents: quality-scored Google search, webpage extraction, and deep research.
Token-efficient search for coding agents over public and private documentation.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/jcsoftdev/web-research-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
