runtime-mcp

Drop-in MCP server that lets Claude inspect, debug, and hot-fix your running Bun process through conversation.

One line of code. Claude can now see inside your running Bun server — memory, queries, traffic, errors, everything.

import { attachMCP } from 'runtime-mcp';
attachMCP({ port: 3100 }); // that's it

Your Bun process now speaks MCP. Connect Claude Desktop, Cursor, or any MCP client and start asking questions about your live app.

Why

Debugging a running app today means adding logging, restarting, and hoping you guessed the right thing to log. LLMs can read your source code, but they can't see your runtime state — the variable values, the open connections, the slow queries, the memory growth.

runtime-mcp fixes that. It exposes your process internals as MCP resources and tools, so the LLM examines the live patient instead of guessing from the chart.

Related MCP server: claude-sessions-mcp

Quick Start

1. Install

bun add runtime-mcp

2. Attach to your server

import { serve } from 'bun';
import { attachMCP } from 'runtime-mcp';

const server = serve({
  port: 3000,
  fetch: () => new Response('Hello'),
});

attachMCP({
  port: 3100,
  bind: { server },
});

3. Connect Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "my-app": {
      "url": "http://localhost:3100/sse"
    }
  }
}

Restart Claude Desktop. Ask: "What is this process doing?"

What Claude Can See

Resources (read-only, always available)

Tools (actions Claude can take)

*Requires node:inspector — not yet available in Bun (tracking issue).

Prompts (guided debugging workflows)

Configuration

attachMCP({
  // Transport
  port: 3100,              // MCP server port (default: 3100)
  host: 'localhost',       // Bind address (default: 'localhost')

  // What to expose
  bind: {                  // Objects the LLM can inspect/eval against
    server,
    db,
    config,
  },

  // Access control
  readOnly: false,         // Disable eval, hot_patch, shell (default: true in production)
  allowedTools: undefined, // Whitelist specific tools
  blockedTools: undefined, // Blacklist specific tools

  // Observation tuning
  requestLog: {
    maxSize: 1000,         // Ring buffer size
    includeBodies: true,   // Capture req/res bodies (default: false in production)
  },
  sqlLog: {
    maxSize: 500,
    includeParams: true,   // Capture query params (default: false in production)
    slowThreshold: 500,    // Slow query threshold in ms
  },

  // Remote access (requires auth)
  auth: 'your-secret-token', // Required when host !== localhost
});

Production Defaults

When NODE_ENV=production, runtime-mcp automatically:

• Sets readOnly: true — disables eval, hot_patch, shell

• Hides request/response bodies

• Hides SQL query parameters

• All read-only inspection tools remain available

Binding Objects

Pass objects to bind to make them accessible to Claude:

import { serve } from 'bun';
import { SQL } from 'bun';
import { attachMCP } from 'runtime-mcp';

const db = new SQL('postgres://localhost/myapp');
const server = serve({ port: 3000, fetch: handleRequest });
const config = { featureFlags: { newCheckout: true }, rateLimit: 100 };

attachMCP({
  port: 3100,
  bind: { server, db, config },
});

runtime-mcp auto-detects:

• Bun.serve() servers — wraps the fetch handler to intercept HTTP traffic

• Bun.sql instances — wraps queries to capture SQL traffic

• WebSocket handlers — tracks connections and messages

Everything else is available through inspect and eval by name.

Security

• Binds to localhost only by default

• Non-localhost binding requires the auth option (Bearer token)

• Production mode disables code execution tools

• Shell tool blocks destructive commands (rm, kill, shutdown, etc.)

• Sensitive env vars are filtered from process info

This is a development tool. Treat the MCP port like a debugger port — don't expose it to the internet.

Requirements

• Bun >= 1.0.0

• An MCP client (Claude Desktop, Cursor, or any MCP-compatible tool)

How It Was Built

This project was built in a single session using Ralph, an autonomous AI agent loop. A PRD was written, converted to a task list, and Ralph implemented all 22 user stories sequentially — each one adding a resource, tool, or interceptor layer.

License

MIT