AI Assistant & integrations

Connect VolunteerBadge to Claude, Cursor & other AI tools (MCP)

Copy one prompt to connect Claude, Cursor, VS Code, Windsurf, Gemini CLI, or ChatGPT over MCP — plus the Skill.

Settings → API — the credentials that also power the Claude (MCP) connection. · click to enlarge

You can run FCRA-compliant volunteer background checks directly from your AI tools— Claude Desktop, Claude.ai, Claude Code, Cursor, VS Code with GitHub Copilot, Windsurf, Gemini CLI, ChatGPT, or any other MCP client — using VolunteerBadge's hosted MCP server. Nothing to install on a server; you connect one URL.

The connection URL

https://www.volunteerbadge.com/api/mcp

Install with your AI

Copy one prompt and paste it into Cursor, Claude, ChatGPT, Gemini CLI, VS Code, or Windsurf. The assistant adds VolunteerBadge to your user account, for every project, and signs in with VolunteerBadge. It does not write an API key into the config file.

Paste it into Cursor, Claude, ChatGPT, Gemini CLI, VS Code, or Windsurf.

Install the VolunteerBadge MCP server on this computer for my user account, so it is available in every project. Merge it into the existing user-level MCP config. Do not replace other servers, and do not put it only in this project's folder.

Name: volunteerbadge
URL: https://www.volunteerbadge.com/api/mcp
Auth: OAuth only. Do not add an API key or Authorization header.

Use the URL field this app actually reads. A wrong field is valid JSON and is silently ignored.
- Cursor: "url" in ~/.cursor/mcp.json (on Windows, %USERPROFILE%\.cursor\mcp.json). Do not use "httpUrl".
- Claude (desktop, Claude.ai, or Claude Code): a custom connector or remote MCP entry with the URL above. No API key.
- VS Code (GitHub Copilot): a user-level MCP entry with "type": "http" and "url". Do not write a project .vscode/mcp.json.
- Windsurf: "serverUrl" in the user config (~/.codeium/windsurf/mcp_config.json). Do not use "url" or "httpUrl".
- Gemini CLI: "httpUrl" in the user mcpServers settings (often ~/.gemini/settings.json). Do not use "url".
- ChatGPT: a custom connector with that URL and authentication set to OAuth. Developer mode must be on under Settings, then Apps & Connectors, then Advanced.

When the file or connector is saved, tell me the path you wrote and the one step I must do before the server shows up. For Cursor, that step is Reload Window. Then start OAuth and stop so I can sign in to VolunteerBadge, pick my organization, and Authorize.

When the assistant finishes, sign in to VolunteerBadge, pick your organization, and Authorize. In Cursor, reload the window before you look for the server. The options below are the same connection, added by hand.

Three hard rules (built in)

  • Never type a Social Security Number into chat.The subject enters their own SSN on a secure VolunteerBadge page; it's optional and only enriches address history.
  • Get authorization first. By default Claude sends the person a secure link to authorize before any check runs.
  • Records found ≠ reject. The law requires a pre-adverse-action notice with a copy of the report before any decision. Notices must be sent from the VolunteerBadge dashboard (Compliance center or the volunteer/direct-check workflow) — not from Claude chat.

Option 1 — Claude Desktop (one-click)

  1. Open Claude Desktop → Settings → Connectors.
  2. Click “Add custom connector”. Name it VolunteerBadge and paste the URL above.
  3. Click Connect → log into VolunteerBadge in the popup → pick your organization → Authorize.
  4. Done — the VolunteerBadge tools appear. Ask: “What's my VolunteerBadge credit balance?”

Option 2 — Claude.ai (web)

Same as Claude Desktop: Settings → Connectors → Add custom connector, paste the URL, click Connect, and complete the VolunteerBadge sign-in + authorize. (Custom connectors require a Pro, Max, Team, or Enterprise plan.)

Option 3 — Claude Code (one command)

First create an API key: VolunteerBadge dashboard → Settings → API → agree to the End-User Agreement → Create key. Then:

