Skip to main content
Glama

Helix

Anthropic-Compatible Gateway • Higgsfield-Backed MCP Generation Server

TypeScript Node MCP Coverage Docker License: MIT



⚑ What is Helix?

Helix unites local LLM intelligence with cloud-grade generative media production through two complementary surfaces:

  1. The Anthropic Gateway: An endpoint implementing the full Anthropic Messages contract (/v1/messages). Point Claude Code, the Anthropic TypeScript/Python SDK, or Claude.ai at your local models (Ollama, vLLM, llama.cpp) with 100% wire fidelityβ€”including streaming SSE events, reasoning tokens, tool calls, and synthetic thinking signatures.

  2. The Higgsfield MCP Server: A Streamable HTTP Model Context Protocol server exposing Higgsfield's image and video generation engines (Seedance 2.5, Cinema Studio 4.0, DoP, Kling) directly to any MCP-compliant client with OAuth 2.1 authentication and atomic budget controls.

  3. Studio Mode (The Autonomous Loop): Configure your local LLM as an autonomous creative director. The gateway intercepts creative requests, offers Higgsfield MCP tools, dispatches generation jobs, monitors progress, and streams back the finished media seamlessly.


Related MCP server: maginary-mcp

🌟 Key Highlights

  • 🎯 Drop-in Anthropic Wire Protocol: Faithfully mirrors POST /v1/messages and GET /v1/models. Matches upstream error shapes, token-counting logic, cache-breakpoint tracking, and SSE frame ordering (message_start, content_block_delta, message_delta, message_stop).

  • 🎬 Dual-Era MCP Generation: Automatically negotiates modern 2026-07-28 (stateless, resultType, TTL cache scopes) and classic 2025-11-25 MCP protocol handshakes.

  • πŸ›‘οΈ Atomic Quota & Spend Guards: Real-time RPM rate limiting and daily USD spend ceilings powered by atomic Redis Lua scripts, failing gracefully to in-memory ledgers.

  • πŸ” OAuth 2.1 + RFC 9728 Compliance: Built-in authorization code flow with PKCE, dynamic client registration, and token rotation tailored for Claude Custom Connectors.

  • πŸŽ₯ Descent β€” Film 01 Showcase: Complete zero-build scroll-driven interactive landing site (site/) built for frame-accurate scrubbing across 49 seconds of chained AI cinematography.

  • πŸ§ͺ Rock-Solid Engineering: 401 unit, integration, and socket-level end-to-end test cases with 91.03% statement test coverage.


πŸ›οΈ Architecture

flowchart TD
    subgraph Clients["Clients"]
        CC["Claude Code CLI"]
        CA["Claude.ai / Custom Connectors"]
        SDK["Anthropic SDK / Curated Apps"]
    end

    subgraph Helix["Helix Hybrid Core"]
        direction TB
        subgraph Gateway["Gateway (:4000)"]
            Router["Model Router & Dispatcher"]
            Signer["Thinking Signer (HMAC-SHA256)"]
            Assembler["Anthropic SSE Assembler"]
        end

        subgraph MCPServer["MCP Server (:4001)"]
            OAuth["OAuth 2.1 & PKCE Auth"]
            ToolRegistry["Generation Tools Registry"]
            TaskEngine["Task Store & Poller"]
        end

        Quota["Quota Ledger (Redis / Lua Atomic Engine)"]
    end

    subgraph Backends["Compute Backends"]
        LocalModel["Local Model (Ollama / vLLM / llama.cpp)"]
        Higgsfield["Higgsfield AI Generation API"]
    end

    CC -->|"ANTHROPIC_BASE_URL"| Router
    SDK -->|"ANTHROPIC_BASE_URL"| Router
    CA -->|"Streamable HTTP /mcp"| OAuth

    Router --> Quota
    OAuth --> Quota

    Router -->|"OpenAI IR translation"| LocalModel
    Router -.->|"Studio Mode Loop"| MCPServer
    MCPServer -->|"Async Job Dispatch"| Higgsfield


πŸš€ Quick Start

1. Prerequisites

  • Node.js: v20.0.0 or higher (Node 22 / 24 recommended)

  • Package Manager: pnpm >= 9

  • Optional: Ollama (running locally) & Redis (for shared quotas)

2. Installation & Setup

# Clone the repository
git clone https://github.com/satiricalguru/Helix.git
cd Helix

# Install monorepo dependencies
pnpm install

# Copy environment template
cp .env.example .env

# Build all TypeScript packages
pnpm build

3. Run Environment Doctor

Verify connectivity to your local model, Redis, and Higgsfield credentials:

pnpm doctor

Output:

