Deployment Guide

This guide covers installation, configuration, and deployment of the JA4+ MCP Server.

Prerequisites

Node.js: Version 20.0.0 or higher
Operating System: macOS, Linux, or Windows
Network Access: HTTPS to ja4db.com (for database downloads)
Disk Space: ~100MB for dependencies and database

Installation Methods

Method 1: Local Installation (Recommended for Development)

# Clone or download the server
git clone <repository> ja4-mcp-server
cd ja4-mcp-server

# Install dependencies
npm install

# Test the server
npm test

# Run the server (will download database on first run)
npm start

Method 2: Global Installation (Recommended for Production)

# Install globally
cd ja4-mcp-server
npm install -g .

# Run from anywhere
ja4-mcp-server

Method 3: Docker Deployment

Create Dockerfile:

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .

RUN chmod +x index.js

CMD ["node", "index.js"]

Build and run:

docker build -t ja4-mcp-server .
docker run -i ja4-mcp-server

Configuration

Claude Desktop Configuration

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ja4-analysis": {
      "command": "node",
      "args": ["/absolute/path/to/ja4-mcp-server/index.js"]
    }
  }
}

For global installation:

{
  "mcpServers": {
    "ja4-analysis": {
      "command": "ja4-mcp-server"
    }
  }
}

Database Configuration

The server automatically manages the JA4DB database:

Location: ./ja4db.json in the server directory
Source: https://ja4db.com/api/read/
Update Frequency: Every 24 hours
Manual Refresh: Use the refresh_database tool

To pre-download the database:

curl https://ja4db.com/api/read/ -o ja4db.json

Environment Variables (Optional)

You can customize behavior with environment variables:

# Database cache duration (milliseconds)
export JA4_CACHE_DURATION=86400000  # 24 hours (default)

# Database file location
export JA4_DB_FILE=/custom/path/ja4db.json

# Database URL (if using custom source)
export JA4_DB_URL=https://custom-ja4db.com/api/read/

Modify index.js to read these:

const CACHE_DURATION = process.env.JA4_CACHE_DURATION || 24 * 60 * 60 * 1000;
const DB_FILE = process.env.JA4_DB_FILE || path.join(process.cwd(), 'ja4db.json');
const DB_URL = process.env.JA4_DB_URL || 'https://ja4db.com/api/read/';

Network Requirements

Outbound Access

The server requires HTTPS access to:

ja4db.com (port 443) - For database downloads

If behind a corporate firewall:

# Set proxy if needed
export HTTPS_PROXY=http://proxy.company.com:8080

Firewall Rules

No inbound ports required (MCP uses stdio communication).

Deployment Scenarios

Scenario 1: Security Analyst Workstation

Use Case: Interactive analysis during investigations

Setup:

Install locally with npm install
Configure in Claude Desktop
Keep database auto-updating

Benefits:

Fast local analysis
No network latency
Full tool access

Scenario 2: SIEM Integration

Use Case: Automated enrichment of security alerts

Setup:

Deploy as system service
Create wrapper script for API-like access
Pre-download database for faster startup

Example systemd service (/etc/systemd/system/ja4-mcp.service):

[Unit]
Description=JA4+ MCP Analysis Server
After=network.target

[Service]
Type=simple
User=security
WorkingDirectory=/opt/ja4-mcp-server
ExecStart=/usr/bin/node /opt/ja4-mcp-server/index.js
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Scenario 3: Team Deployment

Use Case: Multiple analysts sharing common infrastructure

Setup:

Deploy on shared server
Use remote MCP connection
Centralize database management

Configuration (with SSH):

{
  "mcpServers": {
    "ja4-analysis": {
      "command": "ssh",
      "args": [
        "analyst@security-server.company.com",
        "node /opt/ja4-mcp-server/index.js"
      ]
    }
  }
}

Scenario 4: Air-Gapped Environment

Use Case: High-security environment without internet

Setup:

Download database on connected system
Transfer ja4db.json to air-gapped system
Disable auto-updates or point to internal mirror

# On connected system
curl https://ja4db.com/api/read/ -o ja4db.json

# Transfer to air-gapped system
scp ja4db.json analyst@airgapped:/opt/ja4-mcp-server/

# On air-gapped system, disable auto-refresh
# Edit index.js: Set CACHE_DURATION to a very large value

Performance Tuning

Memory Usage

Default: ~50-100MB (depends on database size)

To reduce memory:

// Limit database results
const dbResults = db.lookupJA4(fingerprint).slice(0, 10); // Top 10 only

Database Optimization

For large-scale analysis (>10,000 fingerprints):

// Batch processing
const BATCH_SIZE = 100;
for (let i = 0; i < fingerprints.length; i += BATCH_SIZE) {
  const batch = fingerprints.slice(i, i + BATCH_SIZE);
  await processBatch(batch);
}

