Test via Inspector Guide

MCP Inspector is a tool for testing and debugging MCP servers. This guide explains how to use it to test the BanyanDB MCP server.

Prerequisites

  • MCP server set up (see Setup Guide)
  • BanyanDB running and accessible
  • Node.js 20+ installed (for running Inspector)

Installation

Install MCP Inspector globally:

npm install -g @modelcontextprotocol/inspector

Or use it directly with npx (no installation needed):

npx @modelcontextprotocol/inspector

Basic Setup

1. Create Configuration File

cp example-config.json inspector-config.json

Edit inspector-config.json with absolute path, api key and base url.

Important: Use absolute paths for the binary location.

2. Start Inspector (UI Mode)

npx @modelcontextprotocol/inspector --config inspector-config.json

This will:

  • Start the MCP server
  • Open a web UI at http://localhost:6274 in your default browser
  • Allow you to interactively test MCP tools

3. Using the Inspector UI

  1. View Available Tools: The UI shows all available MCP tools (e.g., list_resources_bydbql)
  2. Test Queries: Enter natural language descriptions and see the generated BydbQL queries
  3. View Results: See the query results returned from BanyanDB
  4. Debug: Check logs and error messages in the Inspector console

CLI Mode

You can also use Inspector in CLI mode for scripting and automation:

npx @modelcontextprotocol/inspector --cli node dist/index.js \
  -e BANYANDB_ADDRESS=localhost:17900 \
  -e LLM_API_KEY=sk-your-key-here \
  --method tools/call \
  --tool-name list_resources_bydbql \
  --tool-arg "description=Show MEASURE service_cpm_minute in sw_metricsMinute from last hour"

Usage Examples

The MCP server translates natural language descriptions into BydbQL queries and executes them against BanyanDB. Here’s how it works:

Example 1: Measure Query

Natural Language Description:

list the last 30 minutes service_cpm_minute in metricsMinute

Generated BydbQL Query:

SELECT * FROM MEASURE service_cpm_minute IN metricsMinute TIME > '-30m'

Result:

=== Query Result ===

Measure Query Result:
[{
    "timestamp": "2025-11-24T09:21:00Z",
    "tagFamilies": [
      {
        "name": "storage-only",
        "tags": [
          {
            "key": "entity_id",
            "value": {
              "str": {
                "value": "Ki01fGRldi1lc2hvcHxhcHAtY2x1c3Rlci0xLTA=.1"
              }
            }
          } 
        ],
        "fields": [
          {
            "name": "value",
            "value": {
              "int": {
                "value": "8"
              }
            }
          }
        ],
        "sid": "3370749934026519158",
        "version": "77686909415634"
      },
    ]
}]
=== BydbQL Query ===
SELECT * FROM MEASURE service_cpm_minute IN metricsMinute TIME > '-30m'

=== Debug Information ===
Description: list the last day service_cpm_minute in metricsMinute
Resource Type: measure
Resource Name: service_cpm_minute
Group: metricsMinute

=== Explanations ===
This query selects all data from the resource 'service_cpm_minute' of type MEASURE in the group 'metricsMinute' for the last day, as specified in the description.

Example 2: Querying a Stream

Natural Language Description:

list log data in last day, the group is recordsLog

Generated BydbQL Query:

SELECT * FROM STREAM log IN recordsLog TIME >= '-1h'

Result:

=== Query Result ===

Stream Query Result:
{
  "elements": [
    {
      "elementId": "da29bd8e7d4c8192",
      "timestamp": "2025-11-24T09:20:00Z",
      "tagFamilies": [
        {
          "name": "searchable",
          "tags": [
            {
              "key": "tags",
              "value": {
                "null": null
              }
            },
            {
              "key": "unique_id",
              "value": {
                "str": {
                  "value": "898482062a414e54b805aa3f106d52bc_3559"
                }
              }
            },]
      }]
    },
  ]
}

=== BydbQL Query ===
SELECT * FROM STREAM log IN recordsLog TIME > '-1d'

=== Debug Information ===
Description: list log data in last day, the group is recordsLog
Resource Type: stream
Resource Name: log
Group: recordsLog

=== Explanations ===
This query retrieves all log data from the 'recordsLog' group for the last day. The resource type is determined as STREAM from the keyword 'log', the resource name is extracted as 'log', and the group name is explicitly given as 'recordsLog'.

Example 3: Querying Traces with LIMIT

Natural Language Description:

list the last 3 zipkin_span order by timestamp_millis, the group is zipkinTrace

Generated BydbQL Query:

SELECT * FROM TRACE zipkin_span IN zipkinTrace ORDER BY timestamp_millis DESC LIMIT 3

Result:

=== Query Result ===

