enoch-mcp

enoch-mcp is a local Model Context Protocol stdio server for a configured Enoch FastAPI control-plane API. It lets MCP clients inspect and operate Enoch through typed tools without exposing a raw shell or reimplementing Enoch business logic.

What it does

• Registers MCP tools for Enoch control-plane, Dashboard V1, and core endpoints.

• Sends requests to a configured Enoch API URL.

• Adds Authorization: Bearer <token> to API requests using the configured token.

• Returns Enoch API responses to the MCP client.

• Marks read-only tools with MCP read-only annotations.

• Marks mutating tools as non-read-only and adds approval metadata.

• Keeps safe defaults for dry-run operations.

• Optionally probes configured CPU/GPU workers directly through worker APIs or allowlisted SSH diagnostics.

Related MCP server: JSON-RPC

What it does not do

• It does not expose a raw shell tool.

• It does not accept arbitrary SSH commands.

• It does not read or write local artifact files directly.

• It does not call language models.

• It does not cache, retry, queue, or schedule work.

• It does not bypass Enoch authentication or authorization.

Requirements

• Python 3.11 or newer

• A running Enoch API, normally at http://localhost:8787

• An Enoch API bearer token

• An MCP client that can run local stdio servers

Installation

Run from PyPI with uvx:

uvx enoch-mcp --api-url http://localhost:8787 --api-token '<token>'

Or configure with environment variables:

export ENOCH_API_URL='http://localhost:8787'
export ENOCH_API_TOKEN='<token>'
uvx enoch-mcp

For local development from a checkout:

git clone https://github.com/alias8818/enoch-mcp.git
cd enoch-mcp
uv sync --dev
uv run enoch-mcp --api-url http://localhost:8787 --api-token '<token>'

Configuration

The token is required. If it is missing, tool calls fail before making an HTTP request.

Optional worker probes

Worker probes are disabled unless ENOCH_WORKER_PROBES_JSON or ENOCH_WORKER_PROBES_FILE is configured. This keeps the default package a thin control-plane bridge. When configured, the MCP exposes named diagnostics for worker truth: API health, worker-gate dashboard status, active process markers, bounded log tails, disk space, and expected artifact presence.

Example:

{
  "cpu": {
    "api_url": "http://127.0.0.1:18788",
    "api_token": "worker-api-token",
    "service_name": "enoch-control-plane",
    "project_root": "/srv/enoch/projects"
  },
  "gpu": {
    "api_url": "http://127.0.0.1:18789",
    "api_token": "worker-api-token",
    "ssh_host": "worker-gpu.example.internal",
    "ssh_user": "enoch",
    "service_name": "enoch-control-plane",
    "project_root": "/srv/enoch/projects",
    "log_paths": ["/var/log/enoch-control-plane.log"]
  }
}

Supported fields per lane:

• api_url: worker-gate base URL. Used first for /healthz, /dashboard/api, /dashboard/api/run/{run_id}, and /project-status/{project_id}.

• api_token: worker bearer token. Treated as secret.

• ssh_host, ssh_user, ssh_port: optional SSH fallback/debug target.

• service_name: systemd unit name for service checks and journal tails.

• project_root, state_dir: fixed worker roots used for disk and artifact checks.

• log_paths: fixed worker-gate log paths that may be tailed.

SSH probes only run fixed diagnostic commands. They do not accept arbitrary shell input from the MCP client. User-supplied IDs are limited to safe run/project identifier characters, log output is bounded, SSH uses batch mode and no stdin, and the recommended deployment is a read-only worker user or forced-command policy.

MCP client setup

Claude Desktop

{
  "mcpServers": {
    "enoch": {
      "command": "uvx",
      "args": ["enoch-mcp"],
      "env": {
        "ENOCH_API_URL": "http://localhost:8787",
        "ENOCH_API_TOKEN": "replace-with-token"
      }
    }
  }
}

For local development, point the MCP client at the checkout:

{
  "mcpServers": {
    "enoch": {
      "command": "uv",
      "args": ["--directory", "/path/to/enoch-mcp", "run", "enoch-mcp"],
      "env": {
        "ENOCH_API_URL": "http://localhost:8787",
        "ENOCH_API_TOKEN": "replace-with-token"
      }
    }
  }
}

Use the equivalent local stdio-server settings for Cursor, Copilot, Windsurf, or other MCP clients.

Development

uv sync --dev
uv run pytest -q
gitleaks detect --no-git --redact

Public-safety note

This package is public. Examples must use placeholders and local URLs only. Do not publish private hostnames, LAN/Tailscale IPs, operator paths, or live tokens.