hdbconnect-mcp

MCP (Model Context Protocol) server providing AI assistants with secure, programmatic access to SAP HANA databases.

Features

• Interactive Parameter Collection — Elicits missing schema names from users during tool execution
• 4 Core Tools — ping, list_tables, describe_table, execute_sql
• Security First — Read-only mode blocks DML/DDL, configurable row limits prevent data exfiltration
• Connection Pooling — Efficient resource management with deadpool
• Full JSON Schema — AI-discoverable tool definitions with comprehensive descriptions
• Zero Unsafe Code — Memory-safe Rust implementation

Installation

From crates.io

cargo install hdbconnect-mcp

From source

git clone https://github.com/bug-ops/pyhdb-rs.git
cd pyhdb-rs/crates/hdbconnect-mcp
cargo install --path .

[!IMPORTANT] Requires Rust 1.88 or later. See MSRV policy.

Quick Start

Standalone Server

hdbconnect-mcp \
  --url "hdbsql://user:password@host:39017" \
  --read-only true \
  --row-limit 10000 \
  --pool-size 4

Claude Desktop Integration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "hana": {
      "command": "hdbconnect-mcp",
      "args": [
        "--url", "hdbsql://user:password@host:39017",
        "--read-only", "true",
        "--row-limit", "10000"
      ]
    }
  }
}

[!TIP] Use environment variables for credentials: --url "hdbsql://${HANA_USER}:${HANA_PASSWORD}@${HANA_HOST}:39017"

Configuration

[!WARNING] Setting --read-only false allows INSERT/UPDATE/DELETE operations. Only use in trusted environments.

MCP Tools

ping

Check database connection health and measure latency.

Returns:

{
  "status": "ok",
  "latency_ms": 12
}

list_tables

List tables in a schema with interactive elicitation for missing schema parameter.

Parameters:

• schema (optional) — Schema name (defaults to CURRENT_SCHEMA)

Returns:

[
  { "name": "EMPLOYEES", "table_type": "TABLE" },
  { "name": "ORDERS", "table_type": "TABLE" }
]

describe_table

Get column definitions for a table with type information.

Parameters:

• table (required) — Table name
• schema (optional) — Schema name (elicited if missing)

Returns:

{
  "table_name": "EMPLOYEES",
  "columns": [
    { "name": "ID", "data_type": "INTEGER", "nullable": false },
    { "name": "NAME", "data_type": "NVARCHAR", "nullable": true }
  ]
}

execute_sql

Execute SQL queries with configurable row limits.

Parameters:

• sql (required) — SQL query (SELECT/WITH/EXPLAIN/CALL in read-only mode)
• limit (optional) — Row limit (overrides server default)

Returns:

{
  "columns": ["ID", "NAME", "DEPARTMENT"],
  "rows": [
    [1, "Alice", "Engineering"],
    [2, "Bob", "Sales"]
  ],
  "row_count": 2
}

[!CAUTION] In read-only mode (default), only SELECT, WITH, EXPLAIN, and CALL statements are permitted. Other SQL commands will be rejected.

Features

Default

Standard stdio transport for MCP integration.

http

Enable HTTP transport for remote MCP access.

[dependencies]
hdbconnect-mcp = { version = "0.3", features = ["http"] }

[!NOTE] HTTP transport requires additional authentication configuration. See HTTP Transport Guide for setup.

cache

Enable in-memory caching for schema metadata and query results.

[dependencies]
hdbconnect-mcp = { version = "0.3", features = ["cache"] }

Cache Deployment Notes

Performance benefits:

• Schema metadata cached for 1 hour (configurable)
• Query results cached for 60 seconds (configurable)
• Cache hit latency: 3-6 microseconds vs database round-trip

Multi-tenant safety: When combined with auth feature, cache implements per-user isolation:

• Different users get different cache keys (includes user_id hash)
• User A cannot read User B's cached query results
• Cache poisoning attacks affect only attacker's own cache entries

Single-user deployments: For stdio transport or when auth is disabled, all queries use _system user. This is safe and recommended for personal AI assistants or service accounts.

Schema staleness: DDL changes (ALTER TABLE, DROP COLUMN) may not be reflected until TTL expires. For environments with frequent schema changes, reduce TTL or disable caching.

auth

Enable OIDC/JWT authentication and multi-tenant support.

[dependencies]
hdbconnect-mcp = { version = "0.3", features = ["auth", "http", "cache"] }

Security features:

• JWT validation with RS256/ES256/HS256 algorithms
• OIDC discovery support
• Multi-tenant schema isolation via JWT claims
• Per-user cache isolation when combined with cache feature
• Role-based access control (RBAC) foundations

Architecture

┌─────────────────┐
│  MCP Client     │ (Claude Desktop, Cline, etc.)
└────────┬────────┘
         │ stdio/HTTP
┌────────▼────────┐
│ hdbconnect-mcp  │
│  ├─ server.rs   │ (Tool handlers with elicitation)
│  ├─ pool.rs     │ (Connection pooling)
│  ├─ config.rs   │ (CLI configuration)
│  ├─ types.rs    │ (JSON Schema types)
│  └─ validation  │ (SQL safety checks)
└────────┬────────┘
         │ hdbconnect_async
┌────────▼────────┐
│   SAP HANA DB   │
└─────────────────┘

Contributing

See CONTRIBUTING.md for development guidelines.

Development

# Build
cargo build -p hdbconnect-mcp

# Run tests
cargo nextest run -p hdbconnect-mcp

# Lint
cargo clippy -p hdbconnect-mcp -- -D warnings

# Format
cargo +nightly fmt --check

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.