The two tools the Virtuous MCP server exposes — search_virtuous_api_docs and query_docs_filesystem_virtuous_api_docs — with usage details, supported commands, and examples
When you connect an AI tool to the Virtuous MCP server, the AI sees two tools it can use. This page documents both — useful when you want to understand what your AI is doing under the hood, or when you want to write prompts that steer it toward one tool or the other.The audience here is partners who want a deeper look at how MCP works for the Virtuous docs. For most day-to-day use, you don’t need to think about the tools individually — the AI picks the right one. But it helps to know what’s available.
Broad or conceptual queries; finding pages by topic; discovering what content exists
query_docs_filesystem_virtuous_api_docs
Exact keyword matching; reading full page content; structural exploration; reading the OpenAPI specs
The AI decides which tool to use based on the question. Conceptual or open-ended questions (“how does upsert work?”) favor search. Specific reference needs (“show me line 47 of the Volunteer schema”) favor the filesystem tool.Many workflows use both: search first to find the right pages, then read those pages with the filesystem tool.
A read-only shell-like interface over a virtualized in-memory filesystem containing only the Virtuous documentation pages and OpenAPI specs. The AI can run shell-like commands against this filesystem to read pages, search exactly, or explore structure.
The filesystem is virtualized and read-only. Despite the shell-like commands, nothing actually runs on a real machine. The filesystem only contains Virtuous documentation content. The tool cannot read your code, your filesystem, or anything outside the documentation. No writes are possible. See What’s read and what’s not in the MCP Overview.
Each call to the filesystem tool is stateless. The working directory always resets to /, and no shell variables, aliases, or history carry over between calls.This means if the AI wants to operate in a subdirectory, it has to either:
Use absolute paths in every command: ls /volunteer/concepts/
Chain commands in a single call: cd /volunteer/concepts && ls
The AI handles this transparently — you don’t need to think about it — but it’s why some of the AI’s filesystem queries look more elaborate than they would in a real shell.
Output is truncated to 30KB per call. For long pages, the AI uses head -N, tail -N, or rg -C N "pattern" to read just the relevant portion rather than cat-ing the whole file.
Pages in the filesystem use the .mdx extension. The AI reads /volunteer/concepts/users.mdx to access the Users concept page.When the AI references pages back to you in its response, it converts filesystem paths to URL paths by removing the .mdx — so it’ll cite /volunteer/concepts/users rather than /volunteer/concepts/users.mdx.
# See the top-level structure of the docstree / -L 2# List all the Volunteer best practices pagesls /volunteer/best-practices/# Find every page that mentions "rate limit"rg -il "rate limit" /# Show 3 lines of context around matches of "Idempotency-Key"rg -C 3 "Idempotency-Key" /volunteer/# Read the top 80 lines of the User concept pagehead -80 /volunteer/concepts/users.mdx# Read multiple pages in one callhead -100 /volunteer/concepts/users.mdx /volunteer/concepts/groups.mdx# Read the full content of a specific pagecat /volunteer/workflows/create-or-update-a-user.mdx# List all the endpoints in the Volunteer OpenAPI speccat /openapi/Volunteer-OpenAPI-Spec.json | jq '.paths | keys'# Find the specific schema for the Volunteer Users POST endpointcat /openapi/Volunteer-OpenAPI-Spec.json | jq '.paths["/users"].post'
These are read-only operations against a sandbox. Nothing runs on your machine.
The AI’s decision process roughly:In practice the AI often uses both in sequence — search to find candidate pages, then filesystem to read the relevant ones in detail. This is the most common pattern.
The AI doesn’t cat huge files when it doesn’t need to. It uses head -N or rg -C N to get just the relevant portion. This stays within the 30KB output limit and produces faster, more focused answers.
When the AI needs multiple files, it batches them into a single head or cat call rather than separate calls. head -100 /file1.mdx /file2.mdx /file3.mdx in one call beats three separate calls.
The AI typically starts with narrow searches (specific keywords, specific directories) before falling back to broad ones. This produces tighter results faster.
When the AI references a docs page back to you, it converts /volunteer/concepts/users.mdx to /volunteer/concepts/users — the URL path you’d use in a browser. You’ll see references in the documented URL form.
Some AI tools surface which MCP tools were called for each response. This can be useful when:
You’re learning how MCP works under the hood
The AI’s answer seems off and you want to verify it actually consulted the docs
You’re debugging why the AI isn’t producing documented patterns
Tool
How to inspect MCP usage
Claude (web)
Click the response footer / expand details to see invoked tools
Claude Code
Tool calls show inline in the terminal output
Cursor
Tool calls appear in the chat as collapsible blocks
VS Code (Copilot)
Tool calls show in the chat output
If the AI claims to have consulted the docs but no search_virtuous_api_docs or query_docs_filesystem_virtuous_api_docs call shows up, the answer is from training data — treat with appropriate skepticism.
