MCP Tools Reference - Virtuous API Docs

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.

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 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:

# 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: 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.

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 in the MCP Overview for the full security boundary.

Where to go next

Using MCP for Integration Development

The practical day-to-day patterns for using MCP while building partner integrations.

Connect to the Virtuous MCP Server

Setup instructions for Claude, Claude Code, Cursor, VS Code, and other tools.

MCP Overview

What MCP is, why it matters, and the full security model.

Integration Pathway

The partner integration workflow — MCP fits throughout development.

​The two tools

​Tool 1: search_virtuous_api_docs

​When the AI uses it

​What it returns

​Parameters the AI can use

​Strengths

​Limitations

​Tool 2: query_docs_filesystem_virtuous_api_docs

​When the AI uses it

​Supported commands

​Critical behavior: stateless

​Critical behavior: output limit

​Path conventions

​Example commands

​Strengths

​Limitations

​When the AI uses one tool vs. the other

​Examples of the AI using these tools

​Scenario 1: “How does the Volunteer Users upsert work?”

​Scenario 2: “What fields does POST /users require?”

​Scenario 3: “What patterns do the docs recommend for handling 429 responses?”

​Scenario 4: “What’s the structure of the Volunteer Polling and Sync documentation?”

​Steering the AI toward one tool

​Tool usage hygiene

​Bounded reads

​Batched reads

​Targeted search first, broad search second

​URL path conversion in responses

​Inspecting tool usage in your AI tool

​What the AI does not do with these tools

​Where to go next

Using MCP for Integration Development

Connect to the Virtuous MCP Server

MCP Overview

Integration Pathway

The two tools

Tool 1: `search_virtuous_api_docs`

When the AI uses it

What it returns

Parameters the AI can use

Strengths

Limitations

Tool 2: `query_docs_filesystem_virtuous_api_docs`

When the AI uses it

Supported commands

Critical behavior: stateless

Critical behavior: output limit

Path conventions

Example commands

Strengths

Limitations

When the AI uses one tool vs. the other

Examples of the AI using these tools

Scenario 1: “How does the Volunteer Users upsert work?”

Scenario 2: “What fields does POST /users require?”

Scenario 3: “What patterns do the docs recommend for handling 429 responses?”

Scenario 4: “What’s the structure of the Volunteer Polling and Sync documentation?”

Steering the AI toward one tool

Tool usage hygiene

Bounded reads

Batched reads

Targeted search first, broad search second

URL path conversion in responses

Inspecting tool usage in your AI tool

What the AI does not do with these tools

Where to go next