Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.karmacheck.com/llms.txt

Use this file to discover all available pages before exploring further.

Get started with KarmaCheck’s MCP server using this guide — it covers prerequisites, authenticating the MCP server, configuring Claude Desktop and Cursor, trying starter prompts (including test SSNs), and the path to production. If anything’s unclear or you need a hand, reach out to us at mcp@karmacheck.com.

​
Setup prerequisites

​
Authenticating the MCP server

See the authentication page for details on how to retrieve the authentication token for KarmaCheck’s MCP server. The JWT token generated using the combination of your API key and client secret will be used to authenticate your connection to the MCP server. The subsequent steps will show you how this authentication token is used.

​
Get setup on Claude Desktop

​
Prerequisites

You will need to install the following dependencies before progressing with this section:
  • Claude Desktop
  • Node.js Version 22+

​
Steps to setup the KarmaCheck MCP server

  1. Open Claude Desktop — the free tier should work for this guide, though you may experience some rate limiting.
  2. Go to Settings → Developer → Edit Config.
  3. Insert the following into the claude_desktop_config.json. Replace <my-token> with your JWT token (see the authentication section for details):
{
  "mcpServers": {
    "karmacheck-dev": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp-stage.karmacheck.io",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <my-token>"
      }
    }
  }
}
  1. Quit and restart Claude Desktop.
  2. Get started using the Starter prompts.

​
Get setup on Cursor

​
Prerequisites

You will need to install the following dependencies before progressing with this section:
  • Cursor IDE
  • Node.js Version 22+

​
Steps to setup the KarmaCheck MCP server

  1. Open Cursor.
  2. Navigate to Cursor → Settings → Cursor Settings.
  3. Click on Tools & Integrations → Add Custom MCP.
  4. Insert the following into the mcp.json file. Replace <my-token> with your JWT token:
{
  "mcpServers": {
    "karmacheck-dev": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp-stage.karmacheck.io",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <my-token>"
      }
    }
  }
}
  1. You should see the KarmaCheck MCP server and the associated tools under the MCP Tools section within “Tools & Integrations”.
  2. Get started using the Starter prompts.

​
Starter prompts for using KarmaCheck via MCP

​
Test emails & SSNs

All order-specific emails in your sandbox account are automatically sent to the default email address on your account (the one you used to sign up). This includes any emails sent to test candidate addresses. In our system, email addresses act as the unique identifier for candidates, so each order must use a unique email address. A simple way to achieve this is by appending a date and timestamp to a test email, for example: test+20250808T1530@test.com. For testing purposes during onboarding:
  • Use SSN 111-22-3333 to generate all CLEAR/COMPLETE results.
  • Use SSN 333-22-1111 to generate NEEDS REVIEW results.
  • All other SSNs will be blocked in the sandbox environment.

​
Create a case

Creating a case requires the candidate’s First Name, Last Name, and Email Address. If any of these details are missing, KarmaCheck will prompt you to provide them. Example prompts: 
Verify the identity, motor vehicle records, and criminal background of Jane Doe (jane.doe@email.com), who is applying for a Senior Driving Instructor position, using KarmaCheck.

Run a nationwide criminal background search on Jane Doe, whose email address is jane.doe@email.com, using KarmaCheck.

Create a case for John Smith at john.smith@email.com and only run a Motor Vehicle Records check.

Verify the identity, motor vehicle records, and criminal background for Emily Johnson (emily.johnson@email.com) applying as a Delivery Driver.

Verify the criminal background of a candidate named Michael applying as a Chauffeur.
KarmaCheck will prompt you to provide the last name and email to create the case.

​
Get the status of all cases in your dashboard

Example prompts: 
Provide a list of all candidate cases that require candidate action.

Provide a list of all candidate cases that require candidate action. For each case, draft a personalized email prompting the candidate to complete the necessary steps to move their case forward.

Show me all candidate cases where background checks are delayed due to missing candidate actions.

List all candidate cases that are waiting on the candidate, and suggest the next actions to resolve each case.

​
Get details on a specific case

When testing in the sandbox environment, make sure to complete the candidate onboarding process first. This will generate cases in various stages of completion, allowing you to fully test prompts and workflows.
Example prompts: 
What's going on with John Smith's case?

Provide a detailed status update on Emily Johnson's case, including any pending actions or completed checks.

Has the Motor Vehicle Records check been completed for Michael Lee's case?

What is preventing Sarah Brown's case from moving forward, and what actions are required?

Show me the timeline of all activities for David Wilson's case.

​
Monitoring use case

You can monitor candidate records on a recurring basis to ensure compliance and up-to-date checks. Monitoring prompts can be resource intensive, so use them thoughtfully with a clear timeframe. Example prompts: 
Run a Motor Vehicle Records (MVR) check on all candidates who have not had an MVR check in the past 7 days using KarmaCheck.

Run a Motor Vehicle Records (MVR) check on all candidates who have not been checked in the last 30 days.

Identify all candidates who have not had a Motor Vehicle Records check in the past 14 days and run new checks for them.

List all candidates overdue for a Motor Vehicle Records check based on a 60-day cycle, and initiate new checks for each.

​
Ready for production?

  1. Request production access — Join the MCP production waitlist. You’ll be the first to know when production MCP accounts become available.
  2. Credentialing & contracting — Your organization will complete contracting and credentialing to ensure you’re approved to run background checks in compliance with applicable regulations.
  3. Unlock full services — Once approved, you’ll gain access to the full suite of KarmaCheck screenings and services in production.
Since background checks involve PII and, at times, PHI, we strongly recommend using enterprise-grade LLMs with secure tool-calling capabilities to ensure data protection and compliance. Examples include GPT-5 (ChatGPT Enterprise or Azure OpenAI), Anthropic Claude Opus/Sonnet (via Amazon Bedrock), Amazon Nova Pro/Lite, Cohere Command R+, and Google Gemini 1.5 Pro (via Vertex AI).