railway-monitor

name	railway-monitor
description	Monitor Railway projects, diagnose deployment failures, and audit infrastructure using read-only MCP tools
version	1.0.0
author	kai-agent
metadata	{"kai":{"tags":["kai","railway","monitoring","deployments","infrastructure"],"related_skills":["aws-performance","aws-cost-optimizer"]}}

Railway Monitor

Monitor, diagnose, and audit Railway infrastructure. All operations are read-only — no deploys, restarts, or config changes.

Prerequisites

• RAILWAY_API_TOKEN set in kai-backend env
• MCP tools available: mcp__kai__railway_*

Workflow 1: Project Overview

Get a full picture of what's running.

1. List all projects:

   railway_list_projects(workspaceId)
   

2. For each project, get details:

   railway_project_detail(workspaceId, projectId="...")
   

   Returns: services, environments, volumes

3. Present as:

   Project	Services	Environments	Volumes

Workflow 2: Deployment Health Check

Check if everything is running correctly.

1. Quick health overview (best starting point):

   railway_project_health(workspaceId, projectId="...")
   

   Returns every service × environment with latest deployment status.

2. Or per-environment:

   railway_deployment_status(workspaceId, projectId="...", environmentId="...")
   

   Shows all services in that environment.

3. Flag issues:

   • Status FAILED or CRASHED → immediate attention
   • Status BUILDING for >10 minutes → possibly stuck
   • No deployment at all → service not deployed

Workflow 3: Troubleshoot Failed Deployment

When a service is down, follow this sequence:

1. Check latest deployment:

   railway_latest_deployment(workspaceId, projectId, environmentId, serviceId)
   

   Note the status and deploymentId.

2. If build failed — read build logs:

   railway_build_logs(workspaceId, deploymentId="...", limit=200)
   

   Look for: dependency install errors, compile errors, Dockerfile issues.

3. If build succeeded but runtime crashed — read runtime logs:

   railway_deployment_logs(workspaceId, deploymentId="...", limit=200)
   

   Look for: uncaught exceptions, OOM kills, port binding failures, missing env vars.

4. Check HTTP errors:

   railway_http_logs(workspaceId, deploymentId="...", limit=100)
   

   Look for: 5xx status codes, high response times (>5s), patterns in failing paths.

5. Check environment variables:

   railway_list_variables(workspaceId, projectId, environmentId, serviceId)
   

   Verify expected vars exist (DATABASE_URL, REDIS_URL, API_KEY, etc.).

6. Check variable references:

   railway_variable_references(workspaceId, projectId, environmentId, serviceId)
   

   Verify ${{...}} references resolve to actual services.

Workflow 4: Domain & DNS Audit

1. List all domains:

   railway_list_domains(workspaceId, projectId, environmentId, serviceId)
   

2. Check for issues:

   • certificateStatus != "VALID" → SSL cert problem
   • DNS records with status != "OK" → DNS not configured
   • Missing expected domains → not set up yet

Workflow 5: Volume Health

1. List volumes:

   railway_list_volumes(workspaceId, projectId)
   

2. Check each volume:

   railway_volume_detail(workspaceId, volumeInstanceId="...")
   

   • Flag state != "READY"
   • Flag currentSizeMB approaching storage limit

3. Verify backups exist:

   railway_volume_backups(workspaceId, volumeInstanceId="...")
   

   • Flag volumes with no recent backups

Workflow 6: Variable Audit

Verify all services have the expected environment variables.

1. For each service in the production environment:

   railway_list_variables(workspaceId, projectId, environmentId, serviceId)
   

2. Common expected variables:

   • Web services: PORT, NODE_ENV, DATABASE_URL
   • APIs: API_KEY, JWT_SECRET, CORS_ORIGIN
   • Workers: REDIS_URL, QUEUE_NAME
   • All: LOG_LEVEL

3. Check references make sense:

   railway_variable_references(workspaceId, projectId, environmentId, serviceId)
   

   • Verify ${{Postgres.DATABASE_URL}} style refs point to real services
   • Flag dangling references to deleted services

Workflow 7: Deployment History

Useful for understanding recent changes.

railway_list_deployments(workspaceId, projectId, environmentId, serviceId, limit=20)

• Look at deployment frequency — too many in short time = instability
• Look for FAILED → SUCCESS → FAILED patterns = flaky deploys
• Note timestamps for correlation with incidents

Reporting Format

Railway Infrastructure Report

Project: {name} Status: Healthy / Warning / Critical

Service	Environment	Deploy Status	Last Deploy	Issue
api	production	SUCCESS	2h ago	-
worker	production	CRASHED	30m ago	OOM in logs
web	staging	BUILDING	15m ago	Possibly stuck

Issues Found:

1. ...

Variable Audit:

• Missing: REDIS_URL on worker service
• Dangling ref: ${{OldDb.URL}} (service deleted)

Recommendations:

1. ...