Helix doctor
────────────────────────────────────────────────────────────
local model   http://127.0.0.1:11434/v1 (qwen3:32b) ... ok
  available: llama3.2:3b, nomic-embed-text:latest, ornith-1.5:9b
higgsfield   the credential was accepted
redis        ok
────────────────────────────────────────────────────────────
served model: helix-fable-5-2
upstream:     qwen3:32b
generation:   14 models in the catalog

all checks passed

4. Start the Services

In separate terminal sessions or background processes:

# Start the Anthropic Gateway (Port 4000)
pnpm dev:gateway

# Start the Higgsfield MCP Server (Port 4001)
pnpm dev:mcp

Or run everything with Docker Compose:

docker compose up -d

πŸ”Œ Connecting Your Clients

Claude Code CLI

Direct Claude Code to use your Helix Gateway as its LLM backend:

export ANTHROPIC_BASE_URL="http://127.0.0.1:4000"
export ANTHROPIC_API_KEY="sk-helix-..." # printed on gateway boot, or set HELIX_API_KEY
claude --model helix-fable-5-2

Add the Helix MCP Generation tools to Claude Code:

claude mcp add --transport http helix http://127.0.0.1:4001/mcp
claude mcp login helix

Claude.ai Custom Connector

  1. Open Claude.ai → Settings → Connectors → Add Custom Connector.

  2. Name: Helix

  3. URL: https://<your-host>:4001/mcp

  4. Complete the OAuth 2.1 login flow in your browser.


πŸ› οΈ MCP Tools Catalog

Helix exposes generation tools with embedded pricing disclosure and AI content metadata:

Tool

Mode

Description

Cost Model

list_generation_models

Read-only

Returns available video/image models, supported resolutions, and limits

Free

get_generation_model

Read-only

Detailed schema, parameter limits, and provider terms for a specific model

Free

generate_video

Action

Dispatches video generation (Seedance, Cinema Studio, Kling) and waits for output

Quoted per second

generate_image

Action

Dispatches high-resolution image generation from prompts and references

Quoted per image

get_generation_status

Read-only

Inspects asynchronous generation request progress and artifact URLs

Free

estimate_generation_cost

Read-only

Pre-flight pricing calculations before invoking paid pipelines

Free

balance

Read-only

Reports current account credits and subscription tier

Free

show_plans_and_credits

Read-only

Displays plan details and upgrade links

Free


πŸ’» CLI Commands

The @helix/cli provides first-class developer tooling:

# Run environment diagnostics
pnpm cli doctor

# Inspect available served models and the generation catalog
pnpm cli models

# Mint a new virtual API key with custom rate limits and daily USD budget
HELIX_KEY_LABEL="prod-app" HELIX_MEDIA_BUDGET_USD=25 pnpm cli key

# Provision an MCP user account
pnpm cli user admin@helix.local MySecurePassword123

πŸ“¦ Monorepo Structure

Helix/
β”œβ”€β”€ apps/
β”‚   └── cli/             # Helix developer CLI tool (@helix/cli)
β”œβ”€β”€ packages/
β”‚   β”œβ”€β”€ config/          # Static catalogs, model deployments & pricing specs
β”‚   β”œβ”€β”€ contracts/       # Anthropic API & MCP protocol schemas & Zod validators
β”‚   β”œβ”€β”€ gateway/         # Anthropic-compatible HTTP/SSE server & router
β”‚   β”œβ”€β”€ hf-client/       # Resilient Higgsfield asynchronous API client
β”‚   β”œβ”€β”€ local-adapter/   # OpenAI-to-Anthropic stream assembler & thinking signer
β”‚   β”œβ”€β”€ mcp-client/      # Reconnecting client for MCP generation endpoints
β”‚   β”œβ”€β”€ mcp-server/      # Dual-era Streamable HTTP MCP & OAuth 2.1 server
β”‚   └── quota/           # Atomic Redis Lua quota service & in-memory fallbacks
β”œβ”€β”€ site/                # Descent (Film 01) zero-build interactive landing page
β”œβ”€β”€ scripts/             # Production scripts for video rendering & auth probes
β”œβ”€β”€ docker/              # Dockerfiles for Gateway and MCP Server
└── test/                # Socket-level end-to-end verification suite

πŸ§ͺ Testing & Verification

Helix maintains rigorous automated testing with Vitest and v8 coverage:

# Run the complete test suite (401 tests across 24 suites)
pnpm test

# Run tests with detailed coverage report
pnpm test:coverage

# Perform typecheck across all workspaces
pnpm typecheck

πŸ“„ License

Distributed under the MIT License. See LICENSE for more information.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers