mcp-observability-server 0.1.1

A Model Context Protocol (MCP) server for querying logs from multiple observability platforms (New Relic, Azure)

MCP Observability Server

A Model Context Protocol (MCP) server that enables Claude to query logs from multiple observability platforms simultaneously. Perfect for SRE workflows, incident investigation, and distributed tracing.

Supported Platforms

• New Relic - Query logs using NRQL
• Azure Application Insights - Query logs using Kusto Query Language (KQL)

Features

• 🔍 Unified Search - Search across all platforms with a single query
• 🎯 Severity Filtering - Filter by log levels (debug, info, warning, error, critical)
• 🔗 Distributed Tracing - Find all logs related to a trace ID across platforms
• ⚡ Concurrent Queries - Queries all providers in parallel for fast results
• 📊 Recent Errors - Quick access to recent error logs across all systems
• 🏥 Health Checks - Verify connectivity to all configured providers
• 🤖 Guided Workflows - Pre-built prompts for incident investigation, deployment validation, and root cause analysis

Installation

From PyPI

pip install mcp-observability-server

From Source

git clone https://github.com/yourusername/mcp-observability-server.git
cd mcp-observability-server
pip install -e .

Configuration

1. Create Configuration File

Copy the example configuration:

cp config.yaml.example config.yaml

Edit config.yaml with your credentials:

providers:
  newrelic:
    enabled: true
    api_key: ${NEW_RELIC_API_KEY}
    account_id: "1234567"
    region: "US"
  
  azure:
    enabled: true
    workspace_id: ${AZURE_WORKSPACE_ID}
    client_id: ${AZURE_CLIENT_ID}
    client_secret: ${AZURE_CLIENT_SECRET}
    tenant_id: ${AZURE_TENANT_ID}

2. Set Environment Variables

Copy and configure environment variables:

cp .env.example .env

Edit .env with your actual credentials.

3. Configure Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "observability": {
      "command": "python",
      "args": ["-m", "mcp_observability.server", "/path/to/config.yaml"]
    }
  }
}

Usage

Once configured, you can ask Claude to query your logs:

Example Queries

Search for errors in the last hour:

Show me all errors from the last hour across all platforms

Search specific text:

Find logs containing "timeout" from the last 30 minutes

Filter by service:

Show me warning and error logs from the api-gateway service in the last 2 hours

Distributed tracing:

Find all logs related to trace ID abc123-def456

Recent errors:

What errors have occurred in the last 15 minutes?

Available Tools

The server exposes these tools to Claude:

query_logs

Search logs across all platforms with flexible filtering.

Parameters:

• start_time (required) - ISO format or relative (e.g., "1h", "30m", "2d")
• end_time (optional) - Defaults to now
• query (optional) - Text to search for
• severity (optional) - Array of severity levels
• service_name (optional) - Filter by service
• limit (optional) - Max results (default: 100)
• providers (optional) - Specific providers to query

get_recent_errors

Quick access to recent error and critical logs.

Parameters:

• minutes (optional) - Look back period (default: 60)
• limit (optional) - Max results per provider (default: 100)
• service_name (optional) - Filter by service

search_by_trace_id

Find all logs associated with a distributed trace.

Parameters:

• trace_id (required) - The trace ID to search for
• start_time (optional) - Defaults to 24 hours ago
• end_time (optional) - Defaults to now

health_check

Verify connectivity to all configured providers.

Guided Workflows (Prompts)

The server provides guided prompts for common SRE workflows. Prompts chain multiple tools together and provide structured analysis frameworks.

investigate-incident

Systematic incident investigation workflow.

Use for: Active production incidents requiring thorough investigation
Parameters:

• service_name (optional) - Service to investigate
• time_period (default: "1h") - Investigation time window
• severity_threshold (default: "error") - Minimum severity

Example:

Use the investigate-incident prompt for api-gateway service

Workflow: Recent errors → Pattern analysis → Trace investigation → Health checks → Summary with recommendations

health-check-report

Generate comprehensive health status report.

Use for: Daily health checks, system status overviews
Parameters:

• time_period (default: "24h") - Error statistics period
• include_metrics (default: true) - Include detailed metrics

Example:

Generate a health check report

Workflow: Provider health → Error analysis → Service catalog → Active traces → Recommendations

post-deployment-check

Validate deployment health by comparing before/after metrics.

Use for: Post-deployment validation, CI/CD pipelines
Parameters:

• service_name (required) - Deployed service name
• deployment_time (optional) - When deployment occurred
• lookback_minutes (default: 30) - Baseline comparison period

Example:

Run a post-deployment check for user-service

Workflow: Current errors → Baseline comparison → New error detection → Trace analysis → Health recommendation (PROCEED/MONITOR/ROLLBACK)

trace-flow-analysis

Analyze distributed trace execution flow and timing.

Use for: Debugging distributed systems, understanding request flow
Parameters:

• trace_id (required) - Trace ID to analyze
• include_timing (default: true) - Include timing breakdown

Example:

Analyze trace flow for abc123-def456

Workflow: Timeline construction → Service chain mapping → Timing analysis → Error detection → Bottleneck identification → Root cause

root-cause-analysis

Deep root cause investigation for complex failures.

Use for: Finding originating causes, cascading failure analysis
Parameters:

• trace_id (optional) - Specific trace to investigate
• error_pattern (optional) - Known error pattern
• time_window (default: "1h") - Investigation window

