Connect to the Virtuous MCP Server

The Virtuous MCP server is hosted at a single URL — connect your AI tool to it, and the tool can search and read the Virtuous API docs as you work. This page covers setup for the most common AI tools.

The Virtuous MCP server URL

https://docs.virtuous.org/mcp

This is the URL you’ll configure in whichever AI tool you use. Mintlify hosts the server on Virtuous’s behalf — no setup, no maintenance, no authentication required (the server serves public documentation content).

If you haven’t yet, skim the MCP Overview — it covers what the server is, what it can and can’t access, and what value MCP adds to partner integration development.

Before you connect

A few quick checks:

Check	Detail
Your AI tool supports MCP	Most modern AI coding tools do. The instructions below cover Claude, Claude Code, Cursor, and VS Code. Other MCP-compatible tools follow similar patterns.
You’re on a recent version	MCP support is still relatively new. If you don’t see MCP options in your tool, update to the latest version.
Authentication isn’t required	The Virtuous docs are public, so the MCP server is open. No tokens, no login.
You don’t need a Virtuous account	This connects your AI tool to the documentation, not to your Virtuous account.

Setup by AI tool

Claude (web app)
Claude Code (CLI)
Cursor
VS Code (with Copilot)
Other MCP-compatible tools

To connect the Virtuous MCP server to the Claude web app:

Open Claude Connectors settings

Navigate to the Connectors page in your Claude settings.

Add a custom connector

Click Add custom connector.

Enter the server details

Name: Virtuous Docs
URL: https://docs.virtuous.org/mcp

Then click Add.

Use it in a conversation

In any Claude conversation, click the attachments button (the plus icon) and select the Virtuous Docs connector. Then ask Claude a question about Virtuous — for example: “What’s the right pattern for detecting new participations in the Volunteer API?”Claude will use the MCP server to consult the docs and produce a documentation-grounded answer.

See the Model Context Protocol documentation for general guidance on connecting remote MCP servers to Claude.

Claude Code is Anthropic’s command-line AI coding tool. To connect the Virtuous MCP server:

Run the add command

claude mcp add --transport http virtuous-docs https://docs.virtuous.org/mcp

This registers the Virtuous MCP server with Claude Code under the name virtuous-docs.

Verify the connection

claude mcp list

You should see virtuous-docs in the list of configured MCP servers.

Use it while coding

Run claude in your project directory and ask questions naturally. For example:

“I’m building a polling worker for the Volunteer Users endpoint. Check the docs for the right way to handle the updated_after checkpoint.”

Claude Code will use the MCP server to consult the docs and incorporate the patterns into its answer.

See the Claude Code MCP documentation for more details on managing MCP servers in Claude Code.

To connect the Virtuous MCP server to Cursor:

Open Cursor's MCP settings

Use Cmd/Ctrl + Shift + P to open the command palette, search for Open MCP settings, then click Add custom MCP. This opens the mcp.json configuration file.

Add the Virtuous MCP server

Add the Virtuous server to your mcp.json:

{
  "mcpServers": {
    "virtuous-docs": {
      "url": "https://docs.virtuous.org/mcp"
    }
  }
}

If you already have other MCP servers configured, just add the virtuous-docs entry alongside them.

Test the connection

In Cursor’s chat, ask: “What MCP tools do you have available?” Cursor should list the Virtuous MCP server’s tools (search_virtuous_api_docs and query_docs_filesystem_virtuous_api_docs).

Use it while coding

Ask Cursor questions naturally as you build. For example:

“Show me the field structure for the CRM+ Contact upsert. Check the Virtuous docs.”

Cursor’s AI will query the MCP server and produce an answer grounded in the actual docs.

See the Cursor MCP documentation for more details.

To connect the Virtuous MCP server to VS Code’s GitHub Copilot:

Create the MCP config file

Create a .vscode/mcp.json file in your workspace (or open the global MCP settings).

Add the Virtuous MCP server

Add the Virtuous server to mcp.json:

{
  "servers": {
    "virtuous-docs": {
      "type": "http",
      "url": "https://docs.virtuous.org/mcp"
    }
  }
}

Reload the Copilot Chat session

VS Code picks up the MCP config on reload. Start a new Copilot Chat session to make sure the new server is loaded.

Use it while coding

Ask Copilot questions naturally:

“I need to handle the email-change problem when syncing Volunteer Users. What does the documentation recommend?”

Copilot will use the MCP server to consult the relevant Virtuous docs and produce an answer.

See the VS Code MCP documentation for more details.

Any tool supporting the MCP standard can connect to the Virtuous MCP server. The general pattern:

Configuration	Value
Server URL	`https://docs.virtuous.org/mcp`
Transport	HTTP
Authentication	None (public docs)
Server name (your choice)	e.g., `virtuous-docs`

For tool-specific instructions, consult the tool’s MCP documentation. Common patterns:

JSON-based MCP configuration files: add an entry pointing to the URL above
Programmatic MCP clients: use standard MCP HTTP transport with the URL
CLI-based MCP managers: typically have an add or register command similar to Claude Code’s

The Model Context Protocol documentation covers MCP standards and reference implementations for tool authors.

