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

# Connect to the Virtuous MCP Server

> Setup instructions for connecting Claude, Claude Code, Cursor, VS Code, and other MCP-compatible AI tools to the Virtuous documentation 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

```text theme={null}
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).

<Tip>
  If you haven't yet, skim the [MCP Overview](/virtuous/mcp/overview) — it covers what the server is, what it can and can't access, and what value MCP adds to partner integration development.
</Tip>

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

<Tabs>
  <Tab title="Claude (web app)">
    To connect the Virtuous MCP server to the Claude web app:

    <Steps>
      <Step title="Open Claude Connectors settings">
        Navigate to the [Connectors](https://claude.ai/settings/connectors) page in your Claude settings.
      </Step>

      <Step title="Add a custom connector">
        Click **Add custom connector**.
      </Step>

      <Step title="Enter the server details">
        * **Name:** `Virtuous Docs`
        * **URL:** `https://docs.virtuous.org/mcp`

        Then click **Add**.
      </Step>

      <Step title="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.
      </Step>
    </Steps>

    See the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server) for general guidance on connecting remote MCP servers to Claude.
  </Tab>

  <Tab title="Claude Code (CLI)">
    Claude Code is Anthropic's command-line AI coding tool. To connect the Virtuous MCP server:

    <Steps>
      <Step title="Run the add command">
        ```bash theme={null}
        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`.
      </Step>

      <Step title="Verify the connection">
        ```bash theme={null}
        claude mcp list
        ```

        You should see `virtuous-docs` in the list of configured MCP servers.
      </Step>

      <Step title="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.
      </Step>
    </Steps>

    See the [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp) for more details on managing MCP servers in Claude Code.
  </Tab>

  <Tab title="Cursor">
    To connect the Virtuous MCP server to Cursor:

    <Steps>
      <Step title="Open Cursor's MCP settings">
        Use <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> to open the command palette, search for **Open MCP settings**, then click **Add custom MCP**. This opens the `mcp.json` configuration file.
      </Step>

      <Step title="Add the Virtuous MCP server">
        Add the Virtuous server to your `mcp.json`:

        ```json theme={null}
        {
          "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.
      </Step>

      <Step title="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`).
      </Step>

      <Step title="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.
      </Step>
    </Steps>

    See the [Cursor MCP documentation](https://docs.cursor.com/en/context/mcp) for more details.
  </Tab>

  <Tab title="VS Code (with Copilot)">
    To connect the Virtuous MCP server to VS Code's GitHub Copilot:

    <Steps>
      <Step title="Create the MCP config file">
        Create a `.vscode/mcp.json` file in your workspace (or open the global MCP settings).
      </Step>

      <Step title="Add the Virtuous MCP server">
        Add the Virtuous server to `mcp.json`:

        ```json theme={null}
        {
          "servers": {
            "virtuous-docs": {
              "type": "http",
              "url": "https://docs.virtuous.org/mcp"
            }
          }
        }
        ```
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>
    </Steps>

    See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details.
  </Tab>

  <Tab title="Other MCP-compatible tools">
    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](https://modelcontextprotocol.io/docs) covers MCP standards and reference implementations for tool authors.
  </Tab>
</Tabs>

## 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](/virtuous/mcp/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](https://www.mintlify.com/docs/ai/model-context-protocol) and support cover the broader platform

## Where to go next

<CardGroup cols={2}>
  <Card title="Using MCP for Integration Development" icon="code" href="/virtuous/mcp/using-mcp-for-integration-development">
    Now that you're connected — the practical patterns for using MCP while building integrations.
  </Card>

  <Card title="MCP Tools Reference" icon="book" href="/virtuous/mcp/tools-reference">
    The two tools the server exposes, with examples of when each is used.
  </Card>

  <Card title="MCP Overview" icon="circle-info" href="/virtuous/mcp/overview">
    What MCP is, why it matters for partners, and the security model.
  </Card>

  <Card title="Partner Resources" icon="toolbox" href="/virtuous/partners/partner-resources">
    The full set of partner resources — Partner Portal, Academy, Marketplace, and more.
  </Card>
</CardGroup>