Validus MCP Server

Model Context Protocol (MCP) server for exposing Validus workspace data to Claude Desktop and other MCP clients.

Overview

The Validus MCP server is a lightweight HTTP proxy that enables Claude Desktop to access your Validus workspace data securely using Platform API keys.

Architecture

┌─────────────────┐
│ Claude Desktop  │
└────────┬────────┘
         │ MCP Protocol (stdio)
         │
┌────────▼─────────┐
│  MCP Server      │ (Lightweight proxy - NO database access)
│  (Node.js)       │
└────────┬─────────┘
         │ HTTP + API Key
         │
┌────────▼─────────┐
│ Validus API      │
│ Gateway          │
└────────┬─────────┘
         │
    ┌────┴────┐
    │         │
┌───▼──┐  ┌──▼────┐
│Lambda│  │Database│
│Funcs │  │(RDS)   │
└──────┘  └────────┘

Key Features

• 🔐 Secure: Only requires Platform API key - NO database credentials needed
• 🚀 Lightweight: Single dependency (@modelcontextprotocol/sdk)
• 📊 16 Workspace Tools: Content, audits, citations, visitor analytics
• ⚡ Fast: Direct HTTP calls to Validus API
• 🔒 Workspace-Scoped: Each API key is tied to a specific workspace
• 📝 Auto-Logged: All usage tracked by Validus API
• 🎯 Rate Limited: Rate limiting handled by Validus API

Quick Start

Prerequisites

1. Validus Platform API Key

   • Create one at: Settings → Platform API Keys
   • Format: vld_live_<32_chars>

2. Validus API Running

   • Local: http://localhost:3000 (via ./start-local-dev.sh)
   • Production: https://app.validus.ai

Installation

Option 1: npx (Recommended)

No installation needed! Just configure Claude Desktop:

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "validus": {
      "command": "npx",
      "args": [
        "-y",
        "validus-mcp-server"
      ],
      "env": {
        "MCP_API_KEY": "vld_live_YOUR_KEY_HERE",
        "VALIDUS_API_URL": "http://localhost:3000"
      }
    }
  }
}

Restart Claude Desktop and you're done! The latest version will be downloaded automatically.

Option 2: Global Install

npm install -g validus-mcp-server

Then configure Claude Desktop:

{
  "mcpServers": {
    "validus": {
      "command": "validus-mcp-server",
      "args": [],
      "env": {
        "MCP_API_KEY": "vld_live_YOUR_KEY_HERE",
        "VALIDUS_API_URL": "http://localhost:3000"
      }
    }
  }
}

Option 3: Local Build (Development)

cd mcp-server
npm install
npm run build

Then configure Claude Desktop with the full path:

{
  "mcpServers": {
    "validus": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/mcp-server/dist/register.js"
      ],
      "env": {
        "MCP_API_KEY": "vld_live_YOUR_KEY_HERE",
        "VALIDUS_API_URL": "http://localhost:3000"
      }
    }
  }
}

Test It

Restart Claude Desktop and ask: "List my reference files"

Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | MCP_API_KEY | ✅ Yes | - | Platform API key (starts with vld_live_) | | VALIDUS_API_URL | ❌ No | http://localhost:3000 | Validus API base URL |

Example Configurations

Local Development:

{
  "env": {
    "MCP_API_KEY": "vld_live_a926f083e4428707c6960c2d2e30134e",
    "VALIDUS_API_URL": "http://localhost:3000"
  }
}

Production:

{
  "env": {
    "MCP_API_KEY": "vld_live_YOUR_PRODUCTION_KEY",
    "VALIDUS_API_URL": "https://app.validus.ai"
  }
}

Available Tools (16)

File Tools (3)

• list_available_files - List reference files with metadata
• search_files - Full-text search inside file contents
• read_file_content - Read full content of specific files

Site Audit Tools (2)

• search_site_audits - Search SEO/AEO/GEO audit results
• get_audit_details - Get detailed audit results with remediation

Optimizer Tools (2)

• search_optimizer_checks - Search AI optimizer check results
• get_optimizer_page_analysis - Get detailed page optimization analysis

Citation Tools (3)

