V1 [MCP] MCP server for AI integration

[austin-barrington]

Context

AI agents and coding tools (Claude Code, Cursor, Windsurf, GitHub Copilot) increasingly use the Model Context Protocol (MCP) to interact with data sources. HyperbyteDB should expose an MCP server so AI can query time-series data, inspect schema, and run TimeseriesQL directly — without a human intermediary.

Deliverables

Core MCP Server

• Implement an MCP server that listens on a configurable transport (stdio for local agents, or SSE for remote).
• Follow the MCP specification for tool definitions, resource exposure, and prompts.

Tools (MCP Tools)

Tool	Description	Inputs
query	Execute TimeseriesQL and return JSON results	db, query, optional epoch, chunked
list_databases	List all databases	—
list_measurements	List measurements in a database	db
list_tag_keys	List tag keys for a measurement	db, measurement
list_field_keys	List field keys for a measurement	db, measurement
schema	Get full schema description for a database	db
write	Write line protocol data	db, data, optional precision
health	Check server status	—

Resources (MCP Resources)

• hyperbytedb://databases — list of databases
• hyperbytedb://{db}/measurements — measurements in a DB
• hyperbytedb://{db}/{measurement}/schema — schema for a measurement
• hyperbytedb://health — server health

Configuration

Add an [mcp] config section:

Key	Type	Default	Description
enabled	boolean	false	Enable MCP server
transport	string	"stdio"	Transport: stdio or sse
port	integer	8087	SSE port (if transport = "sse")
bind_address	string	"127.0.0.1"	Bind address for SSE transport

Auth integration

When [auth] enabled = true, MCP tools that mutate data (write) or access admin-level info should require credentials via the MCP session handshake.

Documentation

• docs/user-guide/mcp.md — MCP setup, tool reference, AI client configuration examples
• Add row to docs/user-guide/index.md reading order

References

• MCP spec: https://modelcontextprotocol.io
• Example MCP SDK for Rust: https://github.com/modelcontextprotocol/rust-sdk (or alternative)
• Existing HTTP auth middleware in src/adapters/http/auth_middleware.rs
• Query service in src/application/query_service.rs
• Config pattern in src/config.rs

Priority

P1 — High value for AI/developer workflows