# hydrolix/mcp-hydrolix architecture

> Architecture diagram of the GitHub repository hydrolix/mcp-hydrolix, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hydrolix/mcp-hydrolix
- Repository: https://github.com/hydrolix/mcp-hydrolix

## Overview

Hydrolix MCP Server exposes Hydrolix database operations as MCP tools. A client connects over stdio, HTTP, or SSE; the server handles database/table discovery and SQL queries, then returns results. Query handling also covers SQL text processing, table-column analysis, attribution, and result limits. Authentication and runtime configuration support the server, with optional HTTP serving and Prometheus metrics. The graph uses README capabilities and the supplied source excerpts and index; unsampled implementation details are represented only where documented.

Main entry points: [`mcp_hydrolix/mcp_server.py`](https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/mcp_server.py) (MCP server), [`mcp_hydrolix/main.py`](https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/main.py) (Server launcher), [`mcp_hydrolix/webapp.py`](https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/webapp.py) (HTTP app), [`mcp_hydrolix/column_analysis.py`](https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/column_analysis.py) (Column analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server runtime"]
  node_launcher["Server launcher<br/>[main.py]"]
  node_httpapp["HTTP app<br/>[webapp.py]"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
  node_middleware["HTTP middleware<br/>[middleware.py]"]
end

subgraph group_operations["Database operations"]
  node_discovery["Database discovery<br/>[mcp_server.py]"]
  node_tableinfo["Table metadata<br/>[mcp_server.py]"]
  node_select["Select query tool<br/>[mcp_server.py]"]
end

subgraph group_query["Query processing"]
  node_statement["SQL normalization<br/>[statement.py]"]
  node_columns["Column analysis<br/>[column_analysis.py]"]
  node_models["Result models<br/>[models.py]"]
end

subgraph group_support["Identity and observability"]
  node_config["Runtime config<br/>[mcp_env.py]"]
  node_auth["Authentication<br/>[mcp_providers.py]"]
  node_credentials["Credential resolution<br/>[__init__.py]"]
  node_attribution["Query attribution<br/>[attribution.py]"]
  node_requestattr["Request attribution"]
  node_metrics["Prometheus metrics<br/>[metrics.py]"]
  node_logging["Structured logging<br/>[log.py]"]
end

node_client(("MCP client"))
node_hydrolix[("Hydrolix cluster")]

node_client -->|"calls tools"| node_mcp
node_launcher -->|"starts HTTP"| node_httpapp
node_launcher -->|"runs stdio"| node_mcp
node_launcher -->|"reads config"| node_config
node_mcp -->|"queries cluster"| node_hydrolix
node_mcp -->|"dispatches"| node_discovery
node_mcp -->|"dispatches"| node_tableinfo
node_mcp -->|"dispatches"| node_select
node_select -.->|"normalizes SQL"| node_statement
node_select -->|"analyzes columns"| node_columns
node_columns -->|"classifies columns"| node_models
node_select -.->|"returns results"| node_models
node_mcp -->|"resolves credentials"| node_credentials
node_credentials -->|"uses providers"| node_auth
node_mcp -.->|"registers middleware"| node_requestattr
node_requestattr -->|"resolves fields"| node_attribution
node_mcp -.->|"adds query comment"| node_attribution
node_mcp -.->|"records metrics"| node_metrics
node_httpapp -.->|"configures middleware"| node_middleware
node_launcher -->|"sets up logging"| node_logging
node_metrics -->|"reads settings"| node_config

click node_launcher "https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/main.py"
click node_httpapp "https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/webapp.py"
click node_mcp "https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/mcp_server.py"
click node_config "https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/mcp_env.py"
click node_auth "https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/auth/mcp_providers.py"
click node_credentials "https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/auth/__init__.py"
click node_discovery "https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/mcp_server.py"
click node_tableinfo "https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/mcp_server.py"
click node_select "https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/mcp_server.py"
click node_statement "https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/statement.py"
click node_columns "https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/column_analysis.py"
click node_models "https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/models.py"
click node_attribution "https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/attribution.py"
click node_requestattr "https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/middlewares/request_attribution.py"
click node_metrics "https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/metrics.py"
click node_logging "https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/log/log.py"
click node_middleware "https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/middleware.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_launcher,node_httpapp,node_mcp,node_middleware,node_client toneBlue
class node_discovery,node_tableinfo,node_select,node_hydrolix toneAmber
class node_statement,node_columns,node_models toneMint
class node_config,node_auth,node_credentials,node_attribution,node_requestattr,node_metrics,node_logging toneRose
```

## Components

### Server runtime

- [Server launcher](https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/main.py): `mcp_hydrolix/main.py`
- [HTTP app](https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/webapp.py): `mcp_hydrolix/webapp.py`
- [MCP server](https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/mcp_server.py): `mcp_hydrolix/mcp_server.py`
- [HTTP middleware](https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/middleware.py): `mcp_hydrolix/middleware.py`

### Database operations

- [Database discovery](https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/mcp_server.py): `mcp_hydrolix/mcp_server.py`
- [Table metadata](https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/mcp_server.py): `mcp_hydrolix/mcp_server.py`
- [Select query tool](https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/mcp_server.py): `mcp_hydrolix/mcp_server.py`

### Query processing

- [SQL normalization](https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/statement.py): `mcp_hydrolix/statement.py`
- [Column analysis](https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/column_analysis.py): `mcp_hydrolix/column_analysis.py`
- [Result models](https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/models.py): `mcp_hydrolix/models.py`

### Identity and observability

- [Runtime config](https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/mcp_env.py): `mcp_hydrolix/mcp_env.py`
- [Authentication](https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/auth/mcp_providers.py): `mcp_hydrolix/auth/mcp_providers.py`
- [Credential resolution](https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/auth/__init__.py): `mcp_hydrolix/auth/__init__.py`
- [Query attribution](https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/attribution.py): `mcp_hydrolix/attribution.py`
- [Request attribution](https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/middlewares/request_attribution.py): `mcp_hydrolix/middlewares/request_attribution.py`
- [Prometheus metrics](https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/metrics.py): `mcp_hydrolix/metrics.py`
- [Structured logging](https://github.com/hydrolix/mcp-hydrolix/blob/main/mcp_hydrolix/log/log.py): `mcp_hydrolix/log/log.py`

### Other components

- **MCP client**
- **Hydrolix cluster**

## Connections

- MCP client → MCP server: calls tools (evidence: `README.md`)
- Server launcher → HTTP app: starts HTTP (evidence: `mcp_hydrolix/main.py`)
- Server launcher → MCP server: runs stdio (evidence: `mcp_hydrolix/main.py`)
- Server launcher → Runtime config: reads config (evidence: `mcp_hydrolix/main.py`)
- MCP server → Hydrolix cluster: queries cluster (evidence: `README.md`)
- MCP server → Database discovery: dispatches (evidence: `README.md`)
- MCP server → Table metadata: dispatches (evidence: `README.md`)
- MCP server → Select query tool: dispatches (evidence: `README.md`)
- Select query tool → SQL normalization: normalizes SQL (evidence: `mcp_hydrolix/mcp_server.py`)
- Select query tool → Column analysis: analyzes columns (evidence: `mcp_hydrolix/mcp_server.py`)
- Column analysis → Result models: classifies columns (evidence: `mcp_hydrolix/column_analysis.py`)
- Select query tool → Result models: returns results (evidence: `mcp_hydrolix/mcp_server.py`)
- MCP server → Credential resolution: resolves credentials (evidence: `mcp_hydrolix/mcp_server.py`)
- Credential resolution → Authentication: uses providers (evidence: `mcp_hydrolix/auth/__init__.py`)
- MCP server → Request attribution: registers middleware (evidence: `mcp_hydrolix/mcp_server.py`)
- Request attribution → Query attribution: resolves fields (evidence: `mcp_hydrolix/middlewares/request_attribution.py`)
- MCP server → Query attribution: adds query comment (evidence: `mcp_hydrolix/mcp_server.py`)
- MCP server → Prometheus metrics: records metrics (evidence: `mcp_hydrolix/mcp_server.py`)
- HTTP app → HTTP middleware: configures middleware (evidence: `mcp_hydrolix/webapp.py`)
- Server launcher → Structured logging: sets up logging (evidence: `mcp_hydrolix/main.py`)
- Prometheus metrics → Runtime config: reads settings (evidence: `mcp_hydrolix/metrics.py`)