For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Guide
Description

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

Section
Description

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


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?