enoch-mcp

enoch-mcp is a local Model Context Protocol (MCP) stdio server for the Enoch FastAPI control-plane API. It lets MCP clients such as Claude Desktop, Cursor, Copilot, and Windsurf inspect and operate a running Enoch instance through tools.

This MCP server is built for the Enoch project: alias8818/enoch-agentic-research-system.

This package is a thin HTTP bridge. It does not reimplement 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 every API request.

• 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 run shell commands.

• It does not expose a raw shell tool, even when SSH worker probes are configured.

• 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 add telemetry or analytics.

• 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, wake-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"
  },
  "gb10": {
    "api_url": "http://127.0.0.1:18789",
    "api_token": "worker-api-token",
    "ssh_host": "100.92.44.26",
    "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 wake-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 wake-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

Add an entry like this to claude_desktop_config.json:

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

For local development, point Claude Desktop 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"
      }
    }
  }
}

Cursor

Add an MCP server entry that runs the same stdio command:

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

Use the equivalent MCP server settings for other clients that support local stdio MCP servers.

Codex on the Enoch workstation

For this workstation, use the repo wrapper so Codex does not store the Enoch bearer token directly. The wrapper starts or reuses an SSH tunnel to enoch-core.exe.xyz, reads the control-plane token on the remote host, and then runs this checkout over stdio:

[mcp_servers.enoch]
command = "/home/jeremy/Desktop/projects/enoch-release/enoch-mcp/scripts/run_codex_mcp.sh"
startup_timeout_sec = 60.0

The wrapper honors these optional environment overrides:

• ENOCH_MCP_SSH_HOST default enoch-core.exe.xyz

• ENOCH_MCP_LOCAL_PORT default 18787

• ENOCH_MCP_REMOTE_PORT default 8787

• ENOCH_MCP_ENABLE_WORKER_PROBES default 1

• ENOCH_MCP_WORKER_BASE_PORT default 18788

When worker probes are enabled, the wrapper reads configured Enoch worker_targets on enoch-core, opens local SSH tunnels for each worker API, and exports ENOCH_WORKER_PROBES_JSON for this MCP process. The Codex config still does not store the control-plane or worker bearer tokens.

Tools

Read-only tools

These tools are registered with readOnlyHint=true.

Mutating tools

These tools are registered as non-read-only and include userApproval metadata. MCP annotations and metadata are hints to clients; confirmation behavior depends on the MCP client.

Live smoke test

A live smoke script is included for checking a running Enoch instance before publishing or changing client configuration:

ENOCH_API_TOKEN='<token>' uv run python scripts/live_smoke.py --api-url http://localhost:8787

The script:

• verifies that the expected tools are registered;

• verifies approval metadata on mutating tools;

• calls read-only tools against the configured Enoch API;

• reads one paper detail and one artifact when available;

• calls direct worker probes only when worker probe config is present;

• calls only safe mutating paths by default: dispatch dry-runs, queue alert dry-run, stale-lane reconcile dry-run, research cycle dry-run, follow-up dry-run, worker preflight, idea intake dry-run, legacy Notion intake dry-run when enabled, and paper draft dry-run.

It does not print the bearer token.

Development

uv sync --dev
uv run ruff check .
uv run pytest
uv build

Run the MCP server from a checkout:

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

The server uses stdio transport, so it waits for MCP protocol messages on standard input.

Error handling

• HTTP 4xx/5xx responses from Enoch are returned as MCP tool errors that include the status code and response body.

• Network failures are returned as transport errors.

• Missing bearer tokens are reported before a request is sent.

Security notes

• Treat ENOCH_API_TOKEN like any other credential.

• Treat ENOCH_WORKER_PROBES_JSON like a credential when it includes worker API tokens.

• Prefer environment variables or your MCP client's secret storage over hard-coded tokens.

• Do not expose an Enoch API endpoint to networks or users that should not operate the control plane.

• Mutating tool approval prompts are MCP-client dependent; review your client behavior before enabling mutating workflows.

• Worker SSH diagnostics are named probes with fixed commands, not a general remote shell. Use a dedicated read-only/forced-command SSH identity when possible.

License

MIT