MCP Server: Overview & Setup

What is the Hades MCP Server?

The Hades MCP (Model Context Protocol) Server is an AI-native interface to the Hades dark web intelligence platform. It exposes 21 specialized tools for natural language querying through Claude AI, transforming complex database queries into conversational intelligence gathering.

Instead of writing MongoDB queries or clicking through Maltego transforms, you can simply ask questions:

“Find all dark web sites using Bitcoin address bc1qxy2…”
“Show me high-risk drug marketplaces discovered in the last 7 days”
“Track this Telegram handle across all servers: @darkvendor”
“Analyze the connections between these 3 marketplaces”

Claude automatically selects the appropriate Hades tools, executes queries, and synthesizes results into actionable intelligence.

Key Features

AI-Native Conversational Interface

Query dark web intelligence using natural language instead of learning complex query syntax or visual tools.

Traditional Approach:

db.entities.aggregate([
  { $match: { type: 'bitcoin', value: 'bc1qxy2...' } },
  { $lookup: { from: 'http', localField: 'source_url', foreignField: 'server', as: 'server_data' } },
  { $lookup: { from: 'labels', localField: 'source_url', foreignField: 'server', as: 'labels' } },
  { $unwind: '$server_data' },
  { $unwind: '$labels' },
  { $project: { server: '$source_url', title: '$server_data.title', risk: '$labels.risk_level' } }
])

MCP Server Approach:

"Find all sites using this Bitcoin address"

21 Specialized Tools

The MCP Server provides 21 tools across 5 categories:

Cryptocurrency Investigation (5 tools)

Track wallets across the dark web
Find servers accepting specific crypto
Monitor wallet activity over time
Cross-reference multiple wallets

Communication Tracking (4 tools)

Search emails, Telegram, Discord
Find servers by contact method
Vendor attribution analysis
Cross-platform identity tracking

Infrastructure Fingerprinting (4 tools)

Identify identical infrastructure (SHV)
Find co-hosted sites (SSH fingerprints)
Cluster servers by infrastructure
Technology stack analysis

Server Intelligence (4 tools)

Advanced server queries with filters
Comprehensive server profiles
Risk assessment and scoring
Real-time threat intelligence feeds

Relationship Mapping (4 tools)

Build investigation graphs
Temporal analysis and timelines
Network analysis between servers
Track entity evolution

View Complete Tool Reference →

Direct Database Access

The MCP Server queries the Hades database directly with:

15 Collections - servers, http, labels, entities, ports, javascript, shv, images, preprocessed, favourites, api, api_usage, organisations, processor_queue, errors
3M+ Documents - 163K+ servers, 375K+ entities, 2.1M+ images
Optimized Queries - Aggregation pipelines for efficient cross-collection joins
Real-Time Data - Direct access to latest intelligence

Architecture

Technology Stack

Node.js + TypeScript - Modern, type-safe backend
MongoDB Driver - Direct database access with connection pooling
MCP SDK - Model Context Protocol for Claude integration
Zod - Runtime type validation for all inputs
Docker - Containerized deployment

Data Flow

User Question (Claude Desktop)
    ↓
Claude AI (selects appropriate MCP tools)
    ↓
Hades MCP Server (validates input, builds query)
    ↓
MongoDB (executes aggregation pipeline)
    ↓
MCP Server (formats results)
    ↓
Claude AI (synthesizes into answer)
    ↓
User receives actionable intelligence

Authentication & Licensing

The MCP Server supports API key authentication with usage-based licensing:

Licensing Tiers:

Free - 100 queries/month (research & testing)
Professional - 10,000 queries/month (analysts & consultants)
Enterprise - Unlimited queries (large teams)
Academic - 50,000 queries/month (universities & research)

Usage automatically resets on the 1st of each month.

Integration Options

Hades MCP Server works with multiple AI platforms for different use cases:

Claude Desktop

Best for: Interactive investigations with best-in-class AI reasoning

The easiest way to access Hades intelligence through natural language. Claude Desktop provides an intuitive conversational interface with excellent multi-tool reasoning for complex investigations.

What you can do:

Ask questions in natural language
Conduct multi-step investigations
Build comprehensive intelligence reports
Use specialized Claude Code skills

Claude CLI

Best for: Terminal-based workflows and automation

Command-line access to Hades intelligence for investigators who prefer terminal environments or need to integrate with scripts and workflows.

What you can do:

Terminal-based investigations
Script-friendly automation
Integration with existing CLI workflows
Specialized investigation skills

Ollama (Local AI)

Best for: Air-gapped environments and privacy-sensitive investigations

Use Hades with locally-running AI models (Llama, Mistral) for environments where dark web intelligence must stay on-premise.

What you can do:

Fully local inference (no cloud)
Air-gapped investigations
Cost-effective high-volume queries
Data sovereignty compliance

OpenAI Integration

Best for: Custom applications and programmatic access

Integrate Hades with GPT-4 or GPT-3.5 for building custom applications, automation, or existing OpenAI-based workflows.

What you can do:

Custom application development
Programmatic API access
Integration with existing GPT workflows
Flexible model selection

Comparison: Which Integration to Use?

Feature	Claude Desktop	Claude CLI	Ollama	OpenAI
Ease of Setup	Easy	Easy	Medium	Medium
Cost	Subscription	Subscription	Free (local)	Pay-per-token
Privacy	Cloud	Cloud	Fully local	Cloud
Model Quality	Excellent	Excellent	Good (varies)	Excellent
Multi-tool Reasoning	Excellent	Excellent	Medium	Excellent
Speed	Fast	Fast	Varies (hardware)	Fast
Best For	Interactive investigations	Terminal workflows	Air-gapped/sensitive	Custom integrations