JA4 MCP Server Resources

This document describes the MCP resources exposed by the JA4 Analysis Server, providing direct access to fingerprint databases and reference documentation.

Overview

The JA4 MCP Server exposes resources through two custom URI schemes:

• ja4-database:// - Access to fingerprint database collections
• ja4-docs:// - Reference documentation for JA4 standards

Database Resources

ja4-database://fingerprints

Complete JA4 Fingerprints Database

• Description: Complete database of known JA4 fingerprints with applications and OS information
• Format: JSON array of fingerprint records
• Use Case: Full database exploration, bulk analysis, research

ja4-database://applications

Applications with JA4 Fingerprints

• Description: Applications grouped with their associated JA4 fingerprints
• Format: JSON object with application names as keys, fingerprint arrays as values
• Use Case: Application-specific fingerprint analysis, software identification

ja4-database://operating-systems

OS Patterns in JA4 Database

• Description: Operating system patterns found in JA4 fingerprints
• Format: JSON object with OS names as keys, fingerprint arrays as values
• Use Case: OS fingerprinting, system identification

ja4-database://statistics

Database Statistics

• Description: Statistics about the JA4 fingerprints database
• Format: JSON object with counts and metadata
• Fields:
  • total_records: Total number of fingerprint records
  • ja4_count: Number of JA4 fingerprints
  • ja4s_count: Number of JA4S fingerprints
  • verified_count: Number of verified fingerprints
  • applications: Number of unique applications
  • operating_systems: Number of unique OS patterns

ja4-database://verified

Verified JA4 Fingerprints

• Description: Only verified JA4 fingerprints from the database
• Format: JSON array of verified fingerprint records
• Use Case: High-confidence analysis, validated patterns

Documentation Resources

ja4-docs://protocols

JA4 Protocol Codes Reference

• Description: Reference for JA4 protocol codes (t, q, d)
• Format: JSON object mapping codes to protocol information
• Codes:
  • t: TCP (Transmission Control Protocol)
  • q: QUIC (Quick UDP Internet Connections)
  • d: DTLS (Datagram Transport Layer Security)

ja4-docs://tls-versions

TLS Version Mappings

• Description: TLS version codes and their meanings in JA4 fingerprints
• Format: JSON object mapping version codes to TLS information
• Versions:
  • 10: TLS 1.0 (Deprecated)
  • 11: TLS 1.1 (Deprecated)
  • 12: TLS 1.2 (Secure)
  • 13: TLS 1.3 (Most Secure)

ja4-docs://tcp-options

TCP Options Documentation

• Description: Complete reference for TCP options used in JA4T fingerprints
• Format: JSON object mapping option numbers to TCP option information
• Common Options:
  • 0: End of Option List
  • 1: No Operation (NOP)
  • 2: Maximum Segment Size (MSS)
  • 3: Window Scale
  • 4: SACK Permitted
  • 8: Timestamp

ja4-docs://http-methods

HTTP Method Codes

• Description: HTTP method codes used in JA4H fingerprints
• Format: JSON object mapping codes to HTTP method information
• Methods:
  • ge: GET
  • po: POST
  • he: HEAD
  • pu: PUT
  • de: DELETE
  • op: OPTIONS
  • pa: PATCH

ja4-docs://alpn-protocols

ALPN Protocol Mappings

• Description: Application-Layer Protocol Negotiation codes and protocols
• Format: JSON object mapping codes to ALPN protocol information
• Protocols:
  • h1: HTTP/1.1
  • h2: HTTP/2
  • h3: HTTP/3
  • dt: DNS over TLS (DoT)
  • dq: DNS over QUIC (DoQ)

Resource Annotations

All resources include helpful annotations:

• audience: Indicates intended users (["user", "assistant"])
• priority: Importance level (0.0-1.0, where 1.0 is most important)
• lastModified: ISO 8601 timestamp (for database resources)

Usage Examples

Reading Database Statistics

const stats = await client.request({
  method: "resources/read",
  params: { uri: "ja4-database://statistics" }
});
console.log(JSON.parse(stats.contents[0].text));

Accessing Protocol Documentation

const protocols = await client.request({
  method: "resources/read", 
  params: { uri: "ja4-docs://protocols" }
});
console.log(JSON.parse(protocols.contents[0].text));

Exploring Applications Database

const apps = await client.request({
  method: "resources/read",
  params: { uri: "ja4-database://applications" }
});
const applications = JSON.parse(apps.contents[0].text);
console.log(`Found ${Object.keys(applications).length} applications`);

Error Handling

Resources may return errors for:

• Unknown resource schemes: Unknown resource scheme: invalid://
• Invalid resource types: Unknown database resource: invalid
• Database loading failures: Failed to read resource: <details>

Standard JSON-RPC error codes are used:

• -32002: Resource not found
• -32603: Internal server error

Performance Considerations

• Database resources are loaded on-demand and may take time for initial access
• Documentation resources are fast as they use static reference data
• Large database resources (like fingerprints) may be memory-intensive
• Consider using filtered resources (verified, applications) for targeted analysis

Integration with Tools

Resources complement the existing tools:

• Tools: For active analysis and processing
• Resources: For passive data access and reference

Use resources when you need:

• Raw data access without processing overhead
• Reference documentation for context
• Bulk data for custom analysis
• Database exploration and research