Practical patterns for using the Virtuous MCP server while building partner integrations — prompting techniques, day-to-day workflows, and how MCP fits with the rest of your AI-assisted development
Once you’ve connected your AI tool to the Virtuous MCP server, the question becomes: how do you actually use it well? This page covers the practical patterns — prompting techniques, integration-development workflows, common gotchas, and how MCP fits with the rest of your AI-assisted development.This is partner-focused. The examples assume you’re building (or maintaining) an integration against CRM+, Raise, or Volunteer.
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:
Pattern
Example
Ask before designing
”I need to sync VOMO Users into our Postgres database. What pattern do the Virtuous docs recommend?”
Ask before implementing
”Show me the actual field shape for the CRM+ Contact create payload, then help me write the JS function”
Ask while debugging
”I’m getting a 422 from POST /users with this payload [paste]. Check the Virtuous docs for the validation rules”
Ask while reviewing
”Review this polling loop I wrote against the patterns in the Virtuous docs”
Ask while documenting
”Help me write a user-facing description of how my integration handles the email-change problem. Pull from the relevant Virtuous docs first.”
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.
Small changes in how you phrase questions make a big difference:
Weak prompt
Strong prompt
”How do I poll an API?"
"What polling cadence does the Virtuous Volunteer documentation recommend for User sync? Check the docs."
"How do I handle errors?"
"What does the Virtuous Volunteer API return on 422 errors, and what’s the documented recovery pattern?"
"Show me how to upsert"
"Show me the Virtuous CRM+ Contact upsert flow, including the matching key behavior, from the docs."
"What’s a good cache TTL?"
"What cache TTLs do the Virtuous best practices documents recommend for different resource types in CRM+?”
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.
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.
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.
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.
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.”
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.
“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).”
Most partners use multiple AI capabilities together. MCP for docs fits with:
Other tool
How it combines
MCP for your own codebase
The AI reads both your code and the Virtuous docs — ideal for “compare this code against the documented best practices”
MCP for a third-party API you also integrate with
Cross-API analysis (“how should this Volunteer User be transformed for our Salesforce schema?”)
AI code completion (Copilot etc.)
Inline completions for the local context; MCP queries for documentation grounding
Standalone AI chat (without MCP)
Use MCP-connected sessions for Virtuous-specific work; standalone chat for unrelated tasks
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.
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?”
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.
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.
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.
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.
“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.
MCP is great, but sometimes reading the docs yourself is faster:
Scenario
Direct docs is faster
You know the exact page you want
Just open it
You need to scan visual content (Mermaid diagrams, tables)
Browser is better than AI summary
You’re orienting yourself in an unfamiliar resource family
The data model pages have visual diagrams
You want to bookmark or share specific sections
URLs are what you want
You’re comparing 5-10 fields across resources
Tabular comparison in a browser tab 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.
