> ## Documentation Index
> Fetch the complete documentation index at: https://docs.virtuous.org/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Tools Reference
> 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](/virtuous/mcp/connect), 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.
## The two tools
| Tool | Best for |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `search_virtuous_api_docs` | 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.
***
## Tool 1: `search_virtuous_api_docs`
A semantic search across the Virtuous documentation. Returns snippets with titles and direct links to the pages where the matches were found.
### When the AI uses it
* Broad questions: "How does authentication work for the Volunteer API?"
* Discovery: "What documentation exists about webhook retries?"
* Comparison: "What are the differences in pagination across the three Virtuous APIs?"
* Initial orientation: "I'm new to Virtuous — where do I start for building a CRM+ integration?"
### What it returns
A list of relevant content snippets, each with:
* A title (the page or section it's from)
* A short preview of the content
* A link to the page
The AI uses these results to construct its answer — citing or following the links to gather more context as needed.
### Parameters the AI can use
* A search query (the text to search for)
* Optional filters (language, version) — if the Virtuous docs ever support multiple languages or versions, these parameters let the AI narrow results
### Strengths
* Finds relevant pages even when keywords don't match exactly
* Returns multiple candidate pages so the AI can pick the most relevant
* Faster than reading through the full docs
### Limitations
* Returns snippets, not full pages — for the complete content, the AI typically follows up with the filesystem tool
* Search relevance depends on query phrasing — too-broad queries return less useful results
* Can't do exact-text or regex matches (use the filesystem tool for that)
***
## Tool 2: `query_docs_filesystem_virtuous_api_docs`
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](/virtuous/mcp/overview#whats-read-and-whats-not) in the MCP Overview.
### When the AI uses it
* Reading full page content: `cat /volunteer/concepts/users.mdx`
* Exact keyword search: `rg "Idempotency-Key" /`
* Structural exploration: `tree / -L 2` or `ls /volunteer/`
* Reading the OpenAPI specs: `cat /openapi/Volunteer-OpenAPI-Spec.json | jq '.paths | keys'`
* Reading specific sections of long pages with context: `rg -C 5 "email-change problem" /volunteer/`
### Supported commands
The filesystem tool supports these read-only utilities:
| Command | Purpose |
| -------------------- | ----------------------------------------------------------- |
| `rg` (ripgrep) | Fast text search with regex support — the most-used command |
| `grep` | Alternative text search |
| `find` | Find files by pattern |
| `tree` | Display directory structure |
| `ls` | List files in a directory |
| `cat` | Read full file content |
| `head` | Read top N lines of a file (or multiple files) |
| `tail` | Read bottom N lines |
| `stat` | File metadata |
| `wc` | Count lines/words/bytes |
| `sort` | Sort lines |
| `uniq` | Deduplicate lines |
| `cut` | Extract columns |
| `sed` | Stream-edit text (read-only operations) |
| `awk` | Text processing |
| `jq` | JSON query (useful for the OpenAPI specs) |
| Basic text utilities | Standard read-only patterns |
**Not supported:** any write operations, network access, process control. The tool is a sandbox.
### Critical behavior: stateless
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.
### Critical behavior: output limit
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.
### Path conventions
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`.
### Example commands
A flavor of what the AI runs under the hood:
```bash theme={null}
# See the top-level structure of the docs
tree / -L 2
# List all the Volunteer best practices pages
ls /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 page
head -80 /volunteer/concepts/users.mdx
# Read multiple pages in one call
head -100 /volunteer/concepts/users.mdx /volunteer/concepts/groups.mdx
# Read the full content of a specific page
cat /volunteer/workflows/create-or-update-a-user.mdx
# List all the endpoints in the Volunteer OpenAPI spec
cat /openapi/Volunteer-OpenAPI-Spec.json | jq '.paths | keys'
# Find the specific schema for the Volunteer Users POST endpoint
cat /openapi/Volunteer-OpenAPI-Spec.json | jq '.paths["/users"].post'
```
These are read-only operations against a sandbox. Nothing runs on your machine.
### Strengths
* Exact keyword and regex matching (search is semantic; filesystem is exact)
* Full page content access for detailed analysis
* Direct access to the OpenAPI specs (queryable with `jq`)
* Useful for cross-page analysis (e.g., "find all pages that mention X")
* Batches multiple file reads in a single call
### Limitations
* 30KB output cap per call (manageable, but the AI works around it)
* Stateless calls (the AI handles, but it's why queries can look elaborate)
* Read-only (cannot modify, can only read)
* Only the docs — no access to anything outside the documentation set
***
## When the AI uses one tool vs. the other
The AI's decision process roughly:
```mermaid theme={null}
graph TD
Start[User question]
Specific{Is the question
about a specific page
the AI already knows about?}
Topical{Is the question
broad or conceptual?}
Exact{Does the answer need
exact text matching
or full page content?}
SearchTool[search_virtuous_api_docs]
FilesystemTool[query_docs_filesystem_virtuous_api_docs]
Both[Both — search first,
then read with filesystem]
Start --> Specific
Specific -->|Yes| FilesystemTool
Specific -->|No| Topical
Topical -->|Yes| SearchTool
Topical -->|No| Exact
Exact -->|Yes| FilesystemTool
Exact -->|No| Both
```
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.
***
## Examples of the AI using these tools
A few scenarios, with the tools the AI typically picks:
### Scenario 1: "How does the Volunteer Users upsert work?"
| Step | Tool | What happens |
| ---- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| 1 | `search_virtuous_api_docs` | Search "Volunteer Users upsert" — returns the concept page and the workflow page as top results |
| 2 | `query_docs_filesystem_virtuous_api_docs` | `head -200 /volunteer/workflows/create-or-update-a-user.mdx` to read the workflow in detail |
| 3 | The AI synthesizes the answer | Explains the email-as-matching-key behavior, the 200/201 distinction, the email-change problem caveat |
### Scenario 2: "What fields does POST /users require?"
| Step | Tool | What happens | |
| ---- | ----------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------- |
| 1 | `query_docs_filesystem_virtuous_api_docs` | Directly read the OpenAPI spec: \`cat /openapi/Volunteer-OpenAPI-Spec.json | jq '.paths\["/users"].post.requestBody'\` |
| 2 | The AI synthesizes the answer | Lists the required fields directly from the spec | |
This is a case where search would be slower — the AI goes straight to the source.
### Scenario 3: "What patterns do the docs recommend for handling 429 responses?"
| Step | Tool | What happens |
| ---- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| 1 | `query_docs_filesystem_virtuous_api_docs` | `rg -C 5 "429" /` finds every page mentioning 429 with surrounding context |
| 2 | `query_docs_filesystem_virtuous_api_docs` | `cat /volunteer/best-practices/error-recovery-patterns.mdx` to read the comprehensive pattern |
| 3 | The AI synthesizes the answer | Explains the documented pattern — respect `Retry-After`, exponential backoff with jitter, circuit breakers for sustained failures |
### Scenario 4: "What's the structure of the Volunteer Polling and Sync documentation?"
| Step | Tool | What happens |
| ---- | ----------------------------------------- | -------------------------------------------------------------- |
| 1 | `query_docs_filesystem_virtuous_api_docs` | `ls /volunteer/polling-and-sync/` lists the pages in the group |
| 2 | The AI synthesizes the answer | Names the five pages and their topics |
A structural question that doesn't need full page reads.
***
## Steering the AI toward one tool
For most workflows, you don't need to steer — the AI picks well. But occasionally you'll want to nudge:
| Goal | Prompt pattern |
| ---------------------------------- | -------------------------------------------------------------------------- |
| **Force a search across all docs** | "Search the Virtuous docs for any mention of..." |
| **Force a specific page read** | "Read the full content of the Virtuous Volunteer Error Handling page" |
| **Force an OpenAPI spec query** | "Look up the request schema for POST /users in the Volunteer OpenAPI spec" |
| **Force an exact-text search** | "Find every instance of the exact phrase 'audit #' in the Virtuous docs" |
| **Force structural exploration** | "Show me the structure of the Virtuous Volunteer documentation" |
The AI translates these to the appropriate tool calls.
***
## Tool usage hygiene
A few practices the AI follows that are worth knowing about — and that you can encourage with your prompts:
### Bounded reads
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.
### Batched reads
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.
### Targeted search first, broad search second
The AI typically starts with narrow searches (specific keywords, specific directories) before falling back to broad ones. This produces tighter results faster.
### URL path conversion in responses
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.
***
## Inspecting tool usage in your AI tool
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.
***
## What the AI does not do with these tools
A few things worth being clear about:
| Action | Status |
| ------------------------------------------- | ----------------------------------------------------------------- |
| Read your code or local files | Cannot — the filesystem is virtualized and contains only the docs |
| Make network calls | Cannot — the tool has no network access |
| Modify documentation | Cannot — read-only |
| Run shell commands on a real system | Cannot — the "shell" is a sandbox |
| Call Virtuous APIs (CRM+, Raise, Volunteer) | Cannot — the MCP server is for docs, not for API calls |
| Access other partners' data | Cannot — only the public docs are available |
See [What's read and what's not](/virtuous/mcp/overview#whats-read-and-whats-not) in the MCP Overview for the full security boundary.
***
## Where to go next
The practical day-to-day patterns for using MCP while building partner integrations.
Setup instructions for Claude, Claude Code, Cursor, VS Code, and other tools.
What MCP is, why it matters, and the full security model.
The partner integration workflow — MCP fits throughout development.