claude mcp add --transport http volunteerbadge \
  https://www.volunteerbadge.com/api/mcp \
  --header "Authorization: Bearer vb_live_xxxxxxxx"

Any MCP client works the same way — use the URL with an Authorization: Bearer <key> header.

Option 4 — Cursor, VS Code, Windsurf, Gemini CLI

The install prompt above signs these in with VolunteerBadge. To connect by hand instead, create an API key as in Option 3 and add VolunteerBadge to the tool's MCP settings file:

ToolWhere the setting goes
Cursor~/.cursor/mcp.json for every project, or .cursor/mcp.json inside one project.
VS Code (GitHub Copilot agent mode).vscode/mcp.json in your workspace, or “MCP: Add Server” from the Command Palette.
Windsurf~/.codeium/windsurf/mcp_config.json
Gemini CLI~/.gemini/settings.json

Cursor (Windsurf is identical with serverUrl in place of url; Gemini CLI uses httpUrl):

{
  "mcpServers": {
    "volunteerbadge": {
      "url": "https://www.volunteerbadge.com/api/mcp",
      "headers": { "Authorization": "Bearer vb_live_xxxxxxxx" }
    }
  }
}

VS Code:

{
  "servers": {
    "volunteerbadge": {
      "type": "http",
      "url": "https://www.volunteerbadge.com/api/mcp",
      "headers": { "Authorization": "Bearer vb_live_xxxxxxxx" }
    }
  }
}

Keep your key out of git

A project-level file (.cursor/mcp.json, .vscode/mcp.json) is committed with your code unless you ignore it. Put the key in the user-level file instead, or use your tool's environment-variable or input-prompt feature. If a key is ever exposed, revoke it in Settings → API and create a new one.

Option 5 — ChatGPT

On ChatGPT plans that allow custom connectors, turn on Developer mode(Settings → Apps & Connectors → Advanced settings), then create a connector: name it VolunteerBadge, paste the URL above, and choose OAuth. ChatGPT opens the same VolunteerBadge sign-in as Claude Desktop — log in, pick your organization, and Authorize. No API key needed. If you don't see Developer mode, your plan doesn't offer custom connectors yet.

Scenarios you can run

Once connected, just ask in plain English — Claude picks the right VolunteerBadge tool, keeps you consent-first, and never needs a Social Security Number in chat:

Ask Claude…What happens
“What’s my VolunteerBadge credit balance?”Reads your remaining checks so you know what’s available before ordering.
“Send a background-check authorization to Maria Lopez at maria@example.org, then run her check once she signs.”Emails the subject a secure consent link; the check runs automatically after she authorizes — no SSN ever touches the chat.
“Order checks for everyone on my approved roster who hasn’t been screened in the last year.”Lists your volunteers, finds the ones due, and queues the whole batch from a single prompt.
“Which of my pending checks have come back, and what do they say?”Pulls the current status of each check and summarizes the results (clear vs. needs review).
“A check came back with a record — what does it mean and what do I have to do?”Explains the result and the FCRA pre-adverse → wait → final steps. Directs you to Compliance or the adverse-action drawer to send notices by email — it won’t generate or send notices from chat.
“Do volunteers in Florida need to be re-screened every year?”Answers FCRA and screening-policy questions in plain English.

Building an automated workflow instead of chatting? The same actions are available over the REST API & webhooks.

The Skill (optional)

The connector's tools already enforce the rules above. For extra workflow guidance, install the VolunteerBadge Skill: download the Skill (.zip) and upload it in your Claude app's Skills / Capabilities area (availability varies by plan and version).

First check blocked? That's expected.

Two one-time setup steps can block a first check — both quick to clear:
  • “Your organization must re-accept the CRA End-User Agreement” — an owner/admin accepts the current version in Settings → API, then retry.
  • ID_VERIFICATION_REQUIRED on an instant check (request_instant_check) — your organization's owner completes a free, one-time identity verification in Settings → Account(“Verify my identity”), then retry. Consent-first checks (request_background_check) aren't affected.
Didn't find what you needed? Email support@volunteerbadge.com or browse all articles.