Analyzer MCP documentation

HTTP-based Model Context Protocol server for network latency monitoring and intelligent analysis. The MCP server works by connecting to the already existing Latencetech API in order to communicate with the Analyzer database itself.

Features

Core Monitoring

• Query latency across latency protocols (TCP, UDP, HTTP, HTTPS, ICMP, TWAMP)
• Connectivity health analysis with comprehensive KPIs
• Radio signal quality monitoring (RSSI, RSRP, RSRQ, SINR)
• Predictive latency forecasting with confidence intervals
• Geolocation-correlated performance data
• System metrics monitoring (CPU, RAM, storage, load)
• Lifbe throughput and quality measurements

Intelligent Analysis

• Anomaly Detection: Detects network anomalies across protocols
• Performance Trends: Analyze agent performance trends vs historical baselines
• Degradation Alerts: Identify agents showing performance degradation
• Correlation Analysis: Detect patterns between agents indicating network-wide issues
• Health Reports: Generate comprehensive network health reports with recommendations
• Agent Rankings: Rank agents by performance metrics and trends

Download configuration file

Note: The MCP server is meant to be installed on the Analyzer VM.

You can download the configuration file here:

wget https://api.latence.ca/software/mcp-server.yml

Configuration

Environment Variables

Set values directly in mcp-server.yml:

environment:
  # REQUIRED: Replace with your API key
  - API_KEY=your-api-key-here

  # REQUIRED: Replace with a secure key that will be used for creating tokens
  - ADMIN_KEY=change-this-secure-admin-key

  # SERVER_HOST: Leave empty for auto-detect external IP, 
  # OR set to your VM's IP (e.g., 192.168.1.100)
  # OR set to your DNS (e.g., demo.example.com)
  - SERVER_HOST=

  # ENABLE_HTTPS: Set to 'false' ONLY when using a DNS address
  # Keep it to true if you will be using an IP address (default)
  - ENABLE_HTTPS=true

  # ENABLE_OAUTH: Set to 'false' to disable OAuth endpoints (Claude Web won't work)
  # Keep 'true' for Claude Web support (default: true)
  # Set 'false' for bearer tokens support only
  # If enabled, anyone with the MCP address can connect to it without verification
  - ENABLE_OAUTH=true

  # Optional
  - LOG_LEVEL=INFO
  - API_TIMEOUT=120
  - HTTP_PORT=12098
  - DEFAULT_CUSTOMER_ID=0
  - DEFAULT_AGENT_ID=1

Important Configuration Notes: - API_KEY: Required for backend API access - ADMIN_KEY: Required for creating/managing access tokens - HTTPS Configuration: - For Claude Desktop with IP: Set ENABLE_HTTPS=true for self-signed certificates - For Claude Web: You must use a domain with valid SSL (see SSL Setup below)

