dg-eng/vanta-mcp-server

Vanta MCP Server

Production-quality Model Context Protocol (MCP) server for the Vanta API.

Overview

This MCP server provides comprehensive access to the Vanta security compliance platform, enabling automated security task management, vulnerability tracking, and compliance monitoring through Claude Code.

Architecture

• Language: Node.js (JavaScript ES Modules)
• Entry Point: server.js
• Launcher: run.sh
• Protocol: MCP (Model Context Protocol) over stdio
• Authentication: OAuth 2.0 client credentials flow

Features

Core Capabilities

• OAuth 2.0 authentication with Vanta API
• Automatic token refresh and expiration handling
• Comprehensive error handling
• Automatic pagination for all GET requests (fetches all pages by default)
• Support for filtering and custom parameters

Available Tools

Authentication Tools

• vanta_authenticate - Authenticate with Vanta API using configured credentials
• vanta_check_auth - Check authentication status and token expiration

Data Retrieval Tools

• vanta_get_vulnerabilities - Get vulnerabilities (with severity/status filtering)
• vanta_get_controls - Get compliance controls
• vanta_get_evidence_requests - Get evidence requests
• vanta_get_audits - Get audit information

Paginated Collection Tools ⭐ NEW

• vanta_get_all_tests - Get ALL tests with automatic pagination and filtering
• vanta_get_all_documents - Get ALL documents with automatic pagination and filtering
• vanta_get_all_policies - Get ALL policies with automatic pagination and filtering
• vanta_get_all_vendors - Get ALL vendors with automatic pagination and filtering

Flexible API Tool

• vanta_api_request - Make custom API requests with optional pagination

Configuration

Environment Variables

Create a .env file in the project root:

VANTA_CLIENT_ID=your_client_id_here
VANTA_CLIENT_SECRET=your_client_secret_here

MCP Configuration

The server is registered in your MCP configuration (user scope):

# View current configuration
claude mcp get vanta

# Configuration is stored in: ~/.config/claude-code/mcp_config.json (or similar)

Current configuration:

{
  "vanta": {
    "command": "/home/jasonrogers/src/daily-work/vanta-mcp-server/run.sh",
    "type": "stdio"
  }
}

Installation

Prerequisites

• Node.js v18+ (with ES modules support)
• npm or yarn
• Vanta API OAuth 2.0 credentials

Setup

# Install dependencies
npm install

# Make run script executable
chmod +x run.sh

# Configure environment
cp .env.example .env
# Edit .env with your credentials

# Test the server
node server.js

Usage

In Claude Code

1. Authenticate

Use vanta_authenticate tool

2. Get All Tests (with automatic pagination)

Use vanta_get_all_tests tool

# With filtering
Use vanta_get_all_tests with status_filter: "NEEDS_ATTENTION"
Use vanta_get_all_tests with category_filter: "HR"

3. Get All Documents

Use vanta_get_all_documents tool

# Filter by status
Use vanta_get_all_documents with status_filter: "Needs update"

4. Get All Policies

Use vanta_get_all_policies tool

# Filter by status
Use vanta_get_all_policies with status_filter: "RENEW_SOON"

5. Get All Vendors

Use vanta_get_all_vendors tool

# Filter by risk level
Use vanta_get_all_vendors with risk_filter: "HIGH"

# Get only vendors needing security review
Use vanta_get_all_vendors with unscored_only: true

6. Custom API Requests

Use vanta_api_request with:
  endpoint: "/custom-endpoint"
  method: "GET"
  paginate: true

Pagination

The server automatically handles pagination for all GET requests:

• Automatic: Fetches all pages by default (up to 100 pages for safety)
• Efficient: Combines results from multiple pages into a single response
• Transparent: Returns total count and pages fetched for visibility
• Flexible: Supports both GraphQL-style and REST-style pagination

Example Response Structure

{
  "results": {
    "data": [
      /* all items from all pages */
    ],
    "pageInfo": {
      "total": 150,
      "pages_fetched": 15
    },
    "filtered_count": 145,  // If filters applied
    "total_count": 150
  }
}

Disabling Pagination

For specific use cases where you want only one page:

Use vanta_api_request with:
  endpoint: "/tests"
  paginate: false

Development

Reloading Changes

When you modify server.js, reconnect the MCP server:

# In Claude Code
/mcp disconnect vanta
/mcp reconnect vanta

Project Structure

vanta-mcp-server/
├── server.js                              # Main MCP server (Node.js) ⭐ ACTIVE
├── run.sh                                 # Launcher script
├── .env                                   # Environment variables (gitignored)
├── package.json                           # Node.js dependencies
├── README.md                              # This file
├── run_server.sh.backup                   # Backup (not used)
└── src/vanta_mcp_server.python_backup/   # Archived Python implementation (not used)

⚠️ Important: The Python implementation in src/vanta_mcp_server.python_backup/ is archived and not used. All active development should be on server.js.