Verifying the connection works

A quick test for any tool: ask the AI a question that requires Virtuous-specific knowledge. Good test prompts:

Prompt	What you should see
”What’s the page size for the Volunteer Users endpoint?”	An answer mentioning 15 records, not partner-configurable (the Volunteer-specific quirk)
“How does the CRM+ Transaction endpoint handle Contact matching?”	An answer citing the Transaction endpoint’s matching logic
”What’s the URL versioning convention across the three Virtuous APIs?”	An answer covering that CRM+ and Raise are unversioned while Volunteer uses `/v1/`

If the AI gives a generic REST answer instead of the Virtuous-specific one, the MCP server may not be connected — re-check your setup.

Quick test in your IDE

For Cursor and VS Code specifically, you can confirm the tools are loaded by asking:

“What MCP tools do you have available right now?”

The response should list search_virtuous_api_docs and query_docs_filesystem_virtuous_api_docs. If those aren’t in the list, the MCP server isn’t connected for that session.

Managing the connection

Task	How
Update server URL	Edit your tool’s MCP config; reload the AI session
Disable temporarily	Most tools support toggling MCP servers on/off without removing the config
Remove the connection	Delete the `virtuous-docs` entry from your tool’s MCP config
Check connection health	Most tools surface MCP server status in their settings UI; for Claude Code, `claude mcp list` shows status
Switch to a different MCP server URL	Update the URL in your config and reload the session

The server URL https://docs.virtuous.org/mcp is stable. Mintlify hosts it; Virtuous doesn’t move it around.

Connecting multiple MCP servers

You’ll likely have multiple MCP servers connected — the Virtuous docs server, plus servers for your own codebase, plus possibly servers for other vendors you integrate with. The AI tool decides which server to query based on the question. A few practical notes:

Consideration	Detail
Servers don’t constantly consume context	The AI only queries a server when it decides the query is relevant. Idle MCP servers cost nothing.
Multiple-server queries can use more context	If the AI consults several servers for one question, the combined results add up. Be specific in prompts to help the AI focus.
Disconnect unused servers	If you’re not actively using a server for current work, removing it from your config reduces complexity.
Server identity matters in prompts	”Check the Virtuous docs” is more useful than “check the docs” if you have multiple connected docs servers.

See Using MCP for Integration Development for the practical prompting patterns.

Troubleshooting

The AI isn’t using the docs

Symptom: You ask a Virtuous question; the AI gives a generic answer that doesn’t seem to reflect the docs. Possible causes:

Cause	Fix
MCP server not configured for this session	Re-check the AI tool’s config; reload the session
MCP server configured but not enabled (some tools have a toggle)	Enable it in the tool’s settings
AI tool doesn’t actually support MCP (older versions)	Update the tool to a recent version
Question was answered from training data without MCP consultation	Be more specific: “Check the Virtuous docs and tell me…”

Connection errors

Symptom: The AI tool reports it can’t reach the MCP server. Possible causes:

Cause	Fix
Network connectivity issue	Confirm you can reach `https://docs.virtuous.org` in a browser
Corporate firewall blocking MCP traffic	Check with your IT team — `docs.virtuous.org` should be allowed
Tool-side config error (typo in URL, malformed JSON)	Re-check the config matches the patterns above
Tool is on an old MCP version that doesn’t support HTTP transport	Update the tool

Slow responses

MCP queries add a small amount of latency — the AI calls the server, waits for results, then incorporates them. For most workflows this is unnoticeable. If responses feel particularly slow:

Cause	Fix
Tool is querying many MCP servers per question	Be more specific in prompts to narrow the AI’s search
The AI is doing multiple sequential queries	Some patterns are inherently multi-query (search, then read; read, then cross-reference). This is normal.
Network slowness	Standard troubleshooting — try again, check connection

Getting help

If you’ve tried the above and the MCP server still isn’t working as expected:

For tool-specific issues (Claude/Cursor/VS Code), check the tool’s own documentation and support channels
For Virtuous-side issues (the MCP server itself appears down), reach out to your Partner Manager
For Mintlify infrastructure issues (the MCP host), Mintlify’s docs and support cover the broader platform

Where to go next

Using MCP for Integration Development

Now that you’re connected — the practical patterns for using MCP while building integrations.

MCP Tools Reference

The two tools the server exposes, with examples of when each is used.

MCP Overview

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

Partner Resources

The full set of partner resources — Partner Portal, Academy, Marketplace, and more.

​The Virtuous MCP server URL

​Before you connect

​Setup by AI tool

​Verifying the connection works

​Quick test in your IDE

​Managing the connection

​Connecting multiple MCP servers

​Troubleshooting

​The AI isn’t using the docs

​Connection errors

​Slow responses

​Getting help

​Where to go next

Using MCP for Integration Development

MCP Tools Reference

MCP Overview

Partner Resources

The Virtuous MCP server URL

Before you connect

Setup by AI tool

Verifying the connection works

Quick test in your IDE

Managing the connection

Connecting multiple MCP servers

Troubleshooting

The AI isn’t using the docs

Connection errors

Slow responses

Getting help

Where to go next