Model Context Protocol (MCP) Server (`benostreamdb-mcp`)¶

benostreamdb-mcp is an AI agent tool server implementing the open Model Context Protocol (MCP) over JSON-RPC stdio.

Overview¶

The MCP server allows LLMs and autonomous AI agents (such as Claude Desktop, Cursor, and Antigravity) to interact directly with BenoStreamDB lakehouse tables without bespoke API integrations:

Discover Tables: Introspect available datasets, node tables, and edge tables.
Inspect Schemas: Read Arrow and Iceberg table schemas as MCP resources.
Execute SQL: Run analytical queries, pgvector distance operations, and graph traversals.
Stream Events: Subscribe to live table change feeds.

Installation & Running¶

Recommended: Run via `uvx` (No Installation Required)¶

You can launch benostreamdb-mcp instantly with uvx, which automatically downloads the prebuilt native binary from PyPI:

uvx benostreamdb-mcp

Alternative: Install via Pip¶

pip install benostreamdb-mcp
benostreamdb-mcp

From Source via Cargo¶

cargo build --release -p benostreamdb-mcp

The compiled binary will be placed at target/release/benostreamdb-mcp.

Configuration with AI Clients¶

Add the server to your MCP client configuration (e.g., claude_desktop_config.json, Cursor, or Antigravity):

With `uvx` (Recommended)¶

{
  "mcpServers": {
    "benostreamdb": {
      "command": "uvx",
      "args": ["benostreamdb-mcp"],
      "env": {
        "BSDB_WAREHOUSE": "/path/to/warehouse",
        "BSDB_GPU_DEVICE": "auto"
      }
    }
  }
}

With Prebuilt Binary / Source Build¶

{
  "mcpServers": {
    "benostreamdb": {
      "command": "/path/to/target/release/benostreamdb-mcp",
      "env": {
        "BSDB_WAREHOUSE": "/path/to/warehouse",
        "BSDB_GPU_DEVICE": "auto"
      }
    }
  }
}

Environment Variables¶

Variable	Description	Default
`BSDB_WAREHOUSE`	Base directory or URI for tables	`./data`
`BSDB_GPU_DEVICE`	Compute target or pool (`auto`, `cpu`, `cuda[:N]`, `mps`, `cuda:0,cuda:1`)	`auto`
`BSDB_CONFIG`	Catalog configuration file path	Unset

Exposed MCP Tools¶

The agent can invoke the following tools:

Tool	Purpose	Parameters
`list_graph_tables`	List all discovered tables, edge tables, and node tables	`{}`
`execute_sql`	Execute a SQL query (SELECT, vector distance, graph traversal)	`{"query": "SELECT ..."}`
`subscribe_events`	Drain change-feed events for a table	`{"table": "edges", "filter": "...", "max_events": 100}`

Resources¶

Tables are exposed as read-only resources:

URI format: benostreamdb://tables/{schema}/{table}
Content: JSON schema representation including field types, partitions, and index coverage.

Example Agent Workflow¶

An AI agent uses the MCP server to solve retrieval tasks in a structured sequence:

Discover: Calls list_graph_tables to identify available tables.
Schema: Reads benostreamdb://tables/default/documents to understand available columns and vector dimensions.
Retrieve: Calls execute_sql with pgvector similarity operators (<->, <=>) or graph table functions (graph_neighbors).
Synthesize: Answers the user request using the grounded result set.

Model Context Protocol (MCP) Server (benostreamdb-mcp)¶