Legion

Legion

"I am Legion, for we are many."

An MCP-native model council. Legion exposes LLMs as individual tools and orchestrates them into debates, juries, blind panels, private refinement gauntlets, workshops, and custom multi-model deliberations.

Every model is reached through the OpenAI Responses API wire format. Use OpenAI or Azure directly, route other providers through a compatible gateway (such as a LiteLLM proxy), and configure the entire council through hot-reloadable files.

Contents

• How it works
• Design decisions
• Requirements
• Setup
• Configuration
• Logging
• Run
• Try it
• Use in VS Code
• Deploy

How it works

flowchart LR

AI[Calling AI] -->|claude / gpt / gemini …| Legion Legion -->|Responses API| GPT[OpenAI / Azure — direct] Legion -->|Responses API| GW[Gateway e.g. LiteLLM] GW --> Claude & Gemini & Llama

• One tool per model, named after the slugified model name (e.g. Claude → claude). Each accepts a prompt plus optional context, role, system, temperature, and maxTokens.
• A `quorum` tool fans one prompt out to several models — with roles, multi-round discussion, visibility modes, and synthesis — and returns each answer separately. See Presets for the orchestration options.
• Presets are named, pre-staffed councils (debate, courtroom, code review, …), each exposed as its own tool.
• Identity and telemetry ride in structuredContent, not the answer text. Logging goes to stderr (safe for stdio).

Design decisions

• No provider adapters. There is no provider-specific code and no built-in model list. Legion speaks one wire format; models that don't speak it natively go through a gateway. Supporting a new model requires no change here.
• Models are config, not code. Adding a model means adding a JSON file. Over HTTP the directory is re-read per request, so no rebuild or restart; over stdio the config is read once per connection (see Hot-reload).
• One tool per model. Each model appears to the calling AI as its own tool with its own description, rather than a single tool with a model parameter. The quorum tool covers the ad-hoc multi-model case, and each preset in config/presets/ is exposed as its own enforced, pre-staffed council tool.
• Stateless. Every call is one-shot with store: false. Nothing is persisted, so there is no database and no conversation state to manage.
• Small. A couple thousand lines of TypeScript, one bundled output file, five dependencies.

Requirements

• Node.js 24+
• At least one OpenAI-Responses-compatible endpoint (a provider API directly, or a gateway such as LiteLLM for models that need bridging)

Setup

From npm — no clone, no build:

npx legion-mcp

From a clone:

npm install

copy .env.example .env # then edit .env

Configuration

All configuration lives in a config/ directory. The bundled defaults are always the base layer; a config/ folder in the current working directory is overlaid on top of them, per file:

• Directory resources (models/, roles/, presets/, tools/): a local file overrides the bundled file of the same name; a local-only file is added; every bundled file you don't touch stays. So dropping in one config/presets/refine.json overrides just that preset — the other bundled presets remain.
• Single-file text (prompts.json, errors.json, schema.json): merged per key — bundled < local. A partial local file overrides only the keys it sets.
• `description.md`: local wins whole if present, else bundled.

The overlay can override or add, but not delete a bundled entry. To choose which bundled presets register as tools, use PRESETS (see below).

Installing from npm? You must supply your own model files. The bundled

config ships only key-free *.example.json model files, which the scanner

deliberately ignores — so the bundle contributes zero real models. With no

real model file the server fails fast at startup (`No model files found

in ...). Drop one config/models/ .json` next to where you run the

server (see below) — the rest falls back to the bundled defaults.

The layout below is identical either way.

Hot-reload

Config is read fresh when a server instance is built, never baked in at build time — but *when* that happens depends on the transport:

HTTP builds a fresh server per request, so a dropped-in model, role, preset, or text override is picked up by the very next call. Stdio pins one server for the life of the connection, so the same edit lands when the client restarts Legion — which for most desktop MCP clients means reloading the server, not rebooting the machine.

Where this README says something is "live on the next call", read it as the HTTP behavior; over stdio it's the next connection.

Models — config/models/*.json

At least one model file is required — the server fails fast without one. Each JSON file becomes a tool, named after the slugified file name (config/models/fable.json → tool fable):

{

"model": "claude-fable-5", "description": "Claude Fable — fast, creative, general purpose.", "baseUrl": "https://api.example.com", "apiKey": "[PopNx MCP ตัดค่าที่หน้าตาเหมือนกุญแจออก]" }

• model (required) — the deployed model id the endpoint routes to.
• description — helps the calling AI pick the right model.
• system — optional baseline system instructions baked into every call to this model.
• baseUrl / apiKey — optional; omitted values fall back to DEFAULT_BASE_URL / DEFAULT_API_KEY. apiKey may reference an environment variable with the env: prefix — "apiKey": "env:GPT_KEY" reads GPT_KEY from the environment (unset/empty is a fatal startup error), so a key can stay out of the file entirely.
• omitParams — optional list of request params to drop for this model, e.g. ["temperature"]. The server stays provider-agnostic: it never assumes which models reject which params — you declare each model's quirks here. Useful for reasoning models and some deployments that reject temperature.
• reasoning — optional "minimal" | "low" | "medium" | "high", sent as reasoning.effort. Reasoning models can spend an entire maxTokens thinking and emit nothing; "low" may help leave room for an answer. The endpoint must support this parameter; it does not bypass content filtering.
• maxTokens — optional hard output ceiling for this model. Every request sends min(requested, ceiling), whatever the caller or preset role asked for. For models that think harder the more room they get and come back empty.

Hot-drop: the directory is re-scanned per request — add or edit a model file and it's live on the next call, no restart.

Secrets & git: model files can contain API keys, so config/models/*.json is git-ignored. Copy a *.example.json (tracked, key-free, ignored by the scanner) to get started:

copy config\models\gpt.example.json config\models\gpt.json   # then add your key

Roles — config/roles/*.md

Optional hot-droppable instruction files. Each .md file becomes a named role (slugified from filename). Drop a file, it's live on the next call. This repo ships skeptic.md, builder.md, judge.md, and short.md (a terse "answer immediately, no deliberation" role useful for constrained-output turns) as ready-to-use starters — edit or delete them freely (they hold no secrets).

Available selectors in tools become roleName, e.g. passing role: "skeptic" or using "model:skeptic" in quorum.models.

Presets — config/presets/*.json

Optional hot-droppable council recipes, one JSON file per preset (named after the slugified file name, like models). Each preset becomes its own tool — drop config/presets/code_review.json and a code_review tool appears on the next request. Each preset has a description, a roles list, and optional authoritative mode / synthesizer defaults. Each role defines its behavior inline — a role's description *is* its instructions (the behavior contract); a role with no description falls back to a matching config/roles/ .md file:

{

"description": [ "Free-for-all: pit several contestants against each other, then crown a winner.", "", "Staff contestant with as many models as you like; one judge decides." ], "mode": "parallel", "synthesizer": "judge", "roles": [ { "role": "contestant", "description": "Argue why your answer beats the others.", "min": 2, "max": null }, { "role": "judge", "description": "Crown a single winner and justify it.", "min": 1, "max": 1 } ] }

The calling AI invokes the preset tool directly (e.g. code_review) and still writes the models selectors, assigning any model to any preset role. Presets are enforced: every selector must use a preset role and every role must be staffed within its cardinality, else the result is an error saying what to fix.

Keys:

Role object keys:

| description | string \| string[] | matching role file | Inline instructions; arrays are joined with newlines. Otherwise