MCP Server

Model Context Protocol server for AI agent telemetry access

qyl MCP Server

The qyl MCP server enables AI agents to query and analyze telemetry data via the Model Context Protocol.

Installation

The MCP server is included in the qyl package:

# Install globally
dotnet tool install -g qyl.mcp

# Or run from source
dotnet run --project src/qyl.mcp

Configuration

Configure your AI tool to use the qyl MCP server:

Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "qyl": {
      "command": "qyl-mcp",
      "env": {
        "QYL_COLLECTOR_URL": "http://localhost:5100",
        "QYL_MCP_TOKEN": "your-token-here"
      }
    }
  }
}

VS Code

Add to .vscode/settings.json:

{
  "mcp.servers": {
    "qyl": {
      "command": "qyl-mcp",
      "env": {
        "QYL_COLLECTOR_URL": "http://localhost:5100"
      }
    }
  }
}

Authentication

Set QYL_MCP_TOKEN to match the collector’s QYL_TOKEN:

# Collector
export QYL_TOKEN=my-secret-token

# MCP Server
export QYL_MCP_TOKEN=my-secret-token

The MCP server sends the token via the x-mcp-api-key header (Aspire-compatible).

If no token is configured, auth is disabled (dev mode). Always set tokens in production.

Available Tools

Trace Tools

Tool	Description
qyl.get_trace	Get a complete distributed trace by ID
qyl.list_sessions	List all telemetry sessions
qyl.search_spans	Search spans with filters

Log Tools

Tool	Description
qyl.list_structured_logs	Query OTLP log records
qyl.list_trace_logs	Get all logs for a trace
qyl.search_logs	Search logs by pattern
qyl.list_console_logs	List frontend console messages
qyl.list_console_errors	Quick access to console errors

GenAI Tools

Tool	Description
qyl.get_genai_stats	Token usage, costs, latency summary
qyl.list_genai_spans	Query LLM calls with filters
qyl.list_models	Usage breakdown by AI model
qyl.get_token_timeseries	Token consumption over time

Storage Tools

Tool	Description
qyl.get_storage_stats	Database statistics
qyl.health_check	Collector health status

Replay Tools

Tool	Description
qyl.replay_trace	Replay a trace to see timing
qyl.export_trace	Export trace as JSON

Example Usage

Once configured, AI agents can query your telemetry:

User

What errors occurred in the last hour?

Aspire Parity

The qyl MCP server provides equivalent functionality to Aspire’s MCP tools:

Aspire Tool	qyl Equivalent
list_resources	qyl.list_sessions, qyl.health_check
list_console_logs	qyl.list_console_logs
list_structured_logs	qyl.list_structured_logs
list_traces	qyl.get_trace, qyl.list_sessions
list_trace_structured_logs	qyl.list_trace_logs
execute_resource_command	N/A (qyl is collector-only)

Environment Variables

Variable	Default	Description
QYL_COLLECTOR_URL	http://localhost:5100	Collector base URL
QYL_MCP_TOKEN	(none)	API key for authentication