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

View Available Tools: The UI shows all available MCP tools (e.g., list_resources_bydbql)
Test Queries: Enter natural language descriptions and see the generated BydbQL queries
View Results: See the query results returned from BanyanDB
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

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
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 30 minutes, as specified in the description.

Example 2: Querying a Stream

Natural Language Description:

list log data in last day

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 the last day
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 time

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 time
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 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 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.

Resource Lookup Behavior

The MCP server uses intelligent resource lookup when generating queries from natural language descriptions. Understanding this behavior helps you write more effective queries.

Resource Name Lookup Across Groups

When the same resource name exists in multiple groups, the LLM will use the first group it can look up from the available resource mappings. The lookup process follows this order:

Exact Match: The LLM first attempts to find an exact match for the resource name
First Available Group: If the resource name appears in multiple groups, the LLM will use the first group it encounters during lookup
Similarity Matching: If an exact match cannot be found, the LLM will match the most similar resource name from the available resources

Example Scenarios

Scenario 1: Same Resource Name in Multiple Groups

If you have a resource named service_cpm in both metricsMinute and metricsHour groups:

Description: "list service_cpm from last hour"

The LLM will use the first group it finds in the resource mapping. To ensure a specific group is used, explicitly mention it:

Description: "list service_cpm in metricsHour from last hour"

Scenario 2: Similarity Matching

If you request a resource that doesn’t exist exactly, the LLM will find the most similar match:

Description: "list service_cpm from last hour"
Available resources: service_cpm_minute, service_cpm_hour

The LLM will match service_cpm_minute or service_cpm_hour based on similarity, preferring the closest match.

Best Practices

Be Explicit: When you know the exact group name, include it in your description (e.g., “in metricsMinute”)
Use Specific Names: Use the exact resource names from your BanyanDB schema when possible
Check Available Resources: Use the list_resources_bydbql tool to see available resources and their groups before querying

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

Edit this page