Helix
Allows Helix to use Ollama local models as the backend for its Anthropic-compatible gateway, enabling local inference with streaming, tool calls, reasoning tokens, and model routing.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Helix
Anthropic-Compatible Gateway • Higgsfield-Backed MCP Generation Server
β‘ What is Helix?
Helix unites local LLM intelligence with cloud-grade generative media production through two complementary surfaces:
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.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.
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/messagesandGET /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 classic2025-11-25MCP 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πΌοΈ Feature Gallery
π Quick Start
1. Prerequisites
Node.js:
v20.0.0or higher (Node 22 / 24 recommended)Package Manager:
pnpm >= 9Optional: 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 build3. Run Environment Doctor
Verify connectivity to your local model, Redis, and Higgsfield credentials:
pnpm doctorOutput:
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 passed4. 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:mcpOr 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-2Add the Helix MCP Generation tools to Claude Code:
claude mcp add --transport http helix http://127.0.0.1:4001/mcp
claude mcp login helixClaude.ai Custom Connector
Open Claude.ai → Settings → Connectors → Add Custom Connector.
Name:
HelixURL:
https://<your-host>:4001/mcpComplete 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 |
| Read-only | Returns available video/image models, supported resolutions, and limits | Free |
| Read-only | Detailed schema, parameter limits, and provider terms for a specific model | Free |
| Action | Dispatches video generation (Seedance, Cinema Studio, Kling) and waits for output | Quoted per second |
| Action | Dispatches high-resolution image generation from prompts and references | Quoted per image |
| Read-only | Inspects asynchronous generation request progress and artifact URLs | Free |
| Read-only | Pre-flight pricing calculations before invoking paid pipelines | Free |
| Read-only | Reports current account credits and subscription tier | Free |
| 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β¦
This server cannot be deployed
Maintenance
Related MCP Connectors
OAuth-protected ImagineVid MCP for image, video, and music generation.
Create and manage AI image and video generations through Quriov's fixed public MCP tools.
Plan, compare, price, generate, and recover AI video from compatible MCP clients.
Generate images, video, audio and short films with 140+ AI models from any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables MCP-compatible clients to generate and upscale AI images, videos, music, and sound effects, manage generation jobs, access model catalogs, and track credits.3MIT

maginary-mcpofficial
AlicenseAqualityBmaintenanceEnables MCP-compatible clients to discover Maginary's image/video generation flags, submit generation requests, and poll for results, including support for API-key and OAuth authentication.131MIT- FlicenseCqualityBmaintenanceProvides a durable MCP media pipeline for image, video, audio, and storyboard generation, with FFmpeg composition, provider routing, and resumable long-running jobs.21-
- AlicenseNot gradedqualityCmaintenanceEnables AI clients to create images and videos through a hosted remote MCP endpoint with browser OAuth, letting users discover available models and Quick Apps, quote credit costs, upload reference files, submit single or batch generation tasks, and retrieve finished results. It also supports task tracking, retries with consistent request IDs, and ranged downloads, while spending account credits only on actually submitted jobs.MIT