Caching Strategies

Implement LRU cache for repeated analyses:

npm install lru-cache

import LRU from 'lru-cache';

const analysisCache = new LRU({
  max: 1000,
  ttl: 1000 * 60 * 60 // 1 hour
});

// Use in analyzer
const cached = analysisCache.get(fingerprint);
if (cached) return cached;
const result = JA4Analyzer.parseJA4(fingerprint);
analysisCache.set(fingerprint, result);

Monitoring

Health Checks

Add health check endpoint:

// Add to server setup
setInterval(() => {
  const stats = db.getStatistics();
  console.error(`[HEALTH] Database: ${stats.total_records} records, Last update: ${stats.last_update}`);
}, 300000); // Every 5 minutes

Logging

The server logs to stderr (doesn’t interfere with MCP protocol on stdout):

# Redirect logs to file
node index.js 2> ja4-mcp.log

# Or use systemd journal
journalctl -u ja4-mcp -f

Metrics

Track key metrics:

let metrics = {
  analyses_total: 0,
  database_lookups: 0,
  cache_hits: 0,
  errors: 0
};

// Increment in tool handlers
metrics.analyses_total++;

// Export metrics
function getMetrics() {
  return {
    ...metrics,
    uptime: process.uptime(),
    memory: process.memoryUsage()
  };
}

Troubleshooting

Issue: Database Download Fails

Symptoms: Error on startup: “Failed to download database”

Solutions:

Check network connectivity: curl https://ja4db.com/api/read/
Check proxy settings if behind firewall
Pre-download manually: curl https://ja4db.com/api/read/ -o ja4db.json
Verify disk space: df -h

Issue: MCP Server Not Appearing in Claude

Symptoms: Server not listed in Claude’s available tools

Solutions:

Verify config file location and syntax
Check absolute path to index.js
Ensure Node.js is in PATH
Restart Claude Desktop
Check Claude logs for MCP errors

Issue: High Memory Usage

Symptoms: Server consuming >500MB RAM

Solutions:

Limit database results: results.slice(0, 10)
Implement result pagination
Clear database cache periodically
Use streaming for large datasets

Issue: Slow Analysis

Symptoms: Tool calls taking >5 seconds

Solutions:

Implement analysis caching
Pre-load frequently-used fingerprints
Optimize database lookups with indexing
Use database stats to verify data loaded

Security Considerations

Input Validation

The server validates all fingerprint formats:

JA4: Must be a_b_c format
JA4H: Must be a_b_c_d format
Rejects invalid hex characters
Prevents injection attacks

Network Security

No inbound network ports
Only outbound HTTPS to ja4db.com
Stdio communication is local only

Data Privacy

No PII stored or logged
Fingerprints are hashed network metadata
JA4H cookie values are hashes (not actual cookies)
Compliant with GDPR for analysis use

Access Control

For team deployments, use SSH-based access:

# Configure SSH with key-based auth
ssh-keygen -t ed25519 -f ~/.ssh/ja4-mcp
ssh-copy-id -i ~/.ssh/ja4-mcp analyst@server

# Update MCP config
{
  "mcpServers": {
    "ja4-analysis": {
      "command": "ssh",
      "args": [
        "-i", "/home/user/.ssh/ja4-mcp",
        "analyst@server",
        "node /opt/ja4-mcp-server/index.js"
      ]
    }
  }
}

Backup and Recovery

Database Backup

# Daily backup
0 2 * * * cp /opt/ja4-mcp-server/ja4db.json /backup/ja4db-$(date +\%Y\%m\%d).json

# Keep 7 days
find /backup -name "ja4db-*.json" -mtime +7 -delete

Configuration Backup

# Backup MCP config
cp ~/Library/Application\ Support/Claude/claude_desktop_config.json \
   ~/backup/claude_desktop_config-$(date +%Y%m%d).json

Updates

Updating the Server

# For local installation
cd ja4-mcp-server
git pull  # or download new version
npm install

# For global installation
npm install -g .

Database Updates

Database updates automatically every 24 hours. To force update:

// Use the refresh_database tool
await refresh_database();

Production Checklist

Node.js 18+ installed
Dependencies installed (npm install)
Database pre-downloaded (optional but recommended)
MCP config file updated with correct path
Network access to ja4db.com verified
Disk space sufficient (~100MB)
Logging configured
Backups scheduled
Monitoring in place
Documentation accessible to team
Test queries successful

Support

For issues:

Check logs: cat ja4-mcp.log or journalctl -u ja4-mcp
Run tests: npm test
Verify database: ls -lh ja4db.json
Check Node version: node --version (should be 18+)
Test manually: echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node index.js

Additional Resources

README.md - Overview and features
EXAMPLES.md - Usage examples
QUICK-REFERENCE.md - Quick reference guide
JA4+ Specification
JA4DB Database
MCP Protocol