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.

Enoch system repo · Docs · MCP

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.

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

... View full README on GitHub