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 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.

What it does not do

• It does not run shell 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 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.

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.

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 22 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 only safe mutating paths: dispatch dry-run, worker preflight, and Notion intake 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.
• 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.

License

MIT