Observability

You are about to deploy Observability MCP Server, a FastMCP 2.14.1–based observability platform that collects metrics, traces, and health data across MCP servers. It provides real-time monitoring, historical storage, and actionable insights to keep your MCP ecosystem performing reliably.

How to use

Start by running the Observability MCP Server alongside your MCP ecosystem to begin collecting metrics and traces. You can operate it from the command line or via your MCP client configuration.

• Initiate the server to begin gathering OpenTelemetry metrics and traces. You can use the CLI or run it as a Python module. Check health status to confirm connectivity with your MCP servers and verify that metrics and traces appear in your dashboards.

• Inspect real-time health and performance metrics to monitor MCP availability, response times, CPU, memory, disk, and network usage. Use the provided endpoints and export options to feed Prometheus, OpenTelemetry, or JSON consumers.

• Leverage automated alerts for anomalies and generate performance reports to guide optimization efforts. Export data in multiple formats for integrations with your existing observability stack.

• Integrate with Grafana by adding Prometheus as a data source and importing the dashboard to visualize the health and performance of your MCP ecosystem.

How to install

Prerequisites you need before installation.

• Python 3.11+
• FastMCP 2.14.1+ (automatically installed)

Install from source and run locally.

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

If you prefer running with Docker, build the image and start a container exposing the metrics port.

docker build -t observability-mcp .
docker run -p 9090:9090 observability-mcp

Start the server using the CLI or as a Python module.

# Using the CLI
observability-mcp run

# Or directly with Python
python -m observability_mcp.server

Configure your MCP client to launch the server command via MCP configuration.

"mcpServers": {
  "observability": {
    "command": "observability-mcp",
    "args": ["run"]
  }
}

Configuration and runtime notes

Environment variables control ports, service naming, OTLP endpoints, and data retention.

PROMETHEUS_PORT=9090
OTEL_SERVICE_NAME=observability-mcp
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
METRICS_RETENTION_DAYS=30

Alerts are preconfigured for common issues and can be customized through the MCP tooling.

Troubleshooting

If the server fails to start, verify the Python version and FastMCP installation, then check dependencies.

python --version  # should be 3.11+
pip show fastmcp    # should be 2.14.1+
pip check

If metrics do not appear, confirm the Prometheus endpoint is reachable and that OpenTelemetry is configured.

curl http://localhost:9090/metrics
observability-mcp metrics

Monitor memory usage and retention settings to avoid excessive resource consumption, and adjust METRICS_RETENTION_DAYS as needed.

Examples and usage notes

Health checks, performance metrics, tracing, and export endpoints can be used to build comprehensive observability dashboards. Use the provided tools to monitor health, analyze performance, detect anomalies, and export data for external analysis.

Development and contribution notes

Development workflow follows standard Python project practices. Install development dependencies, run tests, and ensure type hints and documentation are maintained.

Available tools

monitor_server_health

Real-time health checks with OpenTelemetry metrics to verify MCP server availability and response quality

monitor_system_resources

System-wide resource monitoring for CPU, memory, disk, and network usage

collect_performance_metrics

Collect CPU, memory, disk, and network metrics across MCP servers to feed dashboards and analyzes

generate_performance_reports

Automated performance analysis with recommendations for optimization and capacity planning

analyze_mcp_interactions

Usage pattern analysis to reveal how MCP servers are utilized and interconnected

alert_on_anomalies

Intelligent anomaly detection and alert generation for unusual operating conditions

trace_mcp_calls

Distributed tracing across MCP server interactions to diagnose end-to-end flow

export_metrics

Export metrics in Prometheus, OpenTelemetry, or JSON formats for external tooling