Adding New Tools

1. Add tool definition to the tools array
2. Add handler in the switch statement inside CallToolRequestSchema handler
3. Test with /mcp reconnect vanta

Example:

// 1. Add to tools array
{
  name: 'vanta_get_custom_data',
  description: 'Get custom data from Vanta',
  inputSchema: {
    type: 'object',
    properties: {
      filter: { type: 'string' }
    }
  }
}

// 2. Add handler
case 'vanta_get_custom_data': {
  const result = await makeVantaRequest('GET', '/custom-data', args || {});
  return {
    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
  };
}

Troubleshooting

Authentication Issues

• ✅ Verify .env file contains valid credentials
• ✅ Check that credentials have required scopes: vanta-api.all:read vanta-api.all:write
• ✅ Test authentication: Use vanta_authenticate tool

Tools Not Showing Up

• ✅ Reconnect the MCP server: /mcp disconnect vanta then /mcp reconnect vanta
• ✅ Check run.sh has execute permissions: chmod +x run.sh
• ✅ Verify run.sh points to server.js (not a Python file)

Pagination Issues

• ✅ Pagination is automatic for all GET requests by default
• ✅ Check response has results.pageInfo with pages_fetched count
• ✅ To disable pagination: use vanta_api_request with paginate: false

Server Not Starting

• ✅ Check Node.js version: node --version (should be v18+)
• ✅ Install dependencies: npm install
• ✅ Check for errors in server output
• ✅ Verify .env file exists and is readable

API Reference

Vanta API Documentation

• Getting Started
• Authentication
• API Endpoints

MCP Protocol

• Model Context Protocol Docs
• MCP Server Quickstart

Notes

• ✅ Active Implementation: Node.js server in server.js
• ⚠️ Archived: Python implementation in src/vanta_mcp_server.python_backup/
• ✅ Configuration: Managed via Claude MCP config (user scope)
• ✅ Pagination: Automatic for all GET requests
• ✅ All changes should be made to server.js

⚠️ IMPORTANT: How to Update This Server

Critical Facts About MCP Servers

MCP servers run as persistent background processes. Understanding this is key to avoiding hours of debugging:

1. The Active File: server.js (Node.js) - NOT the Python files!

   # Check what's actually running:
   cat run.sh
   # Output: exec node server.js
   

2. How Reconnecting Works:

   • /mcp reconnect vanta → Reconnects to the same running process
   • The Node.js process stays alive with the old code in memory
   • Changes to server.js are NOT picked up until process restarts

3. How to Properly Apply Changes:

   # Step 1: Edit server.js
   vim server.js
   
   # Step 2: In Claude Code, reconnect to restart the process
   /mcp
   # Select "Reconnect to vanta"
   
   # Step 3: Verify changes loaded
   # Test a new tool or check for updated behavior
   

Common Mistakes to Avoid

❌ WRONG: Editing Python files in src/vanta_mcp_server/

• These are archived and not used by the MCP server

❌ WRONG: Editing server.py or real_server.py

• These Python files are not executed

❌ WRONG: Clearing Python __pycache__

• Won't help because the server is Node.js

❌ WRONG: Expecting reconnect to reload code without restarting

• Reconnect reuses the same process

✅ CORRECT: Edit server.js and reconnect via /mcp

How to Verify Changes Are Loaded

1. Add a debug marker to authentication message:

   message: `Authenticated successfully [v2.0]. Token expires...`
   

2. Reconnect via /mcp command

3. Test authentication and check for your marker:

   Use vanta_authenticate tool
   # Should show: ✅ Authenticated successfully [v2.0]...
   

Debugging Checklist

If new tools aren't showing up:

• Did you edit server.js (not Python files)?
• Did you reconnect via /mcp (not just /mcp disconnect)?
• Does run.sh point to server.js? (cat run.sh)
• Are there syntax errors? (node server.js to test)
• Is the MCP config correct? (claude mcp get vanta)

File Structure Reference

vanta-mcp-server/
├── server.js                    ⭐ EDIT THIS FILE
├── run.sh                       ⭐ CHECK THIS (should run server.js)
├── .env                         ⭐ CREDENTIALS HERE
├── src/
│   └── vanta_mcp_server.python_backup/   ❌ DON'T EDIT (archived)
└── run_server.sh.backup         ❌ DON'T USE (old launcher)

Quick Reference: Where Things Are

Version History

v1.1.0 (Current)

• ✅ Added automatic pagination support
• ✅ Added 4 new paginated collection tools
• ✅ Added filtering capabilities
• ✅ Improved error handling
• ✅ Updated documentation

v1.0.0

• Initial Node.js implementation
• Basic Vanta API integration
• Core authentication and data retrieval tools

For SOC 2 Compliance: This server enables automated compliance monitoring and security task management through Claude Code integration with Vanta.