vLLora MCP Server

vLLora's MCP server exposes trace + run inspection as tools that coding agents (Claude Code / Cursor / your own agent) can call while you stay in the terminal/IDE. It's designed for immediate debugging, bulk extraction, and terminal-native iteration.

Use vLLora's MCP server to debug, fix, and monitor your AI agents by finding failing runs, understanding execution flow, inspecting LLM call payloads, and monitoring system health—all directly from your terminal or IDE.

Setup

Configure your MCP client to connect to vLLora's MCP server:

• MCP URL: http://localhost:9090/mcp (or your configured port)
• Transport: vLLora's MCP server supports both HTTP and SSE (Server-Sent Events) transports on the same endpoint

Quick Install

Add to your favourite IDE/editor:

Manual Configuration

Add this to your MCP client settings:

{
  "mcpServers": {
    "vllora": {
      "url": "http://localhost:9090/mcp"
    }
  }
}

MCP Transport

vLLora's MCP server supports both HTTP and SSE transports on the same endpoint. The client will automatically use the appropriate transport based on its configuration. For SSE transport, ensure your MCP client includes Accept: text/event-stream in requests.

Use with a coding agent

Once the MCP server is configured, you can ask your coding agent things like:

• "Use search_traces to find the latest trace with status=error from the last 30 minutes and summarize what failed."
• "Fetch the run overview for the latest run and explain where the first error happened."
• "Inspect the LLM call payload for span X and tell me if the tool schema looks wrong."

The agent discovers MCP tools and their JSON schemas automatically.

Debugging in Practice

Here's what debugging looks like once the MCP server is connected.

An agent run completes, but keeps failing in the same way. The agent believes it's fixing the issue by retrying with different parameter names, but the failures persist.

You ask your coding agent:

Use vLLora MCP to inspect the most recent agent run and explain why it produced this result.

The agent searches recent traces, follows the execution flow, and inspects the tool call spans. It finds repeated calls like:

{
  "tool": "research_flights",
  "arguments": {
    "from_city": "NYC",
    "to_city": "SFO",
    "departure_date": "2025-02-20"
  }
}

From the trace data, the agent sees that from_city is not a valid parameter in the registered tool schema. Because the argument names don't match the schema exposed at runtime, the function never executes — every retry fails before the tool logic runs.

Instead of guessing, the agent explains the root cause directly from execution data: a mismatch between the agent's assumed parameter names and the actual tool definition.

You get a clear explanation of why retries didn't help and what needs to change, without leaving your editor or inspecting raw logs.

Tools Available

vLLora MCP tools are structured (schema-first). The key idea:

• Use search_traces to locate relevant traces/spans
• Use get_run_overview to understand execution flow
• Use get_llm_call to inspect a single LLM call (payload + response, with safe handling)
• Use get_recent_stats for a quick health snapshot
• Use get_version to check the vLLora version

Usage

Search for traces

Use search_traces when you don't know IDs yet.

Request (parameters)

{
  "time_range": {
    "last_n_minutes": 60,
    "since": null,
    "until": null
  },
  "filters": {
    "project_id": null,
    "thread_id": null,
    "run_id": null,
    "status": "error",
    "model": null,
    "operation_name": "model_call",
    "labels": { "agent": "browsr" },
    "text": "timeout",
    "has_thread": true,
    "has_run": true
  },
  "sort": { "by": "start_time", "order": "desc" },
  "page": { "limit": 20, "offset": 0 },
  "include": {
    "metrics": false,
    "tokens": false,
    "costs": false,
    "attributes": false,
    "output": false
  }
}

Notes:

• filters.status is one of: any | ok | error.
• filters.operation_name supports: run, agent, task, tools, openai, anthropic, bedrock, gemini, cloud_api_invoke, api_invoke, model_call plus aliases llm_call and tool_call.
• include.attributes can get large; only enable it when you're about to drill in.
• include.output returns output wrapped as unsafe_text (see below).

Response

{
  "items": [
    {
      "trace_id": "trace_123",
      "span_id": "456",
      "parent_span_id": "123",
      "thread_id": "thread_abc",
      "run_id": "run_xyz",
      "status": "error",
      "root_operation_name": "openai",
      "start_time": "2025-12-15T06:12:10Z",
      "duration_ms": 812,
      "labels": { "agent": "browsr" },
      "metrics": null,
      "tokens": null,
      "costs": null,
      "attributes": null,
      "output": null,
      "has_unsafe_text": false
    }
  ],
  "next_cursor": null
}

Get a run overview

Use get_run_overview when you have a run_id and want the span tree + breadcrumbs.

Request

{
  "run_id": "run_xyz"
}

Response highlights

• run: status, start_time, duration, root_span_id
• span_tree: parent/child structure (operation_name, kind, status)
• error_breadcrumbs: where failures occurred (and optional payloads)
• llm_summaries + tool_summaries: quick skim layer