• ENABLE_OAUTH:
• ENABLE_OAUTH=true → All 5 OAuth endpoints registered, Claude Web can connect
• ENABLE_OAUTH=false → OAuth endpoints not registered, only bearer tokens work
• Token management endpoints (/admin/tokens/*) always work regardless of OAuth setting

Logs will show:

INFO: OAuth endpoints enabled
# or
INFO: OAuth endpoints disabled - bearer token only mode

Docker Deployment

# Edit mcp-server.yml
nano mcp-server.yml

# Run the container
docker compose -f mcp-server.yml up -d

SSL Setup for Claude Web

Claude Web requires a trusted SSL certificate and cannot use self-signed certificates.

Subdomain with Nginx + Let's Encrypt

1. Add DNS A record for a subdomain (e.g., mcp.yourdomain.com → your server IP)

2. Create nginx config (/etc/nginx/sites-available/mcp.yourdomain.com):

server {
    server_name mcp.yourdomain.com;

    location / {
        proxy_pass          http://localhost:12098;
        proxy_set_header    Host $http_host;
        proxy_set_header    X-Real-IP $remote_addr;
        proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header    X-Forwarded-Proto $scheme;
        proxy_read_timeout  90;

        # Support for long-lived connections
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    listen 80;
}

1. Enable site and get SSL certificate:

sudo ln -s /etc/nginx/sites-available/mcp.yourdomain.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d mcp.yourdomain.com

1. Update mcp-server.yml:

- ENABLE_HTTPS=false

1. Restart container:

docker compose -f mcp-server.yml down
docker compose -f mcp-server.yml up -d

MCP Client Integration

Claude Web (claude.ai)

Requirements: - Valid SSL certificate (self-signed certificates will NOT work) - Must use subdomain with Let's Encrypt or similar trusted CA - OAuth must be enabled (ENABLE_OAUTH=true)

Claude Web uses OAuth 2.1 authentication automatically:

1. Go to Claude Settings → Connectors
2. Click "Add custom connector"
3. Name: Latency Monitoring
4. Remote MCP server URL: https://mcp.yourdomain.com (must use trusted SSL)
5. Leave OAuth fields empty (server handles dynamic registration)
6. Click "Add" - Claude will automatically initiate OAuth flow
7. Approve the authorization (auto-approved by server, no real verification)
8. Connection established with generated access token

How it works: - Claude discovers OAuth endpoints via .well-known/oauth-authorization-server - Server auto-approves authorization and generates access token - Token automatically managed by Claude (no manual token handling needed) - Token expires after 30 days and can be refreshed

Claude Desktop

Claude Desktop can use self-signed certificates with a workaround.

Claude Desktop requires the mcp-remote proxy with bearer token:

1. Create an access token:

curl -k -X POST "https://localhost:12098/admin/tokens/create?name=claude-desktop" \
  -H "X-Admin-Key: your-admin-key-here"

Response:

{
  "token": "TOKEN-CREATED",
  "name": "claude-desktop"
}

1. Configure Claude Desktop:

For self-signed certificates (IP address):

{
  "mcpServers": {
    "latency-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your.vm.ip.address:12098",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "TOKEN-CREATED",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

For trusted SSL (subdomain with Let's Encrypt):

{
  "mcpServers": {
    "latency-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.yourdomain.com",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "TOKEN-CREATED"
      }
    }
  }
}

Security Note: NODE_TLS_REJECT_UNAUTHORIZED=0 disables SSL certificate validation and should only be used in development or trusted network environments. For production, use a subdomain with Let's Encrypt.

1. Restart Claude Desktop

Claude API (Messages API)

For programmatic access via Messages API:

import anthropic

client = anthropic.Anthropic(api_key="your-api-key")

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1000,
    messages=[{"role": "user", "content": "What agents are available?"}],
    mcp_servers=[{
        "type": "url",
        "url": "https://mcp.yourdomain.com",
        "name": "latency-mcp",
        "authorization_token": "TOKEN-CREATED"
    }]
)

Other MCP Clients

For any MCP client that supports bearer tokens:

1. Create a token (see token management section below)
2. Configure client to send Authorization: Bearer <token> header
3. Connect to your server URL

Token Management

Create Tokens

Create new access tokens for clients:

curl -k -X POST "https://localhost:12098/admin/tokens/create?name=my-client" \
  -H "X-Admin-Key: your-admin-key-here"

Response:

{
  "token": "xK9mP2nQ7vR4sT8wU1yZ5aB3cD6eF0gH",
  "name": "my-client"
}

Modify default expiry date

By default, the tokens expire after 720 hours (1 month), however you can change it using the expires_hours parameter:

curl -k -X POST "https://localhost:12098/admin/tokens/create?name=my-client&expires_hours=3600" \
  -H "X-Admin-Key: your-admin-key-here"

List Tokens

View all active tokens:

curl -k -X GET "https://localhost:12098/admin/tokens/list" \
  -H "X-Admin-Key: your-admin-key-here"

Response:

{
  "xK9mP2nQ7vR4sT8wU1yZ5aB3cD6eF0gH": {
    "name": "my-client",
    "expires_at": "2025-11-02T10:30:00"
  }
}

Revoke Tokens

Revoke a specific token:

curl -k -X DELETE "https://localhost:12098/admin/tokens/xK9mP2nQ7vR4sT8wU1yZ5aB3cD6eF0gH" \
  -H "X-Admin-Key: your-admin-key-here"

Token Details: - Tokens expire after 30 days (720 hours) by default - Expired tokens are automatically removed on validation - Tokens are stored in /app/data/tokens.json (persisted via Docker volume) - Each token is bound to a descriptive name for easy management

Security Notes

• Change ADMIN_KEY from the default value
• Keep your API_KEY secure
• The data/ folder contains authentication tokens - back it up!
• Set appropriate file permissions:

chmod 700 data/
chmod 600 data/tokens.json

• Never use NODE_TLS_REJECT_UNAUTHORIZED=0 in production environments
• For production deployments with Claude Web, always use trusted SSL certificates

Available Tools

Core Monitoring Tools

Tool	Description	Required Parameters
list_customer_networks	List all available customer networks	None
search_agents	Find agents for a customer	customer_id (defaults to 0)
query_latency	Query latency with time/protocol filters	customer_id, agent_id, protocol + (time_range OR chosen_time)
get_connectivity_health	Comprehensive connectivity analysis	customer_id, agent_id (both default to 0,1)
analyze_radio_conditions	Radio signal quality analysis	customer_id, agent_id + (time_range OR chosen_time)
get_system_metrics	System performance metrics	None
get_forecast	Predictive latency analysis	customer_id, agent_id (both default to 0,1)
get_geolocation_data	Location-correlated performance	customer_id, agent_id, time_range
get_lifbe_data	Lifbe throughput metrics	customer_id, agent_id (both default to 0,1)
get_twamp_data	TWAMP protocol measurements	customer_id, agent_id (both default to 0,1)

Intelligent Analysis Tools

Tool	Description	Required Parameters
get_anomalies	Detect network anomalies across protocols	customer_id, agent_id (defaults to 0,1)
analyze_performance_trends	Compare current vs baseline performance	customer_id, agent_id (defaults to 0,1)
get_degradation_alerts	Identify degrading agents	customer_id (defaults to 0)
detect_correlation_patterns	Find correlated performance issues	customer_id (defaults to 0)
generate_health_report	Comprehensive network health analysis	customer_id (defaults to 0)
rank_agents_by_performance	Rank agents by performance metrics	customer_id (defaults to 0)

API Endpoints

The MCP server exposes these HTTP endpoints:

• GET / - Server information
• GET /health - Health check
• POST /mcp/initialize - MCP initialization
• POST /mcp/resources/list - List resources
• POST /mcp/resources/read - Read resource content
• POST /mcp/tools/list - List available tools
• POST /mcp/tools/call - Execute tool

Troubleshooting

SSL Certificate Issues

Claude Web: - Error: "self-signed certificate" or connection failures - Solution: Claude Web requires trusted SSL certificates. Self-signed certificates will NOT work. You must set up a subdomain with Let's Encrypt (see SSL Setup section above)

Claude Desktop: - Error: "self-signed certificate" errors - Solution: Add NODE_TLS_REJECT_UNAUTHORIZED: "0" to the env section in your Claude Desktop config (see Claude Desktop configuration above) - Note: This is only for development/testing. For production, use trusted SSL certificates

Connection Issues

• Verify if the API key is correct
• Check if the LatencyTech API is accessible
• For Docker: use host.docker.internal instead of localhost, or use network_mode: "host" in mcp-server.yml
• Check firewall settings for port 12098
• For Claude Web: Ensure subdomain DNS is correctly configured and pointing to your server
• For nginx setups: Verify nginx is running and properly configured (sudo nginx -t)

Logging

• Set LOG_LEVEL=DEBUG for detailed request/response logging
• Check container logs: docker logs <container_id>
• Check nginx logs: sudo tail -f /var/log/nginx/error.log

Example & test queries

• "Get me a summary of the latency for agent 1."
• "Show me any network anomalies detected for agent 1,over the past hour. Focus on TCP protocol if there are any issues."
• "Which agents have connectivity health warnings?"
• "Generate a forecast for agent 2's expected latency"
• "Can you analyze the performance trends for agent 1 in customer 0 over the last 7 days? I want to see if there's been any degradation compared to the baseline."
• "Generate a comprehensive daily network health report for customer 0. Include actionable recommendations for any issues you find."