Example:

Perform root cause analysis for error "database connection timeout"

Workflow: Evidence gathering → Timeline building → Trace flow → Pattern recognition → Root cause formulation → Prevention recommendations

See Prompts README for detailed documentation.

Platform-Specific Configuration

New Relic

1. Create an API key in New Relic (User > API Keys)
2. Find your account ID in the URL or account dropdown
3. Choose region: "US" or "EU"

Azure Application Insights

1. Create a service principal in Azure AD
2. Grant "Log Analytics Reader" role to the service principal
3. Note the workspace ID, client ID, client secret, and tenant ID

Development

Setup Development Environment

# Clone repository
git clone https://github.com/yourusername/mcp-observability-server.git
cd mcp-observability-server

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src/
ruff check src/

Testing with MCP Inspector

Test the server interactively using the MCP Inspector:

npx @modelcontextprotocol/inspector \
  uv \
  --directory /home/gagan/mcp-observability-server \
  run \
  mcp-observability \
  /home/gagan/mcp-observability-server/config.yaml

Or using the Python module directly:

npx @modelcontextprotocol/inspector \
  uv \
  --directory /home/gagan/mcp-observability-server \
  run \
  python \
  -m \
  mcp_observability.server \
  /home/gagan/mcp-observability-server/config.yaml

Project Structure

mcp-observability-server/
├── src/
│   └── mcp_observability/
│       ├── __init__.py
│       ├── server.py           # Main MCP server
│       ├── models.py            # Data models
│       ├── utils.py             # Utilities
│       ├── prompts/             # Guided workflow prompts
│       │   ├── __init__.py
│       │   ├── incident.py      # Incident investigation prompts
│       │   ├── health.py        # Health monitoring prompts
│       │   ├── deployment.py    # Deployment validation prompts
│       │   ├── trace_analysis.py # Trace flow analysis prompts
│       │   └── README.md        # Prompts documentation
│       └── providers/
│           ├── base.py          # Abstract base
│           ├── newrelic.py
│           ├── azure.py
│           
│           
├── tests/
├── config.yaml.example
├── .env.example
└── pyproject.toml

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=mcp_observability

# Run specific test file
pytest tests/test_providers.py

Logging

The server includes comprehensive logging to help with debugging and monitoring:

Configure Log Level:

Set the MCP_LOG_LEVEL environment variable:

# In your .env file or environment
export MCP_LOG_LEVEL=DEBUG  # Options: DEBUG, INFO, WARNING, ERROR, CRITICAL

Log Levels:

• DEBUG - Detailed diagnostic information (queries, parameters, API calls)
• INFO - General informational messages (default)
• WARNING - Warning messages for potential issues
• ERROR - Error messages for failures
• CRITICAL - Critical issues that prevent operation

What Gets Logged:

• Server initialization and configuration loading
• Provider initialization and health checks
• Tool invocations with parameters
• Query execution and results
• API calls to observability platforms
• Errors and exceptions with stack traces

Example Log Output:

2026-02-13 10:30:15 - mcp_observability.server - INFO - Starting MCP Observability Server
2026-02-13 10:30:15 - mcp_observability.utils - INFO - Loading config from: config.yaml
2026-02-13 10:30:15 - mcp_observability.providers.newrelic - INFO - New Relic provider initialized for region: US
2026-02-13 10:30:20 - mcp_observability.server - INFO - Tool called: query_logs
2026-02-13 10:30:21 - mcp_observability.providers.newrelic - INFO - New Relic query returned 42 log(s)

Troubleshooting

Common Issues

"Provider unhealthy" in health check

• Verify credentials are correct in config.yaml
• Check environment variables are set
• Ensure network connectivity to provider API

"No logs found"

• Verify time range includes the period you're interested in
• Check that log groups/workspaces are configured correctly
• Ensure services are actually logging during the time period

AWS credentials error

• If using IAM role, ensure instance has correct permissions
• If using access keys, verify they're correct in .env
• Check AWS region matches where your logs are

Timeout errors

• Increase timeout_seconds in provider config
• Reduce limit to fetch fewer results
• Check network connectivity

Enable debug logging

• Set MCP_LOG_LEVEL=DEBUG in your environment or .env file
• Check logs for detailed query information and API responses
• Review stack traces for error details

Performance Tips

1. Specify log groups - specify exact log groups instead of querying all
2. Use time ranges wisely - Shorter time ranges return faster
3. Limit results - Start with smaller limits and increase if needed
4. Filter by service - Reduces data scanned across all platforms
5. Use recent_errors - Optimized query for error investigation

Security Best Practices

1. Never commit credentials - Use environment variables or secrets manager
2. Rotate keys regularly - Set up key rotation for all platforms
3. Principle of least privilege - Grant only read permissions needed
4. Audit access - Monitor who's using the MCP server
5. Secure config files - Restrict file permissions on config.yaml

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

• Issues: https://github.com/yourusername/mcp-observability-server/issues
• Discussions: https://github.com/yourusername/mcp-observability-server/discussions
• Documentation: https://docs.example.com/mcp-observability

Roadmap

• Support for more providers (Splunk, Elastic, Grafana Loki)
• Advanced query builders
• Log analytics and pattern detection
• Alerting integration
• Performance metrics collection
• Custom query templates
• Multi-account support per provider

Acknowledgments

Built with the Model Context Protocol by Anthropic.