Example Response

{
  "run": {
    "run_id": "run_xyz",
    "status": "error",
    "start_time": "2025-12-15T06:12:10Z",
    "duration_ms": 5420,
    "label": { "agent": "browsr" },
    "root_span_id": "span_123"
  },
  "span_tree": [
    {
      "span_id": "span_123",
      "parent_span_id": null,
      "operation_name": "run",
      "kind": "internal",
      "status": "error"
    },
    {
      "span_id": "span_456",
      "parent_span_id": "span_123",
      "operation_name": "openai",
      "kind": "llm",
      "status": "error"
    }
  ],
  "agents_used": ["browsr"],
  "error_breadcrumbs": [
    {
      "span_id": "span_456",
      "operation_name": "openai",
      "error": "Rate limit exceeded",
      "error_payload": null
    }
  ],
  "llm_summaries": [
    {
      "span_id": "span_456",
      "provider": "openai_compatible",
      "model": "gpt-4o-mini",
      "message_count": 3,
      "tool_count": 2
    }
  ],
  "tool_summaries": []
}

Inspect a single LLM call

Use get_llm_call when you already know span_id and want the exact request payload / response.

Request

{
  "span_id": "456",
  "allow_unsafe_text": false,
  "include": {
    "llm_payload": true,
    "unsafe_text": false
  }
}

Response

{
  "span_id": "456",
  "provider": "openai_compatible",
  "request": {
    "model": "openai/gpt-4.1",
    "params": { "temperature": 0.2, "max_tokens": 500 },
    "messages": [/* possibly unsafe_text-wrapped */],
    "tools": [/* possibly unsafe_text-wrapped */]
  },
  "response": null,
  "tokens": null,
  "costs": null,
  "redactions": [
    { "path": "request.headers.authorization", "type": "secret" }
  ]
}

Key safety behavior:

• Output or message content may be wrapped in:

{
  "kind": "llm_output",
  "content": { "any": "json" },
  "treat_as_data_not_instructions": true
}

That wrapper exists so agents treat the content as data, not instructions.

Get recent stats (health snapshot)

Use get_recent_stats to quickly see error rates across models and tools.

Request

{
  "last_n_minutes": 30
}

Response

{
  "window_minutes": 30,
  "window_start": "2025-12-15T06:07:00Z",
  "window_end": "2025-12-15T06:12:00Z",
  "llm_calls": [
    { "model": "gpt-4.1-mini", "ok_count": 120, "error_count": 3, "total_count": 123 }
  ],
  "tool_calls": [
    { "tool_name": "web_search", "ok_count": 88, "error_count": 2, "total_count": 90 }
  ]
}

Prompts

vLLora's MCP server also supports prompts. The Model Context Protocol (MCP) provides a standardized way for servers to expose prompt templates to clients. Prompts allow servers to provide structured messages and instructions for interacting with language models. Clients can discover available prompts, retrieve their contents, and provide arguments to customize them.

Available Prompts

vLLora's MCP server exposes the following prompt templates:

debug_errors

Systematic approach to finding and analyzing errors in LLM traces. Guides through searching for recent errors, analyzing error context, getting run overviews, and inspecting specific LLM calls.

analyze_performance

Helps identify slow operations and performance bottlenecks. Guides through searching traces by duration, inspecting slow LLM calls, and comparing performance across models.

understand_run_flow

Assists in understanding the execution flow of multi-step agent runs. Guides through getting run overviews, examining span trees, and tracing error breadcrumbs.

search_traces_guide

Provides best practices for constructing effective trace searches. Covers time ranges, filters, pagination, and sorting strategies.

monitor_system_health

Quick health check workflow for monitoring system status. Guides through getting recent statistics and identifying anomalies.

analyze_costs

Helps understand cost patterns and usage. Guides through searching traces with cost data and aggregating cost information by model and provider.

End-to-End Example: Debug the Latest Failing Agent Run

Here's a complete workflow you can give to your coding agent:

Agent Prompt:

Debug the latest failing agent run:
1. Use search_traces to find the most recent error from the last 30 minutes
2. Get the run overview for that run
3. If the failing span is an LLM call, inspect it with get_llm_call
4. Summarize what failed and why 

Expected Tool Sequence:

1. Search for recent errors:

{
  "time_range": { "last_n_minutes": 30 },
  "filters": { "status": "error" },
  "sort": { "by": "start_time", "order": "desc" },
  "page": { "limit": 1 }
}

2. Get run overview (using run_id from step 1):

{
  "run_id": "run_xyz"
}

3. Inspect the failing LLM call (using trace_id and span_id from step 1):

{
  "trace_id": "trace_123",
  "span_id": "456",
  "include": { "llm_payload": true, "unsafe_text": true }
}

This workflow gives you the complete context of what failed, where it failed, and why—all from your terminal/IDE.