Trace Query Result:
{
  "traces": [
    {
      "spans":[
        {
          "tags": [],
          "span": "Cu4BCusBChBL/bXJzPoKPwA/2QwaTjL9Eghq7IDHs8/JEBoIU4Jqwt3AekAgASoIaHR0cC9nZXQxwENbkIc/BgA4mMIMQgoKCGNoZWNrb3V0WhIKC2h0dHAubWV0aG9kEgNHRVRaKwoJaHR0cC5wYXRoEh4vcHJveHkvYWNjb3VudGluZy5kZXYtcGF5bWVudHNaGgoSaHR0cC5yZXNwb25zZS5zaXplEgQxMjkwWkEKB3RldHJhdGUSNnYxLjEwLjAtaW50ZXJuYWwtcmMwLW9ic3Rlc3Rlci1lcnJvciAoOWNkOGFhNTJlLCArMzAxKRAC",
          "spanId": "53826ac2ddc07a40.5.15"
        },
      ]
      "traceId": "4bfdb5c9ccfa0a3f003fd90c1a4e32fd-6356"
    },
    {
      "spans": [
        {
          "tags": [],
          "span": "Cu4BCusBChBL/bXJzPoKPwA/2QwaTjL9Eghq7IDHs8/JEBoIU4Jqwt3AekAgASoIaHR0cC9nZXQxwENbkIc/BgA4mMIMQgoKCGNoZWNrb3V0WhIKC2h0dHAubWV0aG9kEgNHRVRaKwoJaHR0cC5wYXRoEh4vcHJveHkvYWNjb3VudGluZy5kZXYtcGF5bWVudHNaGgoSaHR0cC5yZXNwb25zZS5zaXplEgQxMjkwWkEKB3RldHJhdGUSNnYxLjEwLjAtaW50ZXJuYWwtcmMwLW9ic3Rlc3Rlci1lcnJvciAoOWNkOGFhNTJlLCArMzAxKRAC",
          "spanId": "53826ac2ddc07a40.5.15"
        },
      ]
      "traceId": "4bfdb5c9ccfa0a3f003fd90c1a4e32fd-6353"
    },
    {
      "spans": [
        {
          "tags": [],
          "span": "Cu4BCusBChBL/bXJzPoKPwA/2QwaTjL9Eghq7IDHs8/JEBoIU4Jqwt3AekAgASoIaHR0cC9nZXQxwENbkIc/BgA4mMIMQgoKCGNoZWNrb3V0WhIKC2h0dHAubWV0aG9kEgNHRVRaKwoJaHR0cC5wYXRoEh4vcHJveHkvYWNjb3VudGluZy5kZXYtcGF5bWVudHNaGgoSaHR0cC5yZXNwb25zZS5zaXplEgQxMjkwWkEKB3RldHJhdGUSNnYxLjEwLjAtaW50ZXJuYWwtcmMwLW9ic3Rlc3Rlci1lcnJvciAoOWNkOGFhNTJlLCArMzAxKRAC",
          "spanId": "53826ac2ddc07a40.5.15"
        },
      ]
      "traceId": "4bfdb5c9ccfa0a3f003fd90c1a4e32fd-6347"
    }
  ],
  "traceQueryResult": null
}

=== BydbQL Query ===
SELECT * FROM TRACE zipkin_span IN zipkinTrace ORDER BY timestamp_millis DESC LIMIT 3

=== Debug Information ===
Description: list the last 3 zipkin_span order by timestamp_millis, the group is zipkinTrace
Resource Type: trace
Resource Name: zipkin_span
Group: zipkinTrace

=== Explanations ===
This query retrieves the last 3 entries of zipkin_span from the zipkinTrace group, ordered by timestamp_millis in descending order. The number of results is explicitly requested as 3.

Example 4: Top-N Query with Aggregation

Natural Language Description:

Show TOP3 MEASURE endpoint_2xx in metricsMinute from last 30 minutes, AGGREGATE BY MAX and ORDER BY DESC

Generated BydbQL Query:

SHOW TOP 3 FROM MEASURE endpoint_2xx IN metricsMinute TIME >= '-30m' AGGREGATE BY MAX ORDER BY DESC

Result:

=== Query Result ===

TopN Query Result:
{
  "lists": [
    {
      "timestamp": null,
      "items": [
        {
          "entity": [
            {
              "key": "entity_id",
              "value": {
                "str": {
                  "value": "ZGV2LXN0YWJsZXx0c2ItZ2F0ZXdheS1kZXYtZWRnZS0wfGRldi1lZGdlfHRyYW5zaXQtY2x1c3Rlci0xLTB8LQ==.1_R0VUOi9wcm94eS9vcmRlcnMvcHJveHkvY2hlY2tvdXQuZGV2LWNoZWNrb3V0L3Byb3h5L3BheW1lbnRzLnRldHJhdGUuZGV2L3Byb3h5L2FjY291bnRpbmcuZGV2LXBheW1lbnRzLTE="
                }
              }
            }
          ],
          "value": {
            "int": {
              "value": "1"
            }
          }
        }
      ]
    }
  ],
  "trace": null
}

=== BydbQL Query ===
SHOW TOP 3 FROM MEASURE endpoint_2xx IN metricsMinute TIME > '-30m' AGGREGATE BY MAX ORDER BY DESC

=== Debug Information ===
Description: Show TOP3 MEASURE endpoint_2xx in metricsMinute from last 30 minutes, AGGREGATE BY MAX and ORDER BY DESC
Resource Type: measure
Resource Name: endpoint_2xx
Group: metricsMinute

=== Explanations ===
This query fetches the top 3 maximum values of the measure 'endpoint_2xx' from the group 'metricsMinute' over the last 30 minutes. The values were explicitly provided for resource name, group name, and aggregate function, while the time condition is derived from the description.

Troubleshooting

Inspector UI not opening:

  • Check if port 6274 is available
  • Verify the MCP server binary path is correct
  • Check Inspector logs for errors

MCP server not starting:

  • Verify Node.js 20+ is installed: node --version
  • Check environment variables are set correctly
  • Verify BanyanDB is accessible: curl http://localhost:17913/api/healthz

Query generation fails:

  • Check LLM_API_KEY is set if using LLM-powered generation
  • Verify network connectivity to LLM API
  • Check Inspector console for error messages

No results returned:

  • Verify BanyanDB has data for the queried resources
  • Check time range is appropriate
  • Verify resource names and groups are correct

Resources