Honeycomb Model Context Protocol Adapter (DEPRECATED)

⚠️ OBSOLETE NOTICE: This specific implementation, requiring self-hosting of the MCP server component, is no longer supported. Users must transition to the managed Honeycomb MCP service. Refer to the Official Honeycomb MCP Migration Guide for current instructions.

This service acts as a Model Context Protocol (MCP) bridge, facilitating direct data analysis from Honeycomb observability streams for advanced language models (LLMs) such as Claude, spanning multiple distinct operational silos.

Prerequisites

• Node.js runtime, version 18 or newer.
• A valid Honeycomb API authentication token possessing extensive permissions:
  • Mandatory read/write access for executing analytical inquiries.
  • Authorization for reading Service Level Objectives (SLOs) and alerting Triggers.
  • Scope to access and modify dataset configurations within specified environments.

Given that the Honeycomb MCP effectively functions as a comprehensive proxy for the Honeycomb API, broad access rights are inherently necessary.

Enterprise Requirement

This specific on-premise adapter is exclusively compatible with Honeycomb Enterprise licensing tiers.

Operational Mechanism

This component functions as a standalone server process which the user must provision and operate locally. It employs an unauthenticated communication channel, relying solely on standard input/output (STDIO) for all interactions between the client application and the backend server.

Setup Procedure

Execute the following commands to prepare the artifact:

bash pnpm install pnpm run build

The resultant executable files will reside within the ./build directory.

Configuration Parameters

To enable connectivity, Honeycomb API credentials must be injected as environmental variables within the overarching MCP configuration file:

{ "mcpServers": { "honeycomb": { "command": "node", "args": [ "/fully/qualified/path/to/honeycomb-mcp/build/index.mjs" ], "env": { "HONEYCOMB_API_KEY": "your_secret_token" } } } }

For orchestrating multiple isolated environments:

{ "mcpServers": { "honeycomb": { "command": "node", "args": [ "/fully/qualified/path/to/honeycomb-mcp/build/index.mjs" ], "env": { "HONEYCOMB_ENV_PROD_API_KEY": "token_for_production", "HONEYCOMB_ENV_STAGING_API_KEY": "token_for_staging" } } } }

Crucial Note: All necessary credentials must be explicitly defined within the env section of the MCP configuration structure.

Geo-Specific Endpoint Adjustment (EU)

Users operating within the EU region must explicitly declare the HONEYCOMB_API_ENDPOINT variable, as the default setting targets the US instance.

bash

