mcp-hydrolix 0.1.4__tar.gz → 0.1.6__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- mcp_hydrolix-0.1.6/.dockerignore +13 -0
- mcp_hydrolix-0.1.6/.github/pull_request_template.md +26 -0
- mcp_hydrolix-0.1.6/.github/workflows/publish.yml +67 -0
- mcp_hydrolix-0.1.6/.github/workflows/tests.yaml +40 -0
- mcp_hydrolix-0.1.6/Dockerfile +49 -0
- mcp_hydrolix-0.1.4/README.md → mcp_hydrolix-0.1.6/PKG-INFO +86 -4
- mcp_hydrolix-0.1.4/PKG-INFO → mcp_hydrolix-0.1.6/README.md +61 -23
- mcp_hydrolix-0.1.6/docker-compose.yaml +56 -0
- mcp_hydrolix-0.1.6/fastmcp.json +13 -0
- mcp_hydrolix-0.1.6/mcp_hydrolix/auth/__init__.py +29 -0
- mcp_hydrolix-0.1.6/mcp_hydrolix/auth/credentials.py +63 -0
- mcp_hydrolix-0.1.6/mcp_hydrolix/auth/mcp_providers.py +137 -0
- mcp_hydrolix-0.1.6/mcp_hydrolix/log/__init__.py +6 -0
- mcp_hydrolix-0.1.6/mcp_hydrolix/log/log.py +60 -0
- mcp_hydrolix-0.1.6/mcp_hydrolix/log/log.yaml +40 -0
- mcp_hydrolix-0.1.6/mcp_hydrolix/log/utils.py +56 -0
- mcp_hydrolix-0.1.6/mcp_hydrolix/main.py +77 -0
- {mcp_hydrolix-0.1.4 → mcp_hydrolix-0.1.6}/mcp_hydrolix/mcp_env.py +142 -52
- mcp_hydrolix-0.1.6/mcp_hydrolix/mcp_server.py +321 -0
- mcp_hydrolix-0.1.6/mcp_hydrolix/utils.py +70 -0
- {mcp_hydrolix-0.1.4 → mcp_hydrolix-0.1.6}/pyproject.toml +12 -6
- mcp_hydrolix-0.1.6/test-services/docker-compose.yaml +30 -0
- mcp_hydrolix-0.1.6/tests/__init__.py +3 -0
- mcp_hydrolix-0.1.6/tests/test_log.py +338 -0
- {mcp_hydrolix-0.1.4 → mcp_hydrolix-0.1.6}/tests/test_mcp_server.py +143 -30
- {mcp_hydrolix-0.1.4 → mcp_hydrolix-0.1.6}/tests/test_tool.py +39 -30
- mcp_hydrolix-0.1.6/tests/test_utils.py +299 -0
- mcp_hydrolix-0.1.6/uv.lock +1929 -0
- mcp_hydrolix-0.1.4/.github/workflows/publish.yml +0 -18
- mcp_hydrolix-0.1.4/mcp_hydrolix/main.py +0 -21
- mcp_hydrolix-0.1.4/mcp_hydrolix/mcp_server.py +0 -268
- mcp_hydrolix-0.1.4/test-services/docker-compose.yaml +0 -15
- mcp_hydrolix-0.1.4/uv.lock +0 -1212
- {mcp_hydrolix-0.1.4 → mcp_hydrolix-0.1.6}/.editorconfig +0 -0
- {mcp_hydrolix-0.1.4 → mcp_hydrolix-0.1.6}/.gitignore +0 -0
- {mcp_hydrolix-0.1.4 → mcp_hydrolix-0.1.6}/.pre-commit-config.yaml +0 -0
- {mcp_hydrolix-0.1.4 → mcp_hydrolix-0.1.6}/.python-version +0 -0
- {mcp_hydrolix-0.1.4 → mcp_hydrolix-0.1.6}/LICENSE +0 -0
- {mcp_hydrolix-0.1.4 → mcp_hydrolix-0.1.6}/glama.json +0 -0
- {mcp_hydrolix-0.1.4 → mcp_hydrolix-0.1.6}/mcp_hydrolix/__init__.py +0 -0
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
What does this MR do?
|
|
2
|
+
-----------------------
|
|
3
|
+
|
|
4
|
+
Does this MR meet the acceptance criteria?
|
|
5
|
+
--------------------------------------------
|
|
6
|
+
|
|
7
|
+
* [ ] Documentation created/updated
|
|
8
|
+
* [ ] Tests added for this feature/bug
|
|
9
|
+
* [ ] Does this change request have any security impacts?
|
|
10
|
+
|
|
11
|
+
Release Notes
|
|
12
|
+
---------------------------------------------------
|
|
13
|
+
|
|
14
|
+
* Major changes:
|
|
15
|
+
*
|
|
16
|
+
* Minor changes:
|
|
17
|
+
*
|
|
18
|
+
* Bugfixes:
|
|
19
|
+
*
|
|
20
|
+
* Issues Closed:
|
|
21
|
+
*
|
|
22
|
+
* Security impacts identified:
|
|
23
|
+
*
|
|
24
|
+
|
|
25
|
+
Testing
|
|
26
|
+
--------------------------------------------
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
on:
|
|
2
|
+
workflow_dispatch:
|
|
3
|
+
inputs:
|
|
4
|
+
publish_pypi:
|
|
5
|
+
description: "Include a pypi push in this publish"
|
|
6
|
+
required: true
|
|
7
|
+
type: boolean
|
|
8
|
+
default: true
|
|
9
|
+
publish_docker:
|
|
10
|
+
description: "Include a docker push in this publish"
|
|
11
|
+
required: true
|
|
12
|
+
type: boolean
|
|
13
|
+
default: true
|
|
14
|
+
|
|
15
|
+
jobs:
|
|
16
|
+
publish:
|
|
17
|
+
name: Upload release to PyPI
|
|
18
|
+
runs-on: ubuntu-latest
|
|
19
|
+
if: ${{ inputs.publish_pypi }}
|
|
20
|
+
environment:
|
|
21
|
+
name: pypi
|
|
22
|
+
url: "https://pypi.org/p/mcp-hydrolix"
|
|
23
|
+
permissions:
|
|
24
|
+
id-token: write
|
|
25
|
+
steps:
|
|
26
|
+
- uses: actions/checkout@v5
|
|
27
|
+
- uses: astral-sh/setup-uv@v5
|
|
28
|
+
- run: uv python install
|
|
29
|
+
- run: uv build
|
|
30
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
31
|
+
publish-docker:
|
|
32
|
+
name: Upload release to GAR
|
|
33
|
+
runs-on: ubuntu-latest
|
|
34
|
+
if: ${{ inputs.publish_docker }}
|
|
35
|
+
steps:
|
|
36
|
+
- name: Checkout repository
|
|
37
|
+
uses: actions/checkout@v5
|
|
38
|
+
- name: Setup uv
|
|
39
|
+
uses: astral-sh/setup-uv@v5
|
|
40
|
+
- name: Authenticate GAR
|
|
41
|
+
uses: google-github-actions/auth@v3
|
|
42
|
+
with:
|
|
43
|
+
# Key ID: 98941823000cead5a61777398bd450e3e19539c3
|
|
44
|
+
credentials_json: ${{ secrets.GCP_GKE_CI_KEY }}
|
|
45
|
+
- name: "Set up GCP SDK" # needs to be done after google-github-actions/auth but before `gcloud auth configure-docker`
|
|
46
|
+
uses: google-github-actions/setup-gcloud@v3
|
|
47
|
+
- name: Configure GAR for docker
|
|
48
|
+
run: gcloud auth configure-docker us-docker.pkg.dev --quiet
|
|
49
|
+
- name: Get tag
|
|
50
|
+
id: get_tag
|
|
51
|
+
shell: bash
|
|
52
|
+
run: |
|
|
53
|
+
tag="v$(uv version --short)"
|
|
54
|
+
echo "::notice::Tag is $tag"
|
|
55
|
+
echo "tag=$tag" >> "$GITHUB_OUTPUT"
|
|
56
|
+
- name: Build docker image for MCP
|
|
57
|
+
shell: bash
|
|
58
|
+
run: |
|
|
59
|
+
docker buildx build \
|
|
60
|
+
-t us-docker.pkg.dev/hdx-art/t/mcp-hydrolix:${{ steps.get_tag.outputs.tag }} \
|
|
61
|
+
-t us-docker.pkg.dev/hdx-art/t/mcp-hydrolix:latest \
|
|
62
|
+
.
|
|
63
|
+
- name: Push docker image
|
|
64
|
+
shell: bash
|
|
65
|
+
run: |
|
|
66
|
+
docker push us-docker.pkg.dev/hdx-art/t/mcp-hydrolix:${{ steps.get_tag.outputs.tag }}
|
|
67
|
+
docker push us-docker.pkg.dev/hdx-art/t/mcp-hydrolix:latest
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
name: Tests Pipeline
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
pull_request:
|
|
5
|
+
paths:
|
|
6
|
+
- '.github/workflows/tests.yml'
|
|
7
|
+
- 'mcp_hydrolix/**'
|
|
8
|
+
- 'mcp_hydrolix/tests/**'
|
|
9
|
+
- 'mcp_hydrolix/pyproject.toml'
|
|
10
|
+
- 'mcp_hydrolix/ruff.toml'
|
|
11
|
+
- 'mcp_hydrolix/uv.lock'
|
|
12
|
+
- 'mcp_hydrolix/Dockerfile'
|
|
13
|
+
- 'mcp_hydrolix/docker-compose.yaml'
|
|
14
|
+
workflow_dispatch:
|
|
15
|
+
|
|
16
|
+
jobs:
|
|
17
|
+
core-test:
|
|
18
|
+
runs-on: ubuntu-latest
|
|
19
|
+
steps:
|
|
20
|
+
- uses: actions/checkout@v5
|
|
21
|
+
- uses: actions/setup-python@v6
|
|
22
|
+
with:
|
|
23
|
+
python-version: '3.13'
|
|
24
|
+
- name: Pre-commit
|
|
25
|
+
uses: pre-commit/action@v3.0.1
|
|
26
|
+
with:
|
|
27
|
+
extra_args: --all-files
|
|
28
|
+
- name: Build and run Docker Compose services
|
|
29
|
+
run: docker compose up -d --wait --wait-timeout 300
|
|
30
|
+
- name: Install uv
|
|
31
|
+
uses: astral-sh/setup-uv@v7
|
|
32
|
+
- name: Run tests
|
|
33
|
+
working-directory: .
|
|
34
|
+
run: |
|
|
35
|
+
uv sync --frozen --no-editable
|
|
36
|
+
uv pip install '.[dev]'
|
|
37
|
+
uv run pytest
|
|
38
|
+
- name: Stop Docker Compose services
|
|
39
|
+
if: always()
|
|
40
|
+
run: docker compose down
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# use the official uv image (with matching python/alpine version) to construct the venv
|
|
2
|
+
FROM ghcr.io/astral-sh/uv:0.9.4-python3.13-alpine AS builder
|
|
3
|
+
# # Install `cc` (to build lz4 from source)
|
|
4
|
+
RUN apk add build-base
|
|
5
|
+
|
|
6
|
+
WORKDIR /app
|
|
7
|
+
|
|
8
|
+
# dependencies specifications
|
|
9
|
+
COPY pyproject.toml /app/
|
|
10
|
+
COPY uv.lock /app/
|
|
11
|
+
# And because uv sync likes to verify the README... for some reason...
|
|
12
|
+
COPY README.md /app/
|
|
13
|
+
|
|
14
|
+
# produce .venv
|
|
15
|
+
RUN uv sync --locked
|
|
16
|
+
|
|
17
|
+
# begin definition of runtime container, relying on the venv made in builder
|
|
18
|
+
FROM python:3.13-alpine
|
|
19
|
+
|
|
20
|
+
# don't buffer log streams (docker adds enough delay)
|
|
21
|
+
ENV PYTHONUNBUFFERED=1
|
|
22
|
+
|
|
23
|
+
# don't cache pyc bytecode, since the container fs isn't persisted across restarts anyways
|
|
24
|
+
ENV PYTHONDONTWRITEBYTECODE=1
|
|
25
|
+
|
|
26
|
+
# Bind HTTP transport to all interfaces
|
|
27
|
+
ENV HYDROLIX_MCP_BIND_HOST=0.0.0.0
|
|
28
|
+
ENV HYDROLIX_MCP_SERVER_TRANSPORT=http
|
|
29
|
+
|
|
30
|
+
# declare that we expose port 8000
|
|
31
|
+
EXPOSE 8000
|
|
32
|
+
|
|
33
|
+
# Got a health check too
|
|
34
|
+
HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
|
|
35
|
+
CMD [ "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:8000/health" ]
|
|
36
|
+
|
|
37
|
+
RUN addgroup -g 1000 -S appgroup && \
|
|
38
|
+
adduser -u 1000 -S appuser -G appgroup -h /app -s /sbin/nologin
|
|
39
|
+
USER appuser
|
|
40
|
+
|
|
41
|
+
WORKDIR /app
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
COPY --from=builder --chown=appuser:appgroup /app/.venv/ /app/.venv
|
|
45
|
+
|
|
46
|
+
COPY --chown=appuser:appgroup mcp_hydrolix/ /app/mcp_hydrolix
|
|
47
|
+
COPY --chown=appuser:appgroup pyproject.toml /app/
|
|
48
|
+
|
|
49
|
+
ENTRYPOINT [".venv/bin/python", "-m", "mcp_hydrolix.main"]
|
|
@@ -1,3 +1,28 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: mcp-hydrolix
|
|
3
|
+
Version: 0.1.6
|
|
4
|
+
Summary: An MCP server for Hydrolix.
|
|
5
|
+
Project-URL: Home, https://github.com/hydrolix/mcp-hydrolix
|
|
6
|
+
License-Expression: Apache-2.0
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Requires-Python: >=3.13
|
|
9
|
+
Requires-Dist: clickhouse-connect<0.11,>=0.10
|
|
10
|
+
Requires-Dist: fastmcp<2.15,>=2.14
|
|
11
|
+
Requires-Dist: gunicorn<24.0,>=23.0
|
|
12
|
+
Requires-Dist: pip-system-certs<5.0,>=4.0
|
|
13
|
+
Requires-Dist: pyjwt<2.11,>=2.10
|
|
14
|
+
Requires-Dist: python-dotenv<1.2,>=1.1
|
|
15
|
+
Provides-Extra: dev
|
|
16
|
+
Requires-Dist: fastapi>=0.124; extra == 'dev'
|
|
17
|
+
Requires-Dist: mcp-clickhouse==0.1.13; extra == 'dev'
|
|
18
|
+
Requires-Dist: pre-commit; extra == 'dev'
|
|
19
|
+
Requires-Dist: pytest; extra == 'dev'
|
|
20
|
+
Requires-Dist: pytest-asyncio; extra == 'dev'
|
|
21
|
+
Requires-Dist: pytest-repeat; extra == 'dev'
|
|
22
|
+
Requires-Dist: pytest-xdist; extra == 'dev'
|
|
23
|
+
Requires-Dist: ruff; extra == 'dev'
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
|
|
1
26
|
# Hydrolix MCP Server
|
|
2
27
|
|
|
3
28
|
[](https://pypi.org/project/mcp-hydrolix)
|
|
@@ -45,6 +70,18 @@ The Hydrolix MCP server is configured using a standard MCP server entry. Consult
|
|
|
45
70
|
|
|
46
71
|
The recommended way to launch the Hydrolix MCP server is via the [`uv` project manager](https://github.com/astral-sh/uv), which will manage installing all other dependencies in an isolated environment.
|
|
47
72
|
|
|
73
|
+
### Authentication
|
|
74
|
+
|
|
75
|
+
The server supports multiple authentication methods with the following precedence (highest to lowest):
|
|
76
|
+
|
|
77
|
+
1. **Per-request Bearer token**: Service account token provided via `Authorization: Bearer <token>` header
|
|
78
|
+
2. **Per-request GET parameter**: Service account token provided via `?token=<token>` query parameter
|
|
79
|
+
3. **Environment-based credentials**: Credentials configured via environment variables
|
|
80
|
+
- Service account token (`HYDROLIX_TOKEN`), or
|
|
81
|
+
- Username and password (`HYDROLIX_USER` and `HYDROLIX_PASSWORD`)
|
|
82
|
+
|
|
83
|
+
When multiple authentication methods are configured, the server will use the first available method in the precedence order above. Per-request authentication is only available when using HTTP or SSE transport modes.
|
|
84
|
+
|
|
48
85
|
MCP Server definition using username and password (JSON):
|
|
49
86
|
|
|
50
87
|
```json
|
|
@@ -180,17 +217,37 @@ To leverage service account use the following config block:
|
|
|
180
217
|
|
|
181
218
|
5. Restart Claude Desktop to apply the changes. If you are using Windows, ensure Claude is stopped completely by closing the client using the system tray icon.
|
|
182
219
|
|
|
220
|
+
### Configuration Example (Claude Code)
|
|
221
|
+
|
|
222
|
+
To configure the Hydrolix MCP server for Claude Code, run the following command:
|
|
223
|
+
|
|
224
|
+
```bash
|
|
225
|
+
claude mcp add --transport stdio hydrolix \
|
|
226
|
+
--env HYDROLIX_USER=<hydrolix-user> \
|
|
227
|
+
--env HYDROLIX_PASSWORD=<hydrolix-password> \
|
|
228
|
+
--env HYDROLIX_HOST=<hydrolix-host> \
|
|
229
|
+
--env HYDROLIX_MCP_SERVER_TRANSPORT=stdio \
|
|
230
|
+
-- uv run --with mcp-hydrolix --python 3.13 mcp-hydrolix
|
|
231
|
+
```
|
|
232
|
+
|
|
183
233
|
### Environment Variables
|
|
184
234
|
|
|
185
235
|
The following variables are used to configure the Hydrolix connection. These variables may be provided via the MCP config block (as shown above), a `.env` file, or traditional environment variables.
|
|
186
236
|
|
|
187
237
|
#### Required Variables
|
|
188
238
|
* `HYDROLIX_HOST`: The hostname of your Hydrolix server
|
|
189
|
-
* `HYDROLIX_TOKEN`: The Hydrolix service account token (omit if using username/password)
|
|
190
|
-
* `HYDROLIX_USER`: The username for authentication (omit if using service account)
|
|
191
|
-
* `HYDROLIX_PASSWORD`: The password for authentication (omit if using service account)
|
|
192
239
|
|
|
193
|
-
|
|
240
|
+
#### Authentication Variables
|
|
241
|
+
At least one authentication method must be configured when using the stdio transport:
|
|
242
|
+
|
|
243
|
+
* `HYDROLIX_TOKEN`: Service account token for environment-based authentication
|
|
244
|
+
* `HYDROLIX_USER` and `HYDROLIX_PASSWORD`: Username and password for environment-based authentication (both must be provided together)
|
|
245
|
+
|
|
246
|
+
In summary:
|
|
247
|
+
- For stdio, you MUST use HYDROLIX_TOKEN or HYDROLIX_USER+HYDROLIX_PASS (environmental credentials)
|
|
248
|
+
- For http/sse, you MAY use HYDROLIX_TOKEN or HYDROLIX_USER+HYDROLIX_PASS (environmental credentials), but you may instead use per-request credentials.
|
|
249
|
+
|
|
250
|
+
If no credentials are provided via the environment or the request, the request will fail.
|
|
194
251
|
|
|
195
252
|
#### Optional Variables
|
|
196
253
|
* `HYDROLIX_PORT`: The port number of your Hydrolix server
|
|
@@ -229,4 +286,29 @@ When using HTTP transport, the server will run on the configured port (default 8
|
|
|
229
286
|
- MCP endpoint: `http://localhost:4200/mcp`
|
|
230
287
|
- Health check: `http://localhost:4200/health`
|
|
231
288
|
|
|
289
|
+
#### Using Per-Request Authentication with HTTP Transport
|
|
290
|
+
|
|
291
|
+
When using HTTP or SSE transport, you can omit environment-based credentials and instead provide authentication per-request. This is useful for multi-user scenarios or with clients that don't support running MCP servers locally.
|
|
292
|
+
|
|
293
|
+
Example `mcpServers` configuration connecting to a remote HTTP server with per-request authentication:
|
|
294
|
+
|
|
295
|
+
```json
|
|
296
|
+
{
|
|
297
|
+
"mcpServers": {
|
|
298
|
+
"mcp-hydrolix-remote": {
|
|
299
|
+
"url": "http://my-hydrolix-mcp.example.com:8000/mcp?token=<service-account-token>"
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
}
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
Example minimal `.env` configuration for running your own HTTP server without environment credentials:
|
|
306
|
+
|
|
307
|
+
```env
|
|
308
|
+
HYDROLIX_HOST=my-cluster.hydrolix.net
|
|
309
|
+
HYDROLIX_MCP_SERVER_TRANSPORT=http
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
Though not part of the MCP specification, many MCP clients allow adding headers to MCP-issued requests. When this is possible, we recommend configuring the MCP client to pass a service account token via the `Authorization: Bearer <sa-token-here>` header instead of as a query parameter for greater security.
|
|
313
|
+
|
|
232
314
|
Note: The bind host and port settings are only used when transport is set to "http" or "sse".
|
|
@@ -1,22 +1,3 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: mcp-hydrolix
|
|
3
|
-
Version: 0.1.4
|
|
4
|
-
Summary: An MCP server for Hydrolix.
|
|
5
|
-
Project-URL: Home, https://github.com/hydrolix/mcp-hydrolix
|
|
6
|
-
License-Expression: Apache-2.0
|
|
7
|
-
License-File: LICENSE
|
|
8
|
-
Requires-Python: >=3.13
|
|
9
|
-
Requires-Dist: clickhouse-connect>=0.8.16
|
|
10
|
-
Requires-Dist: fastmcp>=2.0.0
|
|
11
|
-
Requires-Dist: pip-system-certs>=4.0
|
|
12
|
-
Requires-Dist: python-dotenv>=1.0.1
|
|
13
|
-
Provides-Extra: dev
|
|
14
|
-
Requires-Dist: pre-commit; extra == 'dev'
|
|
15
|
-
Requires-Dist: pytest; extra == 'dev'
|
|
16
|
-
Requires-Dist: pytest-asyncio; extra == 'dev'
|
|
17
|
-
Requires-Dist: ruff; extra == 'dev'
|
|
18
|
-
Description-Content-Type: text/markdown
|
|
19
|
-
|
|
20
1
|
# Hydrolix MCP Server
|
|
21
2
|
|
|
22
3
|
[](https://pypi.org/project/mcp-hydrolix)
|
|
@@ -64,6 +45,18 @@ The Hydrolix MCP server is configured using a standard MCP server entry. Consult
|
|
|
64
45
|
|
|
65
46
|
The recommended way to launch the Hydrolix MCP server is via the [`uv` project manager](https://github.com/astral-sh/uv), which will manage installing all other dependencies in an isolated environment.
|
|
66
47
|
|
|
48
|
+
### Authentication
|
|
49
|
+
|
|
50
|
+
The server supports multiple authentication methods with the following precedence (highest to lowest):
|
|
51
|
+
|
|
52
|
+
1. **Per-request Bearer token**: Service account token provided via `Authorization: Bearer <token>` header
|
|
53
|
+
2. **Per-request GET parameter**: Service account token provided via `?token=<token>` query parameter
|
|
54
|
+
3. **Environment-based credentials**: Credentials configured via environment variables
|
|
55
|
+
- Service account token (`HYDROLIX_TOKEN`), or
|
|
56
|
+
- Username and password (`HYDROLIX_USER` and `HYDROLIX_PASSWORD`)
|
|
57
|
+
|
|
58
|
+
When multiple authentication methods are configured, the server will use the first available method in the precedence order above. Per-request authentication is only available when using HTTP or SSE transport modes.
|
|
59
|
+
|
|
67
60
|
MCP Server definition using username and password (JSON):
|
|
68
61
|
|
|
69
62
|
```json
|
|
@@ -199,17 +192,37 @@ To leverage service account use the following config block:
|
|
|
199
192
|
|
|
200
193
|
5. Restart Claude Desktop to apply the changes. If you are using Windows, ensure Claude is stopped completely by closing the client using the system tray icon.
|
|
201
194
|
|
|
195
|
+
### Configuration Example (Claude Code)
|
|
196
|
+
|
|
197
|
+
To configure the Hydrolix MCP server for Claude Code, run the following command:
|
|
198
|
+
|
|
199
|
+
```bash
|
|
200
|
+
claude mcp add --transport stdio hydrolix \
|
|
201
|
+
--env HYDROLIX_USER=<hydrolix-user> \
|
|
202
|
+
--env HYDROLIX_PASSWORD=<hydrolix-password> \
|
|
203
|
+
--env HYDROLIX_HOST=<hydrolix-host> \
|
|
204
|
+
--env HYDROLIX_MCP_SERVER_TRANSPORT=stdio \
|
|
205
|
+
-- uv run --with mcp-hydrolix --python 3.13 mcp-hydrolix
|
|
206
|
+
```
|
|
207
|
+
|
|
202
208
|
### Environment Variables
|
|
203
209
|
|
|
204
210
|
The following variables are used to configure the Hydrolix connection. These variables may be provided via the MCP config block (as shown above), a `.env` file, or traditional environment variables.
|
|
205
211
|
|
|
206
212
|
#### Required Variables
|
|
207
213
|
* `HYDROLIX_HOST`: The hostname of your Hydrolix server
|
|
208
|
-
* `HYDROLIX_TOKEN`: The Hydrolix service account token (omit if using username/password)
|
|
209
|
-
* `HYDROLIX_USER`: The username for authentication (omit if using service account)
|
|
210
|
-
* `HYDROLIX_PASSWORD`: The password for authentication (omit if using service account)
|
|
211
214
|
|
|
212
|
-
|
|
215
|
+
#### Authentication Variables
|
|
216
|
+
At least one authentication method must be configured when using the stdio transport:
|
|
217
|
+
|
|
218
|
+
* `HYDROLIX_TOKEN`: Service account token for environment-based authentication
|
|
219
|
+
* `HYDROLIX_USER` and `HYDROLIX_PASSWORD`: Username and password for environment-based authentication (both must be provided together)
|
|
220
|
+
|
|
221
|
+
In summary:
|
|
222
|
+
- For stdio, you MUST use HYDROLIX_TOKEN or HYDROLIX_USER+HYDROLIX_PASS (environmental credentials)
|
|
223
|
+
- For http/sse, you MAY use HYDROLIX_TOKEN or HYDROLIX_USER+HYDROLIX_PASS (environmental credentials), but you may instead use per-request credentials.
|
|
224
|
+
|
|
225
|
+
If no credentials are provided via the environment or the request, the request will fail.
|
|
213
226
|
|
|
214
227
|
#### Optional Variables
|
|
215
228
|
* `HYDROLIX_PORT`: The port number of your Hydrolix server
|
|
@@ -248,4 +261,29 @@ When using HTTP transport, the server will run on the configured port (default 8
|
|
|
248
261
|
- MCP endpoint: `http://localhost:4200/mcp`
|
|
249
262
|
- Health check: `http://localhost:4200/health`
|
|
250
263
|
|
|
264
|
+
#### Using Per-Request Authentication with HTTP Transport
|
|
265
|
+
|
|
266
|
+
When using HTTP or SSE transport, you can omit environment-based credentials and instead provide authentication per-request. This is useful for multi-user scenarios or with clients that don't support running MCP servers locally.
|
|
267
|
+
|
|
268
|
+
Example `mcpServers` configuration connecting to a remote HTTP server with per-request authentication:
|
|
269
|
+
|
|
270
|
+
```json
|
|
271
|
+
{
|
|
272
|
+
"mcpServers": {
|
|
273
|
+
"mcp-hydrolix-remote": {
|
|
274
|
+
"url": "http://my-hydrolix-mcp.example.com:8000/mcp?token=<service-account-token>"
|
|
275
|
+
}
|
|
276
|
+
}
|
|
277
|
+
}
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
Example minimal `.env` configuration for running your own HTTP server without environment credentials:
|
|
281
|
+
|
|
282
|
+
```env
|
|
283
|
+
HYDROLIX_HOST=my-cluster.hydrolix.net
|
|
284
|
+
HYDROLIX_MCP_SERVER_TRANSPORT=http
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
Though not part of the MCP specification, many MCP clients allow adding headers to MCP-issued requests. When this is possible, we recommend configuring the MCP client to pass a service account token via the `Authorization: Bearer <sa-token-here>` header instead of as a query parameter for greater security.
|
|
288
|
+
|
|
251
289
|
Note: The bind host and port settings are only used when transport is set to "http" or "sse".
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
version: '3.8'
|
|
2
|
+
|
|
3
|
+
services:
|
|
4
|
+
clickhouse:
|
|
5
|
+
image: clickhouse/clickhouse-server:latest
|
|
6
|
+
container_name: hydrolix-test-clickhouse
|
|
7
|
+
ports:
|
|
8
|
+
- "9000:9000" # Native protocol
|
|
9
|
+
- "8123:8123" # HTTP interface
|
|
10
|
+
environment:
|
|
11
|
+
CLICKHOUSE_DB: default
|
|
12
|
+
CLICKHOUSE_USER: default
|
|
13
|
+
CLICKHOUSE_PASSWORD: clickhouse
|
|
14
|
+
CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
|
|
15
|
+
TEST_CONFIG: |+
|
|
16
|
+
<?xml version="1.0" ?>
|
|
17
|
+
<clickhouse>
|
|
18
|
+
<max_connections>4096</max_connections>
|
|
19
|
+
<logger>
|
|
20
|
+
<console>1</console>
|
|
21
|
+
</logger>
|
|
22
|
+
<timezone>UTC</timezone>
|
|
23
|
+
<custom_settings_prefixes replace="replace">SQL_,hdx_</custom_settings_prefixes>
|
|
24
|
+
</clickhouse>
|
|
25
|
+
entrypoint:
|
|
26
|
+
- /bin/bash
|
|
27
|
+
- -c
|
|
28
|
+
- |
|
|
29
|
+
$(echo "$$TEST_CONFIG" > /etc/clickhouse-server/config.d/tcconfig.xml)
|
|
30
|
+
exec /entrypoint.sh "$@"
|
|
31
|
+
volumes:
|
|
32
|
+
- clickhouse_data:/var/lib/clickhouse
|
|
33
|
+
- clickhouse_logs:/var/log/clickhouse-server
|
|
34
|
+
# Optional: mount custom config
|
|
35
|
+
# - ./clickhouse-config.xml:/etc/clickhouse-server/config.d/custom.xml
|
|
36
|
+
ulimits:
|
|
37
|
+
nofile:
|
|
38
|
+
soft: 262144
|
|
39
|
+
hard: 262144
|
|
40
|
+
healthcheck:
|
|
41
|
+
test: ["CMD", "clickhouse-client", "--query", "SELECT 1"]
|
|
42
|
+
interval: 10s
|
|
43
|
+
timeout: 5s
|
|
44
|
+
retries: 5
|
|
45
|
+
networks:
|
|
46
|
+
- hydrolix-test
|
|
47
|
+
|
|
48
|
+
volumes:
|
|
49
|
+
clickhouse_data:
|
|
50
|
+
driver: local
|
|
51
|
+
clickhouse_logs:
|
|
52
|
+
driver: local
|
|
53
|
+
|
|
54
|
+
networks:
|
|
55
|
+
hydrolix-test:
|
|
56
|
+
driver: bridge
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
|
|
3
|
+
"source": {
|
|
4
|
+
"type": "filesystem",
|
|
5
|
+
"path": "mcp_hydrolix/mcp_server.py",
|
|
6
|
+
"entrypoint": "mcp"
|
|
7
|
+
},
|
|
8
|
+
"environment": {
|
|
9
|
+
"type": "uv",
|
|
10
|
+
"python": ">=3.13",
|
|
11
|
+
"editable": ["."]
|
|
12
|
+
}
|
|
13
|
+
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
"""Authentication package for MCP Hydrolix.
|
|
2
|
+
|
|
3
|
+
This package contains authentication-related types used to define hydrolix auth
|
|
4
|
+
in terms of FastMCP infrastructure
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from mcp_hydrolix.auth.credentials import (
|
|
8
|
+
HydrolixCredential,
|
|
9
|
+
ServiceAccountToken,
|
|
10
|
+
UsernamePassword,
|
|
11
|
+
)
|
|
12
|
+
from mcp_hydrolix.auth.mcp_providers import (
|
|
13
|
+
TOKEN_PARAM,
|
|
14
|
+
AccessToken,
|
|
15
|
+
ChainedAuthBackend,
|
|
16
|
+
GetParamAuthBackend,
|
|
17
|
+
HydrolixCredentialChain,
|
|
18
|
+
)
|
|
19
|
+
|
|
20
|
+
__all__ = [
|
|
21
|
+
"HydrolixCredential",
|
|
22
|
+
"ServiceAccountToken",
|
|
23
|
+
"UsernamePassword",
|
|
24
|
+
"AccessToken",
|
|
25
|
+
"ChainedAuthBackend",
|
|
26
|
+
"GetParamAuthBackend",
|
|
27
|
+
"HydrolixCredentialChain",
|
|
28
|
+
"TOKEN_PARAM",
|
|
29
|
+
]
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
"""Hydrolix credential types for authentication."""
|
|
2
|
+
|
|
3
|
+
from abc import ABC, abstractmethod
|
|
4
|
+
from dataclasses import dataclass
|
|
5
|
+
from typing import Optional
|
|
6
|
+
import jwt
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
class HydrolixCredential(ABC):
|
|
10
|
+
@abstractmethod
|
|
11
|
+
def clickhouse_config_entries(self) -> dict:
|
|
12
|
+
"""
|
|
13
|
+
Returns the entries needed for a ClickHouse client config to use this credential.
|
|
14
|
+
This will typically add `access_token` or (`username` and `password`)
|
|
15
|
+
"""
|
|
16
|
+
...
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
@dataclass
|
|
20
|
+
class ServiceAccountToken(HydrolixCredential):
|
|
21
|
+
"""Hydrolix credentials using a service account token."""
|
|
22
|
+
|
|
23
|
+
def __init__(self, token: str, expected_iss: Optional[str]):
|
|
24
|
+
"""
|
|
25
|
+
Initialize a ServiceAccountToken from a token JWT (or raise an error if the claims are invalid).
|
|
26
|
+
NB the claims' signatures are NOT checked by this function -- these validations MUST NOT be considered
|
|
27
|
+
authoritative.
|
|
28
|
+
"""
|
|
29
|
+
|
|
30
|
+
claims = jwt.decode(
|
|
31
|
+
token,
|
|
32
|
+
key="", # NB service account signing key is not publicly-hosted, so we can't verify the signature
|
|
33
|
+
options={
|
|
34
|
+
"verify_signature": False,
|
|
35
|
+
"verify_iss": True,
|
|
36
|
+
"verify_iat": True,
|
|
37
|
+
"verify_exp": True,
|
|
38
|
+
},
|
|
39
|
+
issuer=expected_iss,
|
|
40
|
+
)
|
|
41
|
+
self.token = token
|
|
42
|
+
self.service_account_id = claims["sub"]
|
|
43
|
+
self.issued_at = claims["iss"]
|
|
44
|
+
self.expires_at = claims["exp"]
|
|
45
|
+
|
|
46
|
+
def clickhouse_config_entries(self) -> dict:
|
|
47
|
+
return {"access_token": self.token}
|
|
48
|
+
|
|
49
|
+
token: str
|
|
50
|
+
service_account_id: str
|
|
51
|
+
issued_at: int
|
|
52
|
+
expires_at: int
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
@dataclass
|
|
56
|
+
class UsernamePassword(HydrolixCredential):
|
|
57
|
+
"""Hydrolix credentials using username and password."""
|
|
58
|
+
|
|
59
|
+
def clickhouse_config_entries(self) -> dict:
|
|
60
|
+
return {"username": self.username, "password": self.password}
|
|
61
|
+
|
|
62
|
+
username: str
|
|
63
|
+
password: str
|