verso-mcp
Click on "Deploy 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., "@verso-mcp search the Lean reference for 'dependent types'"
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 (Model Context Protocol) server that lets an AI agent search and read documentation built with Verso, Lean's documentation authoring tool.
Verso powers most of the Lean ecosystem's reference docs and books — the
Lean Language Reference,
Functional Programming in Lean,
Theorem Proving in Lean 4,
and more. Verso Manual-genre sites publish a machine-readable cross-reference
index (xref.json); this server consumes that index and the rendered HTML.
The format of thexref.json files that this server depends on is
Verso-internal and may change at any time. Such changes could render this
server non-functional. I'll try to keep up with any such changes, but can't
make any promises.
Point it at one or more Verso sites and an agent gets four read-only tools:
list_sites, list_kinds, search, and fetch_page.
Tools
Tool | Description |
| Enumerate the configured Verso sites and their aliases. |
| List a site's entry kinds (tactics, terms, sections, options, …) with counts. |
| Name-ranked search over a site's cross-reference index, with |
| Fetch a page — or a single |
list_kinds, search, and fetch_page take an optional site argument (an
alias from list_sites); omit it to use the default site. All tools are
read-only and accept a response_format of markdown (default) or json.
Entry "kinds" are derived dynamically from each site's xref.json, so
project-specific domains (Lake commands, error explanations, …) are picked up
automatically — nothing about a particular site is hard-coded.
Related MCP server: devdoc
Configuring sites
Set the VERSO_MCP_SITES environment variable to a comma-separated list of
alias=url pairs. A bare URL (no alias=) gets an alias derived from its path.
VERSO_MCP_SITES="lean-reference=https://lean-lang.org/doc/reference/latest/,
fpil=https://lean-lang.org/functional_programming_in_lean/,
tpil=https://lean-lang.org/theorem_proving_in_lean4/"The first site listed is the default. If VERSO_MCP_SITES is unset, the server
defaults to a single site, the Lean Language Reference.
A site URL must be the root directory that contains xref.json (Verso writes it
there for Manual- and Tutorial-genre sites). The configured site roots also
serve as the network allowlist — see Safety.
Requirements
uv. uv fetches the package and its dependencies
automatically on first launch — no manual virtualenv or pip install step.
Use with Claude Code / Claude Desktop
Add an entry to your MCP configuration (.mcp.json, ~/.claude.json, or
claude_desktop_config.json):
{
"mcpServers": {
"verso": {
"type": "stdio",
"command": "uvx",
"args": ["verso-mcp"],
"env": {
"VERSO_MCP_SITES": "lean-reference=https://lean-lang.org/doc/reference/latest/, fpil=https://lean-lang.org/functional_programming_in_lean/"
}
}
}
}Environment variables
All optional:
Variable | Default | Purpose |
| Lean Language Reference | Comma-separated |
|
| Cache directory (each site cached in its own subdirectory). |
|
| Sustained outbound request rate (requests/second). |
|
| Token-bucket burst capacity. |
|
| Max seconds to wait for a token before refusing. |
Safety & etiquette
MCP servers have a lot of
risks.
As far as MCP servers go, this one (verso-mcp) should be relatively
innocuous: it is read-only, runs no shell commands, and only reaches the
documentation sites you configure (or just the Lean Language Reference, if
left unconfigured). The main caveat is that a malicious or compromised
documentation site could try to steer the model via indirect prompt injection.
verso-mcp cannot prevent that, so don't let an agent that uses it take
consequential actions without your review.
The server is built to be a well-behaved client of documentation sites:
Scoped network access — fetches are restricted to the configured site roots; the site list doubles as the allowlist. Enforced on the request URL and the final post-redirect URL, so a same-host URL outside a configured root is still refused. Path traversal (
..,%2e%2e, backslash variants) is rejected.Obeys
robots.txt— each host'srobots.txtis fetched and respected for this server'sUser-Agent; a host can target it specifically with aUser-agent: verso-mcpgroup.Rate limiting — a shared token bucket caps outbound requests across all sites (default 2 req/s, burst 5); a hit falls back to cached content rather than hammering the origin.
Caching & revalidation —
xref.jsonand pages are cached on disk per site (24 h TTL) withETag/If-None-Matchconditional revalidation, so a repeated lookup costs at most a304 Not Modified.Bounded responses — HTTP bodies are streamed with an 8 MB cap; Markdown output is capped at 200 KB; each site's page cache is LRU-evicted at 200 MB.
Identifying
User-Agenton every request.
Evaluation
evaluation.xml is a 10-question evaluation suite in the format used by
Anthropic's mcp-builder skill. The questions target the default site (the
Lean Language Reference); each is read-only, independent, and has a single
stable, verifiable answer.
Limitations
Works with Verso Manual-genre sites (those that publish
xref.json). Blog-genre sites have noxref.json. Tutorial-genre sites also emit one and should work, but are untested.searchis name-based — it matches entry names and titles in the cross-reference index, the same granularity as Verso's own on-site search. It does not do full-text search of page bodies.The
xref.jsonschema is an undocumented Verso internal; it may shift between Verso releases, which could break this MCP server if it doesn't keep up.
Disclaimer
This project was written almost entirely by Claude Opus 4.7 (1M), an AI assistant. It was built for my own personal use and is shared here only in case it is useful to others. It comes with no warranty whatsoever. Use it at your own risk.
Available Tools
4 toolsfetch_pageARead-onlyIdempotent
Fetch a page from a Verso documentation site and return it as Markdown.
Converts the site's HTML to Markdown. With an #anchor, only that single
entry/section is returned (not the whole chapter). A relative path is
resolved against site; an absolute URL is accepted only if it falls under
a configured site root. Plain http://, off-site URLs, and path-traversal
segments are rejected. Read-only.
Args:
url_or_path: absolute URL on a configured site, or a site-relative path.
May include an "#anchor" (e.g. ".../Tactic-Reference/#induction").
site: site to resolve a relative path against (alias from list_sites);
omit for the default. Ignored when url_or_path is absolute.
response_format: "markdown" (default) for the page text, or "json" for
text plus metadata.
Returns: markdown: a "" header line, then the page/section as Markdown (capped at ~200 KB with a truncation marker). json: {"site","url","anchor","content","truncated"} On failure: an error string, or {"error": "..."} when response_format="json".
Examples:
- Read one entry -> fetch_page(url_or_path=".../Tactic-Reference/#induction")
- Read a chapter -> fetch_page(url_or_path="/Tactic-Proofs/Tactic-Reference/")
- Resolve a hit -> pass the url field of a search result here.
Inputs: url_or_path (required), site, response_format. Returns: result
list_kindsARead-onlyIdempotent
List the kinds of entries indexed for a Verso site, with counts.
Kinds are derived from the site's cross-reference index — they vary per site
(a language reference has tactics and options; a textbook has sections and
terms). Use the returned kind values to filter search. Read-only.
Args:
site: which configured site (alias from list_sites); omit for the default.
response_format: "markdown" (default) or "json".
Returns:
markdown: a table of kind, count, and human-readable description.
json: {"site": str, "root": str, "total_entries": int,
"kinds": [{"kind","count","description"}, ...]}
Inputs: site, response_format. Returns: result
list_sitesARead-onlyIdempotent
List the Verso documentation sites this server is configured to serve.
Each site has an alias — pass it as the site argument to search,
list_kinds, or fetch_page to target that site. Sites are configured via
the VERSO_MCP_SITES environment variable. Read-only.
Args: response_format: "markdown" (default) or "json".
Returns: markdown: one line per site (alias, default marker, root URL). json: {"default": str, "sites": [{"alias","root","indexed"}, ...]}
Inputs: response_format. Returns: result
searchARead-onlyIdempotent
Search a Verso documentation site's cross-reference index by name.
Matches entry names and display names (not free text inside pages — use
fetch_page to read a page). Results are ranked by match quality and
paginated. Read-only.
Args:
query: free-text query matched against canonical and user-facing names.
site: which configured site (alias from list_sites); omit for the default.
kind: optional kind filter — one of the values from list_kinds.
limit: maximum results per page, 1-100 (default 20).
offset: number of results to skip, for pagination (default 0).
response_format: "markdown" (default) or "json".
Returns: markdown: a header ("N matches … showing X-Y") then one bullet per hit ("- [kind] display — url"), plus a hint to re-call with a higher offset. json: {"site","query","kind","total","count","offset","has_more", "next_offset","results":[{"kind","name","display","url",...}]}
Examples: - "Find the simp tactic" -> search(query="simp", kind="tactic") - "Search the FPiL book for monads" -> search(query="monad", site="fpil") - "Next page of results" -> search(query=..., offset=20)
Inputs: query (required), kind, site, limit, +2 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a distinct purpose: listing sites, listing kinds, searching, and fetching pages. No overlap or ambiguity; they form a clear progression from discovery to retrieval.
All tool names follow a consistent verb-based pattern with underscores: list_sites, list_kinds, search, fetch_page. The naming is predictable and readable.
Four tools is well-scoped for a documentation querying server. Each tool is necessary and none are redundant.
The tool surface covers the full read-only workflow: discover sites, explore index structure, search entries, and fetch page content. No obvious gaps for the stated purpose.
Maintenance
Related MCP Connectors
MCP server for agentverse documentation, generated by doc2mcp.
An MCP server that gives your AI access to the source code and docs of all public github repos
Team docs served to AI agents over MCP - search, Markdown reads, version pinning, read audit.
MCP server for querying Forkast documentation
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceGeneric MCP server that exposes Markdown documentation to LLMs, enabling them to search and answer questions about any software documentation.MIT
- AlicenseNot gradedqualityDmaintenanceA documentation MCP server that crawls websites and Git repositories, stores them as Markdown, and provides tools to search and retrieve documentation for local LLMs and AI agents.Apache 2.0
- FlicenseAqualityDmaintenanceAn MCP server that searches official documentation for popular libraries, scrapes pages, and returns clean, LLM-ready text.1-
- FlicenseNot gradedqualityDmaintenanceMCP server that exposes one or more documentation folders (Markdown, MDX, TXT) to AI agents, enabling listing, reading, and searching of documentation files.-