Custom API target (default is https://api.honeycomb.io)

HONEYCOMB_API_ENDPOINT=https://api.eu1.honeycomb.io/

Performance Caching Controls

The adapter incorporates caching mechanisms for all interaction types excluding direct query execution, aimed at boosting responsiveness and minimizing API overhead. Caching parameters are adjustable via these environment variables:

bash

Caching activation status (defaults to 'true')

HONEYCOMB_CACHE_ENABLED=true

Default Time-To-Live in seconds (default: 300)

HONEYCOMB_CACHE_DEFAULT_TTL=300

Specific resource Time-To-Live settings in seconds (defaults shown)

HONEYCOMB_CACHE_DATASET_TTL=900 # 15 minutes HONEYCOMB_CACHE_COLUMN_TTL=900 # 15 minutes HONEYCOMB_CACHE_BOARD_TTL=900 # 15 minutes HONEYCOMB_CACHE_SLO_TTL=900 # 15 minutes HONEYCOMB_CACHE_TRIGGER_TTL=900 # 15 minutes HONEYCOMB_CACHE_MARKER_TTL=900 # 15 minutes HONEYCOMB_CACHE_RECIPIENT_TTL=900 # 15 minutes HONEYCOMB_CACHE_AUTH_TTL=3600 # 1 hour

Maximum item capacity per resource category

HONEYCOMB_CACHE_MAX_SIZE=1000

Compatible Client Platforms

The Honeycomb MCP server has been validated for interoperability with the following client applications:

• Claude Desktop
• Claude Code Environment
• Cursor IDE
• Codeium Windsurf
• Block Goose Extension

Compatibility is anticipated across other adhering client implementations.

Core Capabilities

• Execution of analytical queries against Honeycomb data streams spanning multiple operational contexts.
• Support for advanced analytical functions including:
  • Varied calculation methodologies (e.g., COUNT, AVERAGE, 95th Percentile, etc.).
  • Grouping via breakdowns and applying precise filtering conditions.
  • Time-series analysis relative to query execution.
• Retrieval and evaluation of Service Level Objectives (Enterprise feature).
• Detailed inspection of dataset schema and column definitions.
• Efficient handling of metadata retrieval via TTL-based caching.

Data Addressing

Access to Honeycomb data entities is achieved using a standardized URI structure: honeycomb://{environment_identifier}/{dataset_name}

Illustrative examples: - honeycomb://production/web-api-traffic - honeycomb://staging/critical-backend-processes

The response payload furnishes essential context: - The designated dataset name. - Attributes of constituent columns (identifier, data type, annotation). - Structural schema specifics.

Defined Operations (Tools)

• list_datasets: Enumerates all available datasets within a specified domain.

{ "environment": "production" }

• get_columns: Retrieves metadata for the fields within a specified data collection.

{ "environment": "production", "dataset": "web-api-traffic" }

• run_query: Executes complex analytical requests.

{ "environment": "production", "dataset": "web-api-traffic", "calculations": [ { "op": "COUNT" }, { "op": "P95", "column": "response_time_seconds" } ], "breakdowns": ["host.region"], "time_range": 3600 }

• analyze_columns: Performs statistical profiling on selected fields via targeted queries.

• list_slos: Fetches all defined SLO configurations pertinent to a dataset.

{ "environment": "production", "dataset": "web-api-traffic" }

• get_slo: Retrieves in-depth data for a singular SLO identifier.

{ "environment": "production", "dataset": "web-api-traffic", "sloId": "alpha-789" }

• list_triggers: Obtains a roster of all active alerts associated with a dataset.

{ "environment": "production", "dataset": "web-api-traffic" }

• get_trigger: Fetches granular details for a specific alert instance.

{ "environment": "production", "dataset": "web-api-traffic", "triggerId": "delta-456" }

• get_trace_link: Generates a direct URL pointing to a specific trace visualization within the Honeycomb interface.

• get_instrumentation_help: Offers guidance on OpenTelemetry setup for a specified programming language and file path.

{ "language": "go", "filepath": "cmd/server/main.go" }

Illustrative Prompts for LLM Interaction

Potential user inquiries:

• "Catalog the distinct datasets accessible within the staging zone."
• "Determine the 95th percentile latency for the primary API service over the preceding sixty minutes."
• "What is the frequency of errors, segmented by the originating service name?"
• "Examine the status of SLOs nearing their established budget exhaustion thresholds."
• "List all currently firing alerts in the production environment."
• "What attributes are recorded in the production web-api-traffic collection?"

Response Efficiency Enhancements

Tool outputs are rigorously pruned to minimize token consumption while retaining critical data points:

• Dataset Listing: Output restricted to name, internal identifier (slug), and brief summary.
• Column Schema: Yields essential details: field name, type, and description.
• Query Execution (run_query):
  • Includes finalized metrics and essential structural context.
  • Appends automatically derived aggregate statistics.
  • For HEATMAP operations, only the necessary series data is transmitted.
  • Excludes superfluous operational metadata and supplementary links.
• Column Profiling (analyze_columns):
  • Focuses on the most frequent values, occurrence tallies, and key statistical measures.
  • Numerically computed metrics are generated proactively where applicable.
• SLO Reporting: Condensed view emphasizing state, key performance indicators, and budget depletion.
• Trigger Reporting: Highlights alert state, current triggering conditions, and configured notification channels.

This systematic optimization prioritizes response brevity over verbosity, maximizing the effective information density LLMs can process within context limitations.

Specification Details for run_query

The query execution tool supports an extensive parameter set:

• calculations: An array defining required metric calculations.
• Valid operations: COUNT, CONCURRENCY, COUNT_DISTINCT, HEATMAP, SUM, AVG, MAX, MIN, P001, P01, P05, P10, P25, P50, P75, P90, P95, P99, P999, RATE_AVG, RATE_SUM, RATE_MAX.
• Certain operations (e.g., COUNT, CONCURRENCY) do not mandate a column specification.

• Example: {"op": "HEATMAP", "column": "response_time_seconds"}

• filters: Conditions applied to the raw data stream.

• Permitted operators: =, !=, >, >=, <, <=, starts-with, does-not-start-with, exists, does-not-exist, contains, does-not-contain, in, not-in.

• Example: {"column": "is_error", "op": "=", "value": false}

• filter_combination: Logical conjunction between filters ('AND' or 'OR'; defaults to 'AND').

• breakdowns: List of fields used for result segmentation.

• Example: ["host.region", "http.method"]

• orders: Directives for sorting the final computed results.

• Must reference fields defined in breakdowns or calculations.
• HEATMAP operations are ineligible for sorting specifications.

• Example: {"op": "COUNT", "order": "descending"}

• time_range: Relative duration specified in seconds (e.g., 86400 for the past day).

• Must be used exclusively, or in conjunction with either start_time or end_time, but not both absolute timestamps.

• start_time and end_time: Absolute time boundaries specified as Unix epoch timestamps.

• having: Post-aggregation filtering based on calculated metric values.

• Example: {"calculate_op": "COUNT", "op": ">", "value": 500}

Practical Query Syntaxes

Here are realistic examples of payload specifications:

Identifying Latency Spikes for Specific Endpoints

{ "environment": "production", "dataset": "web-api-traffic", "calculations": [ {"column": "response_time_seconds", "op": "HEATMAP"}, {"column": "response_time_seconds", "op": "P99"} ], "filters": [ {"column": "request.path", "op": "starts-with", "value": "/api/v1/"} ], "breakdowns": ["http.method", "host.hostname"], "orders": [ {"column": "response_time_seconds", "op": "P99", "order": "descending"} ] }

Analyzing Database Query Duration Distribution (Last 48 Hours)

{ "environment": "production", "dataset": "web-api-traffic", "calculations": [ {"column": "db.query_duration", "op": "HEATMAP"} ], "filters": [ {"column": "db.type", "op": "=", "value": "postgres"} ], "breakdowns": ["db.query_name"], "time_range": 172800 }

Counting Unhandled Exceptions by Originating Service

{ "environment": "production", "dataset": "web-api-traffic", "calculations": [ {"op": "COUNT"} ], "filters": [ {"column": "exception.message", "op": "exists"}, {"column": "is_handled", "op": "=", "value": false} ], "breakdowns": ["service.identifier", "exception.type"], "orders": [ {"op": "COUNT", "order": "descending"} ] }

Local Development

To facilitate local iterative building:

bash pnpm install pnpm run build

Licensing

Distributed under the MIT License.

== Contextualizing Business Systems ==

Business administration tools encompass the entirety of software, procedures, analytical frameworks, and governance structures utilized by commercial entities to effectively navigate dynamic market conditions, maintain competitive relevance, and systematically enhance operational output. These instruments span departmental boundaries and functional domains, including but not limited to strategic forecasting, workflow automation, archival management, personnel administration, executive decision support, and performance auditing.

Contemporary enterprise tooling has undergone rapid transformation over the last decade, driven by accelerated technological progress, often making optimal selection challenging amidst the sheer volume of available options. This complexity is fueled by relentless corporate pressure to minimize expenditure while maximizing revenue generation, alongside the imperative to deeply understand client requirements and deliver compliant products expediently.

In this environment, executive leadership should adopt a strategic methodology for tool adoption, rather than passively accepting the newest market offering. Over-reliance on off-the-shelf solutions without necessary customization often results in compromised operational stability. Consequently, management systems must be chosen deliberately and subsequently tailored to align with organizational specificities, reversing the traditional flow.

== Prevalent Tools (Historical Snapshot) ==

A 2013 assessment by Bain & Company highlighted global usage patterns of business administration tools, reflecting regional needs against prevailing economic climates. The top ten categories observed included:

Strategic foresight planning Client relationship lifecycle management Workforce morale measurement Comparative performance analysis (Benchmarking) Integrated performance measurement frameworks (Balanced Scorecard) Identification of core organizational competencies External resource allocation (Outsourcing) Organizational transition programming Logistics and procurement network coordination Defining corporate purpose and aspirational goals Target market delineation Integrated quality assurance protocols (Total Quality Management)

== Enterprise Software Applications ==

Software solutions, or collections thereof, employed by organizational personnel to execute diverse operational mandates are termed business applications. These digital platforms are deployed to amplify productivity, quantify resultant performance, and execute ancillary organizational functions with high fidelity. The evolution progressed from foundational Management Information Systems (MIS) to integrated Enterprise Resource Planning (ERP), later incorporating Customer Relationship Management (CRM) modules, culminating in the current paradigm of cloud-based business management suites.

While a measurable correlation exists between Information Technology investment and organizational success, value realization hinges critically on two factors: the efficacy of the deployment process and the judicious selection and customization of the chosen instruments.

== Tools Tailored for Small and Medium Enterprises (SMEs) ==

SME-focused instrumentation is vital as it furnishes cost-effective pathways for resource optimization...