BxMCP
Model Context Protocol server module for BoxLang runtime diagnostics, introspection, and operational automation.
The bx-mcp module exposes a production-ready Model Context Protocol (MCP) server for BoxLang, enabling MCP-capable clients — AI coding assistants, IDE agents, monitoring tools, and automation pipelines — to inspect and operate a live BoxLang runtime over HTTP.
When enabled, the module auto-registers a boxlang MCP server and exposes an HTTP endpoint at /~bxmcp/boxlang.bxm. Clients communicate via JSON-RPC 2.0 to list and invoke tools, retrieve prompts, and read resources.
✨ Features
🔍 Runtime Introspection — Query BoxLang version, configuration, BIFs, components, and global services
💻 JVM Diagnostics — Memory, threads, CPU, GC, hot threads, deadlock detection, heap dumps, disk and file descriptor usage
🗄️ Data Layer — Cache analytics, datasource pool metrics, slow SQL capture, connection pool latency histograms
🌐 HTTP & Web — HTTP/SOAP client stats, slow outbound call capture, slow request analysis, per-route metrics, Undertow server diagnostics
⚡ Operations — Async executor monitoring, scheduler management, module lifecycle, interceptor registry audit, application lifecycle, logging, file watchers
🏥 Structured Health Reports — Unified health snapshots across all subsystems with scoring, issue codes, and actionable recommendations
🚨 Incident Response — Pre-built triage, error spike, cascade failure, rollback decision, and post-incident review workflows
🔧 Extensible — Register custom MCP tools and prompts from your own modules and applications at runtime
🎮 Interactive CLI — Built-in shell client with tab completion, watch mode, and formatted output
🔒 Access Control — Per-token tool filtering with glob patterns, IP allowlisting, CORS support, and tool whitelist/blacklist
📦 Installation
Via CommandBox
Via BoxLang OS Binary
🚀 Quick Start
After installation, the MCP server is available at http://localhost:8080/~bxmcp/boxlang.bxm. Here's a 3-step check that everything is working:
1. List available tools:
2. Get BoxLang runtime information:
3. Check cache health:
See the Quick Start guide for detailed setup including VS Code, Claude Desktop, and Cursor client configurations.
📖 Documentation Sections
Usage Guides
Install, configure, and connect your first MCP client
Auth tokens, per-token tool filters, IP allowlisting, CORS
VS Code, Claude Desktop, Cursor, and generic curl setup
Health checks, performance snapshots, JVM monitoring, scheduler oversight
Cache analysis, datasource health, slow SQL/HTTP diagnosis
Triage workflows, error spikes, cascade failures, post-mortems
Register custom tools and prompts at runtime
Reference
Complete tool catalog organized by domain (153 tools)
Pre-built diagnostic and administrative prompts (32 prompts)
JSON-RPC 2.0 endpoint, methods, and request/response envelopes
Health report schema, scoring model, and issue code catalog
Complete settings reference and authentication deep-dive
🔌 Client Connection
Configure your MCP client to connect to the BoxLang endpoint:
See Client Configuration for platform-specific setup (VS Code, Claude Desktop, Cursor) and Security & Access Control for authentication options.
🎮 Interactive CLI
The module ships with a built-in interactive CLI client. Launch it from the BoxLang CLI:
Once connected, use commands like tools, prompts, run <tool>, and watch <tool> to interact with any MCP server.
📋 Requirements
BoxLang 1.12+
bx-ai module
Free to use under the proprietary license included with the module; no BoxLang+ subscription is required
🔗 Related Documentation
🔭 Related
BxMCP is one of the BoxLang observability tools. See Observability for how it fits with BxLens, and AI and MCP observability for watching AI agents and for letting AI agents watch the runtime.
Last updated
Was this helpful?
