The general shape of using MCP
The biggest mental shift: MCP is most useful as background help, not as a tool you consciously invoke. Once connected, just ask your AI questions naturally — it decides when to consult the docs. A few patterns that work well:
The common thread: tell the AI you want it to consult the docs, especially when the answer depends on Virtuous-specific patterns the AI’s training data wouldn’t know.
Strong prompts vs. weak prompts
Small changes in how you phrase questions make a big difference:
The pattern: mention the doc context explicitly (“Virtuous documentation”, “Virtuous Volunteer API”, “Virtuous best practices”) and ask the actual question rather than a generic one.
This shapes the AI’s search query — the better the framing, the better the docs lookup.
Workflows where MCP shines
A few concrete scenarios where MCP adds real value for partners.1. Designing the architecture of a new integration
You’re starting a new integration. Before writing code, ask the AI to walk through the canonical architecture for your use case:“I’m building a partner integration that syncs Volunteer Users to a Salesforce instance. Walk me through the architecture the Virtuous docs recommend — initial sync, ongoing polling, reconciliation. Cite the relevant docs pages so I can dive deeper.”The AI consults the Volunteer API docs (especially Sync Users to External System and the Polling and Sync group) and produces a grounded architecture overview with links you can follow. This is dramatically better than the AI generating a generic “polling architecture” template that misses the participation gap, the email-change problem, and other Virtuous-specifics.
2. Implementing specific endpoints
You know what you’re building; you need the exact field shape for a request:“Generate the JavaScript function to upsert a user via the Volunteer Users endpoint. Use the field shape and required fields from the Virtuous docs.”The AI reads the relevant page, gets the exact field shape (
first_name, last_name, email snake_case, with the right required/optional split), and produces code that matches.
3. Handling edge cases
You’re working on an edge case and want to know what the docs recommend:“How should I handle the case where a Volunteer User’s email changes between syncs? Check the Virtuous docs for the recommended pattern.”The AI finds the email-change problem section and explains the documented mitigation (track external IDs separately, alert on email changes, don’t auto-sync with the new email). This is a case where generic AI would say “just sync the new email” — which is wrong and creates duplicate VOMO users. The documented answer is significantly different from the obvious answer.
4. Implementing best-practice patterns
You’re writing the retry logic for your integration:“Implement an exponential-backoff retry wrapper for calls to the Volunteer API. Use the patterns from the Virtuous Error Recovery Patterns documentation.”The AI reads Error Recovery Patterns and produces code that:
- Classifies errors correctly (transient vs. permanent)
- Uses exponential backoff with jitter
- Respects
Retry-Afterheaders for 429s - Doesn’t retry 422s (validation errors)
- Has bounded retry counts
5. Writing customer-facing documentation
You’re writing your integration’s user-facing docs:“I’m writing customer-facing documentation for our Volunteer integration. Help me explain why we can’t sign up volunteers for shifts via the API. Pull the explanation from the Virtuous Understand Write Limitations page.”The AI reads Understand Write Limitations and produces a customer-friendly explanation of the constraint — accurate, complete, and grounded.
6. Debugging production issues
You’re seeing unexpected behavior in production:
“My integration is sometimes getting different counts in meta.total between consecutive pages of the same query. Is this expected? Check the Virtuous docs.”
The AI consults the Volunteer Pagination doc, finds the note that meta.total reflects the count at request time (not constant), and explains why counts can shift during pagination of a live dataset.
This is the kind of “is this a bug or expected?” question MCP answers efficiently — instead of you searching docs yourself, the AI does it.
7. Reviewing pull requests for integration correctness
You’re reviewing a teammate’s PR:“Review this PR. Compare the polling implementation against the Virtuous Detecting User Changes documentation. Flag anything that deviates from the documented patterns.”The AI reads the documented patterns and surfaces gaps — for example, “this code advances the checkpoint to
new Date() rather than to the latest updated_at actually seen, which can cause records to be skipped during long polls (see the Virtuous docs).”
How MCP combines with other AI tools
Most partners use multiple AI capabilities together. MCP for docs fits with:
Practical recommendation: keep MCP servers connected for the projects where they’re relevant; disconnect or disable them for projects where they’re not. This keeps the AI’s context focused.
Prompting patterns that work especially well
A few specific patterns worth knowing:“Cite the docs”
“…and cite the specific docs pages you’re referencing.”Asks the AI to surface the URLs it consulted. Useful when you want to dive deeper after the AI’s initial answer.
”Check the docs first, then…”
“Check the Virtuous docs for the recommended polling cadence, then design a worker for our specific scale.”Tells the AI to look up grounding before designing. Better answers because the design starts from documented constraints.
”Compare to the documented pattern”
“Compare my implementation against the Virtuous polling pattern. What am I missing?”Forces the AI to consult the docs and surface gaps. Especially useful for code review and refactoring.
”What does the documentation specifically say about…”
“What does the Virtuous documentation specifically say about handling deletions in the Volunteer API?”Tight, focused question. Likely produces a tightly focused answer with specific doc references.
”Search the docs for…”
“Search the Virtuous docs for any mention of ‘rate limits’ across all three APIs. Summarize the differences.”Cross-cutting search. Useful when you want a synthesized view across multiple docs pages.
Common pitfalls (and how to avoid them)
A few things partners run into when starting to use MCP:Assuming the AI is using MCP when it isn’t
Problem: You ask a question; the AI gives an answer that sounds plausible but turns out to be from its training data, not from the docs. Fix: Be explicit. Say “check the Virtuous docs” or “according to the documentation” in your prompt. Some AI tools also surface “which MCP tools were used” — check that the search or filesystem tool actually fired.Asking generic questions and getting generic answers
Problem: “How do I authenticate with Virtuous?” — gets a generic OAuth tutorial, not the Virtuous-specific one. Fix: Be specific about which Virtuous product and which workflow: “How do I authenticate against the Volunteer API for a partner integration that serves multiple customers?”Confusing MCP with the Virtuous APIs themselves
Problem: Asking the AI to “use the MCP server to query my customer’s Volunteer data.” Fix: The MCP server is for documentation, not for calling Virtuous APIs. The AI can help you write code that calls the APIs, but the MCP server itself won’t fetch customer data.Treating the AI as authoritative when the docs disagree
Problem: The AI confidently states something that contradicts the docs. Fix: When the answer matters, follow the docs links the AI cites and verify. The AI’s role is to help you find and apply documented patterns, not to be the final word on what the docs say.Letting MCP do all the thinking
Problem: You ask the AI to design the entire architecture and accept the answer without considering your specific constraints. Fix: Use MCP-assisted answers as inputs to your design process, not as final answers. Your customer’s specific needs, your team’s capabilities, and your operational context all matter — and the docs can’t know about those.Day-in-the-life examples
Morning: starting a new feature
You’re adding Volunteer hours reporting to your existing integration. Open Cursor:“I’m extending our integration to add volunteer hours reporting. Walk me through the Virtuous documented approach for collecting and aggregating participation data. Cite the relevant docs.”The AI reads Report on Volunteer Hours and walks you through the two collection strategies (Project Dates vs. Users), the local raw store pattern, and the materialized-view aggregation approach. You start coding from a solid foundation.
Mid-morning: implementing the collector
“Implement the IncrementalParticipationCollector from the Virtuous docs in TypeScript. Adapt it to use our HTTP client and our Postgres connection.”The AI reads the documented reference class, adapts it, and produces working code.
Lunch: customer asks about a quirk
A customer messages you: “Why doesn’t my participation data refresh when a volunteer signs up for a new shift?” You ask Claude:“A Volunteer customer is asking why participation data doesn’t refresh immediately. We poll the User endpoint every 15 minutes. Check the Virtuous docs for the relevant explanation.”The AI finds the participation caveat (participations don’t advance User’s
updated_at), explains the issue, and you have an accurate response to send the customer.
Afternoon: writing tests
“Write integration tests for our Volunteer User polling loop. Cover the cases the Virtuous Change Detection Best Practices documentation calls out.”The AI reads the best practices page, identifies the test cases (checkpoint correctness, failure isolation, deletion detection), and generates test scaffolding for each.
End of day: writing customer-facing docs
“Write a section of our customer documentation explaining how we handle Volunteer User syncing. Reference the Virtuous documentation appropriately.”The AI produces documentation that explains your integration’s behavior in customer-friendly terms while crediting the underlying Virtuous patterns.
When to bypass MCP and read docs directly
MCP is great, but sometimes reading the docs yourself is faster:
MCP shines for questions the docs can answer but that take you longer to find than they take the AI. For “open this specific page I have bookmarked,” just open it.
Tips for AI-assisted integration teams
A few patterns that scale across a team of partner engineers:
The goal: every engineer who’s writing Virtuous integration code has access to documentation-grounded AI assistance by default.
Where to go next
MCP Tools Reference
The two tools the server exposes, with usage examples — useful for understanding what your AI is doing under the hood.
Connect to the Virtuous MCP Server
Setup instructions if you haven’t connected yet.
MCP Overview
What MCP is, what it can and can’t access, and the security model.
Integration Pathway
The partner integration workflow — MCP fits throughout it.