> For the complete documentation index, see [llms.txt](https://boxlang.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boxlang.ortusbooks.com/boxlang-framework/observability/ai-and-mcp.md).

# AI and MCP Observability

Observability for AI in both directions: watch the agents you build with BoxLang AI, and let AI agents watch your BoxLang runtime through BxMCP.

AI observability has two sides, and BoxLang covers both:

1. **Watching the AI you build.** What do my agents, models and tools do, and what do they cost?
2. **AI watching your runtime.** Can an AI assistant inspect a live BoxLang server and help with an incident?

|                      | Watching your agents                                      | AI watching BoxLang                                          |
| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------ |
| **Tool**             | BxLens AI page and BoxLang AI middleware                  | [BxMCP](https://boxlang.ortusbooks.com/boxlang-ai/bx-mcp.md) |
| **Who looks**        | You, in the BxLens console                                | An AI client, over MCP                                       |
| **What it is about** | The agents, models and MCP servers you build with `bx-ai` | The BoxLang runtime itself                                   |
| **License**          | BoxLang+ for the full page                                | Free, needs `bx-ai`                                          |

## 🤖 Watching the agents you build

### BxLens AI observability

The **AI** page of the BxLens console shows what the agents, models and MCP servers of `bx-ai` are doing on a server. It listens to the events of BoxLang AI, so there is no code change.

* **Runs and traces.** Open any run to see its model calls, tool calls and MCP calls, step by step. Filter by failed, slow or delegated.
* **Cost.** Tokens and an estimated cost for each agent and model, from a price table that you add.
* **Agent composition.** A diagram of how an agent is made: model, instructions, memory, skills, tools, sub-agents and middleware, each with how it performs.
* **MCP servers you host.** Requests, tool calls, failures, rejected callers and rate limits.
* **What needs attention.** Failed runs and rate limit hits are flagged.

{% hint style="info" %}
The AI page is off until an admin turns it on. The full page is a BoxLang+ feature. Without a license it shows a few counters for the last hour. Cost is an estimate from your own price table.
{% endhint %}

<figure><img src="https://1598982152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4ENvvb4b3Cmrr1qKj7y4%2Fuploads%2Fgit-blob-43b4846673fca8bfef41f6105331ae4ccc00c1b3%2Fbxlens-console-aiobs-overview.png?alt=media" alt="The BxLens AI overview with runs, success, tokens, cost and the top agents"><figcaption><p>The AI overview: runs, success, run time, tokens and cost</p></figcaption></figure>

<figure><img src="https://1598982152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4ENvvb4b3Cmrr1qKj7y4%2Fuploads%2Fgit-blob-7ae138191caad3c895bc10327fc0f9838ab883ab%2Fbxlens-console-aiobs-run.png?alt=media" alt="The trace of one agent run"><figcaption><p>The trace of one run, step by step</p></figcaption></figure>

### BoxLang AI middleware

When you build an agent, BoxLang AI includes middleware for an audit trail: `LoggingMiddleware` and `FlightRecorderMiddleware`. See [Governance and security](https://boxlang.ortusbooks.com/boxlang-ai/boxlang-ai/governance-and-security.md) in the BoxLang AI section.

## 🛰️ AI watching your runtime

[BxMCP](https://boxlang.ortusbooks.com/boxlang-ai/bx-mcp.md) (`bx-mcp`) is a Model Context Protocol server for BoxLang. It lets an MCP capable client, such as an AI coding assistant or a monitoring tool, inspect and operate a live runtime over HTTP.

| Area                  | What the client can ask                                              |
| --------------------- | -------------------------------------------------------------------- |
| Runtime introspection | BoxLang version, configuration, BIFs, components and services        |
| JVM diagnostics       | Memory, threads, CPU, garbage collection, hot threads and deadlocks  |
| Data layer            | Cache analytics, datasource pool metrics and slow SQL                |
| HTTP and web          | Outgoing call statistics, slow requests and per-route metrics        |
| Operations            | Executors, schedulers, modules, logging and file watchers            |
| Health reports        | One snapshot across all subsystems, with scoring and recommendations |
| Incident response     | Triage, error spike and post-incident review workflows               |

Access is controlled per token, with tool filtering, IP allowlisting and a tool allow list or block list.

{% hint style="info" %}
BxMCP is free of charge but proprietary, and it requires the `bx-ai` module. No BoxLang+ subscription is required.
{% endhint %}

{% content-ref url="/pages/MudccuVelzOchW8RSv91" %}
[Operations & Monitoring](https://boxlang.ortusbooks.com/boxlang-framework/modularity/operations-and-monitoring.md)
{% endcontent-ref %}

{% content-ref url="/pages/8H2tbJGs0Ez72vYL8xi2" %}
[Incident Response](https://boxlang.ortusbooks.com/boxlang-framework/modularity/incident-response.md)
{% endcontent-ref %}

{% content-ref url="/pages/LJdWwbmfqKvY4QNC7jUZ" %}
[Security & Access Control](https://boxlang.ortusbooks.com/boxlang-framework/modularity/security-and-access-control.md)
{% endcontent-ref %}

## 🤝 Use them together

An AI assistant that reads your runtime through BxMCP is itself an agent. If it runs on `bx-ai`, you can watch it on the BxLens AI page: its runs, its tool calls, its cost and the MCP server it calls. One tool shows what the assistant sees, and the other shows what the assistant does.

## 🔗 Related

{% content-ref url="/pages/GmTVD7UDbULZYHM7e1OO" %}
[Overview](https://boxlang.ortusbooks.com/boxlang-ai/boxlang-ai.md)
{% endcontent-ref %}

{% content-ref url="/pages/4fV8qkgwsS5WhJjrKob2" %}
[MCP](https://boxlang.ortusbooks.com/boxlang-ai/boxlang-ai/mcp.md)
{% endcontent-ref %}

{% content-ref url="/pages/EzEcU6oifVQJccVAX4AM" %}
[BxLens](https://boxlang.ortusbooks.com/boxlang-framework/observability/bxlens.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://boxlang.ortusbooks.com/boxlang-framework/observability/ai-and-mcp.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
