runtime-mcp-server
This server gives AI coding agents read-only, real-time runtime diagnostics for local development environments.
Inspect ports: Find which PID/process is occupying a local port (e.g., 3000, 8080) to resolve port conflicts.
Tail application logs: Read the most recent lines from a specified local log file to see stack traces and errors.
Get process metrics: View per-core CPU and memory usage of running processes to detect issues like infinite loops or memory leaks.
Diagnose runtime: Combine port, process, and log evidence into a deterministic health report with next steps.
Capture network errors: Inspect failed HTTP/gRPC responses, CORS headers, and status codes to debug local API connection issues.
Allows tailing stdout/stderr and crash logs from Docker-based dev servers so AI agents can inspect stack traces and runtime errors directly.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@runtime-mcp-server Check what process is using port 3000 and tail its logs."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Runtime Diagnostic MCP Server (runtime-mcp-server)
A local Model Context Protocol (MCP) server that provides AI coding agents (like OpenAI Codex CLI) with real-time runtime diagnostics, process monitoring, and log analysis for local development environments.
🎯 Purpose
AI coding agents are great at inspecting static code, but blind to runtime execution state. This server bridges that gap by giving AI agents programmatic, read-only tools to observe running processes, analyze crash logs, inspect active ports, and monitor system resources.
Related MCP server: DevTwin MCP
🛠️ Core Tools (v1 Features)
tail_app_logsDescription: Reads the most recent lines from an explicitly provided local application log file.
Goal: Hands recent stack traces and error output to Codex without manual copy-pasting.
inspect_portsDescription: Scans active local network ports (e.g., 3000, 8080) and identifies occupying process IDs (PIDs).
Goal: Automatically resolves
EADDRINUSE/ "Port already in use" errors and can safely signal zombie processes.
get_process_metricsDescription: Reports per-core CPU and memory usage for an already-running local process. A process using one fully utilized core reports approximately 100%; multi-threaded processes may exceed 100%.
Goal: Helps Codex detect infinite loops, memory leaks, and runaway background scripts in real time.
diagnose_runtimeDescription: Combines port, process, and log evidence into a single deterministic runtime diagnosis.
Goal: Gives Codex a concise health report and evidence-backed next steps for a local application.
capture_network_errorsDescription: Inspects local failed HTTP/gRPC responses, CORS headers, and status codes.
Goal: Pinpoints root causes for broken frontend-to-backend local API connections.
🏗️ Technical Stack
Language: TypeScript / Node.js
Protocol: Model Context Protocol (MCP) via
@modelcontextprotocol/sdkTransport: Standard Input/Output (
stdio)System APIs:
child_process,fs/promises,psutil/ system process utilities
🚀 Getting Started
Install dependencies and compile the TypeScript source:
npm install
npm run buildRun the automated process-metrics tests:
npm testStart the MCP server:
npm startThe server connects over stdio and currently provides port inspection, explicit log-file reading, live process metrics, and a combined runtime diagnosis tool.
Start the optional local dashboard:
npm run dashboardOpen the printed http://127.0.0.1:3847 URL to add one or more local application targets. The dashboard is read-only, polls each configured port every five seconds, and stores target settings in the browser only. It runs separately from the MCP server and is not started automatically by Codex.
🚀 Codex CLI Integration
Configured in ~/.codex/config.json (or Codex client settings):
{
"mcpServers": {
"runtime-diagnostics": {
"command": "node",
"args": ["/Users/USERNAME/Documents/Codex/runtime-mcp-server/build/index.js"]
}
}
}📋 Development Roadmap
Initialize TypeScript &
@modelcontextprotocol/sdkprojectImplement
inspect_portstoolImplement
tail_app_logstoolImplement
get_process_metricstoolImplement
diagnose_runtimetoolAdd integration tests with Codex CLI
Available Tools
1 toolinspect_portsA
Inspects active local network ports to determine which process ID (PID) and application are occupying a port.
Inputs: port.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
With only one tool available, there is no possibility of confusing it with other tools. The tool's purpose is clearly defined and stands alone.
The single tool name follows a clear verb_noun pattern. Since there is only one tool, there are no inconsistencies or competing naming conventions to evaluate.
The server is named 'runtime-mcp-server,' suggesting broad runtime management capabilities, but it exposes only a single port inspection tool. This feels severely undersized for the stated scope.
The tool surface is limited to inspecting ports, with no support for managing processes, terminating processes, or interacting with runtime state in any other meaningful way. The server's purpose appears very narrow, leaving significant gaps for any real runtime management workflow.
Maintenance
Related MCP Connectors
Deploy local apps, add managed Postgres, and inspect logs from your AI coding agent.
Errors, logs and AI-call costs for apps on Node.js, Next.js, Cloudflare Workers or the browser. Ask your AI what’s broken, why, and how to fix it, right inside Cursor or Claude.
Your team's shipping standards, org map and delivery metrics, inside your coding agent.
Open-source agent that observes and fixes your application. Query logs, traces, metrics, incidents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables LLM clients to inspect local dev environments—Docker container health, pnpm workspace integrity, and stuck process detection—without manual terminal copy-pasting.MIT
- AlicenseAqualityBmaintenanceProvides AI coding agents with structured, evidence-based diagnostics about the local development environment, detecting tech stack, runtime mismatches, dependency state, services, ports, and Git status without exposing secrets or using network calls.10Apache 2.0
- AlicenseNot gradedqualityDmaintenanceExposes a live application's runtime state to coding agents, including logs, DB schema, config, and feature flags, with read-only SQL and secret redaction.MIT
- AlicenseNot gradedqualityCmaintenanceEnables coding agents to access live runtime observability data such as logs, deploys, and health metrics for evidence-based incident triage.1MIT