@lakehouse/mcp-server

Model Context Protocol (MCP) server for Lakehouse42.

Features

• Code-First Pattern - On-demand tool discovery (~98% token reduction)
• Tool Tagging - Filter tools by category (read/write/admin/search/time-travel)
• Cursor Pagination - Efficient browsing of large result sets
• Streamable HTTP - Scalable deployment with session recovery
• Optimized Responses - Compact JSON, truncated snippets, sample rows

Quick Start

LAKEHOUSE42_API_KEY=lh_xxx npx @lakehouse/mcp-server

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "lakehouse42": {
      "command": "npx",
      "args": ["@lakehouse/mcp-server"],
      "env": {
        "LAKEHOUSE42_API_KEY": "lh_your_api_key"
      }
    }
  }
}

Environment Variables

| Variable | Required | Default | |----------|----------|---------| | LAKEHOUSE42_API_KEY | Yes | - | | LAKEHOUSE42_BASE_URL | No | https://api.lakehouse42.com |

Tools

search_tools

Discover tools on-demand (code-first pattern).

{ "tags": ["search"], "detail": "summary" }

| Parameter | Type | Description | |-----------|------|-------------| | query | string | Search term | | tags | string[] | read, write, admin, search, time-travel | | detail | string | name (10 tokens), summary (50), full (150) |

search

Hybrid search with cursor pagination.

{ "query": "revenue report", "top_k": 10 }

Returns: 5 results max, 200-char snippets, next_cursor for pagination.

ask_question

RAG-powered Q&A.

{ "question": "What is our refund policy?" }

Returns: answer + source count.

get_document / list_documents / list_collections

Document and collection management with cursor pagination.

upload_document

Upload text documents (auto-chunked and indexed).

time_travel_query / time_travel_diff / list_snapshots

Iceberg time-travel queries. Returns row count + 3 sample rows.

HTTP Transport

For web deployments:

import { HttpTransport, ToolExecutor, ApiClient } from '@lakehouse/mcp-server';

const client = new ApiClient({ apiKey: 'lh_xxx', baseUrl: 'https://api.lakehouse42.com' });
const transport = new HttpTransport({ toolExecutor: new ToolExecutor(client) });

http.createServer((req, res) => transport.handleRequest(req, res)).listen(3000);

Features:

• Session management (Mcp-Session-Id header)
• SSE streaming (Accept: text/event-stream)
• Disconnect recovery (Last-Event-ID)

Endpoints:

• POST /mcp - JSON-RPC requests
• GET /mcp - SSE stream
• DELETE /mcp - Close session
• GET /health - Health check

Programmatic Usage

import { createServer, searchTools, TAGGED_TOOLS } from '@lakehouse/mcp-server';

// Stdio server
const server = createServer({ apiKey: 'lh_xxx' });
await server.start();

// Tool discovery
const readTools = searchTools(undefined, ['read'], 'name');
// → [{ name: 'search' }, { name: 'ask_question' }, ...]

Response Optimization

| Tool | Optimization | |------|--------------| | search | 5 results, 200-char snippets | | list_documents | 10 docs, essential fields | | time_travel_query | 3 sample rows + count |

All responses use compact JSON (no pretty-printing).

License

MIT