mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-13 08:15:14 +02:00
feb0818444
Fixes a production crash-loop (PostHog issue 019eb68e): ktx mcp start --foreground on a uv-less container eagerly installed the managed Python runtime at boot, failed, and was restarted by its supervisor every ~62s (122 exceptions from one install). - MCP server factory now wires a lazy semantic-layer compute port that defers the runtime install to the first call, mirroring the already-lazy SQL-analysis port; the server boots and serves non-Python tools without the runtime. - ktx no longer requires uv on PATH: it downloads its own pinned, sha256-verified uv build under the runtime root (KTX_RUNTIME_ROOT aware), always musl-static on Linux. PATH uv is never consulted. - uv is acquired before the version dir is wiped, so a failed download cannot destroy an existing runtime. - Acquisition failures (offline, intercepted download, unsupported platform) throw KtxExpectedError and stay out of Error Tracking; a missing binary inside a checksum-verified archive remains a plain Error. - scripts/refresh-uv-manifest.mjs regenerates the pinned manifest (packages/cli/src/managed-uv-release.ts) on uv bumps. - Setup consent prompt now discloses the uv download; docs updated.
71 lines
2.6 KiB
Text
71 lines
2.6 KiB
Text
---
|
|
title: "ktx mcp"
|
|
description: "Run the ktx MCP HTTP server for agent clients."
|
|
---
|
|
|
|
`ktx mcp` starts, stops, inspects, and tails the local **ktx** MCP server for a **ktx**
|
|
project. Use it when an agent client connects through MCP instead of generated
|
|
CLI instructions.
|
|
|
|
## Command signature
|
|
|
|
```bash
|
|
ktx mcp <subcommand> [options]
|
|
```
|
|
|
|
## Subcommands
|
|
|
|
| Subcommand | Description |
|
|
|-----------|-------------|
|
|
| `start` | Start the **ktx** MCP HTTP server |
|
|
| `stop` | Stop the **ktx** MCP daemon |
|
|
| `status` | Show daemon status, URL, PID, token mode, and project path |
|
|
| `logs` | Print the daemon log |
|
|
|
|
## `mcp start` Options
|
|
|
|
| Flag | Description | Default |
|
|
|------|-------------|---------|
|
|
| `--host <host>` | Host to bind | `127.0.0.1` |
|
|
| `--port <n>` | Port to bind | `7878` |
|
|
| `--token <token>` | Bearer token for non-loopback binding | `KTX_MCP_TOKEN` |
|
|
| `--foreground` | Run the server in the foreground | `false` |
|
|
| `--allowed-host <host>` | Additional allowed Host header; repeatable | - |
|
|
| `--allowed-origin <origin>` | Allowed browser Origin header; repeatable | - |
|
|
|
|
## `mcp logs` Options
|
|
|
|
| Flag | Description | Default |
|
|
|------|-------------|---------|
|
|
| `--follow` | Follow log output | `false` |
|
|
|
|
## Examples
|
|
|
|
```bash
|
|
# Start the daemon on localhost
|
|
ktx mcp start
|
|
|
|
# Check status
|
|
ktx mcp status
|
|
|
|
# Tail logs
|
|
ktx mcp logs --follow
|
|
|
|
# Run in the foreground on a custom port
|
|
ktx mcp start --port 8787 --foreground
|
|
```
|
|
|
|
## Security notes
|
|
|
|
The default host is loopback-only. If you bind to a non-loopback host, configure
|
|
a bearer token with `--token <token>` or `KTX_MCP_TOKEN` and restrict allowed
|
|
hosts and origins for browser clients.
|
|
|
|
## Common errors
|
|
|
|
| Error | Cause | Recovery |
|
|
|-------|-------|----------|
|
|
| No **ktx** project found | Current directory has no `ktx.yaml` and `KTX_PROJECT_DIR` is unset | Run from a **ktx** project or pass `--project-dir <path>` |
|
|
| Non-loopback host rejected | The server needs token auth before binding beyond localhost | Pass `--token <token>` or set `KTX_MCP_TOKEN` |
|
|
| Client cannot connect | Host, port, token, allowed host, or allowed origin does not match the client | Check `ktx mcp status`, then restart with explicit `--host`, `--port`, `--allowed-host`, and `--allowed-origin` values |
|
|
| A Python-backed tool reports a runtime install failure | A tool that needs the managed Python runtime (metric compute, query-history SQL analysis) ran on a host that cannot reach `github.com` to download the pinned `uv` and Python | The server still starts and serves catalog and search tools. Restore network access and retry, or pre-build the runtime where network is available: `ktx admin runtime install --yes` |
|