• search_citations - Search AI citations across platforms
• get_cited_sources - Get citing domains and sources
• analyze_visibility_gaps - Identify visibility gaps vs competitors

Visitor Analytics Tools (6)

• get_visitor_analytics_summary - High-level visitor statistics
• analyze_bot_traffic - Bot vs human traffic analysis
• get_visitor_time_trends - Traffic trends over time
• get_top_visited_pages - Most visited pages
• analyze_bot_verification - Bot verification analysis
• get_traffic_sources - Traffic source breakdown

API Key Management

Creating Keys

Via Validus UI:

1. Go to Settings → Platform API Keys
2. Click "Create New API Key"
3. Enter name and description
4. Select workspace
5. Set rate limit (default: 60 req/min)
6. Copy the key (shown only once!)

Key Format

vld_live_<32_random_hex_chars>

Example: vld_live_a926f083e4428707c6960c2d2e30134e

Security

• Keys are stored as SHA-256 hashes (never plaintext)
• Each key is scoped to a single workspace
• Keys can be revoked instantly
• All usage is logged for audit trail

Development

Building

cd mcp-server
npm install
npm run build

Running Locally

# Development mode with hot reload
npm run dev

# Production mode
npm start

Testing Tools

Test with the MCP CLI:

# List available tools
npx @modelcontextprotocol/cli list-tools dist/server.js

# Call a tool
export MCP_API_KEY="vld_live_YOUR_KEY"
export VALIDUS_API_URL="http://localhost:3000"
npx @modelcontextprotocol/cli call-tool dist/server.js \
  list_available_files \
  '{}'

Troubleshooting

API Key Invalid

Symptom: Invalid API key format error

Solutions:

1. Verify key format: must start with vld_live_
2. Check key is active in Validus UI
3. Confirm key hasn't expired

Cannot Connect to API

Symptom: Request timeout or connection errors

Solutions:

1. Verify VALIDUS_API_URL is correct
2. Check Validus API is running:

   curl http://localhost:3000/health

3. For local dev, ensure ./start-local-dev.sh is running

Rate Limit Exceeded

Symptom: Rate limit exceeded error

Solutions:

1. Wait 1 minute for rate limit window to reset
2. Increase rate limit for your API key (up to 10k req/min)
3. Use multiple API keys for parallel workloads

Claude Desktop Not Connecting

Solutions:

1. Check Claude Desktop logs:

   tail -f ~/Library/Logs/Claude/mcp*.log

2. Verify config file syntax (must be valid JSON)
3. Use absolute paths (not ~ or relative paths)
4. Restart Claude Desktop completely

Architecture Decisions

Why HTTP Proxy Instead of Direct Database Access?

Benefits:

• Security: MCP clients never get database credentials
• Simplicity: Only need API key + API URL
• Maintainability: All business logic stays in Lambda functions
• Scalability: Leverage existing API Gateway rate limiting
• Auditability: All MCP usage logged through normal API logging

Why Workspace-Scoped Keys?

Benefits:

• Simpler tool calls: No workspace_id parameter needed
• Better security: Keys can't access other workspaces
• Clear audit trail: Key usage tied to specific workspace
• Matches session behavior: Sessions also have workspace_id

Deployment

Docker

# Build image
docker build -t validus-mcp-server:latest -f mcp-server/Dockerfile .

# Run container
docker run -d \
  --name mcp-server \
  -e MCP_API_KEY="vld_live_YOUR_KEY" \
  -e VALIDUS_API_URL="https://app.validus.ai" \
  validus-mcp-server:latest

AWS ECS Fargate

The MCP server can be deployed to ECS Fargate using Terraform.

See: infrastructure/modules/mcp-server/ for Terraform configuration.

Resources

• MCP Specification: https://modelcontextprotocol.io/docs
• Claude Desktop: https://claude.ai/download
• Validus API Docs: docs/4-development/API-ENDPOINTS.md

Support

For issues or questions:

1. Check MCP server logs (stderr output)
2. Check Claude Desktop logs: ~/Library/Logs/Claude/mcp*.log
3. Verify API key is active in Validus UI
4. File issue: GitHub Issues

Status: ✅ Production Ready (HTTP Proxy Architecture) Version: 2.0.0 Last Updated: November 10, 2025