Skip to main content
Glama

LLM Council MCP Server (llm-council-mcp)

NOTE

Attribution & Inspiration: This project is inspired by Andrej Karpathy's LLM Council multi-perspective deliberation methodology. It operationalizes the 3-Stage Council Protocol (Independent Gathering, Adversarial Critique, and Chairman Synthesis) as a native Model Context Protocol (MCP) tool server for modern AI coding agents.

A high-performance, host-agnostic MCP server that empowers Any AI Coding Agent (Google Antigravity, Claude Code, Codex, Cursor) to act as the Chairman & Executor while delegating:

  • Architectural Strategy & Modular Contracts to OpenAI (gpt-5.6-sol) (The Architect)

  • Adversarial Critique & Edge-Case Stress Testing to DeepSeek (deepseek-v4-pro / deepseek-reasoner) (The Contrarian)

Both models are queried concurrently via asynchronous I/O to minimize latency, giving any host agent frontier-grade peer review without slowing down execution.


Architecture & 3-Stage Deliberation Protocol

                      ┌─────────────────────────────────────────┐
                      │        THE CHAIRMAN & EXECUTOR          │
                      │  (Dynamic Host: Antigravity / Claude /  │
                      │               Codex / Cursor)           │
                      │  Context Ingestion & Workspace State    │
                      └────────────────────┬────────────────────┘
                                           │
                              [MCP: deliberate_council]
                                           │
                   ┌───────────────────────┴───────────────────────┐
                   ▼                                               ▼
        ┌─────────────────────┐                         ┌─────────────────────┐
        │    The Architect    │                         │   The Contrarian    │
        │  (OpenAI gpt-5.6)   │                         │(DeepSeek Reasoner)  │
        │  Stage 1: Gathering │   CONCURRENT ASYNC IO   │  Stage 2: Critique  │
        │  Modular contracts  │ ◄─────────────────────► │  Adversarial flaws, │
        │  & layout blueprint │   Independent Review    │  race conditions    │
        └──────────┬──────────┘                         └──────────┬──────────┘
                   │                                               │
                   └───────────────────────┬───────────────────────┘
                                           │
                                           ▼
                      ┌─────────────────────────────────────────┐
                      │           CHAIRMAN'S DECREE             │
                      │      (Synthesized by Host Agent)        │
                      │  Reconciles tensions, produces decree,  │
                      │  edits files, and verifies builds       │
                      └─────────────────────────────────────────┘
  1. Stage 1: The Gathering (The Architect): OpenAI independently evaluates the problem, designing clean interface boundaries, type contracts, and sequence of changes.

  2. Stage 2: The Critique (The Contrarian): DeepSeek Reasoner independently stress-tests the problem, searching for race conditions, subtle logic regressions, and unnecessary over-engineering.

  3. Stage 3: The Chairman's Decree (The Host Agent): The calling agent (Antigravity Gemini, Claude Code, or Codex/Cursor) receives both structured perspectives, resolves points of tension, creates the implementation plan, and executes the workspace changes.


Related MCP server: brainstorm-mcp

Exposed MCP Tools

Tool

Description

deliberate_council

Concurrently queries both the Architect (gpt-5.6-sol) and Contrarian (deepseek-v4-pro), returning a structured report with identified tension points for Chairman synthesis.

consult_architect

Single-target query to OpenAI for API schema design, interface planning, or modular file layouts.

consult_contrarian

Single-target query to DeepSeek-V4 Pro for adversarial code reviews, bug-hunting, edge cases, and over-engineering checks.

offload_task

Offloads focused implementation subtasks, utility code, unit test suites, or regex writing to high-speed workers (DeepSeek-V4 Flash or OpenAI gpt-5-mini). Prevents host turn/token depletion.

fast_context_reader

High-speed document/log parsing and filtering via DeepSeek-V4 Flash in ~1–2s. Extracts only requested signals without bloating host agent context.


Installation & Build

cd D:/Repositories/llm-council-mcp
npm install
npm run build

Multi-Platform Configuration

1. Google Antigravity 2.0 / AGY CLI

Add to ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "llm-council": {
      "command": "node",
      "args": [
        "D:/Repositories/llm-council-mcp/dist/index.js"
      ],
      "env": {
        "OPENAI_API_KEY": "sk-proj-YOUR_OPENAI_KEY",
        "DEEPSEEK_API_KEY": "sk-YOUR_DEEPSEEK_KEY",
        "COUNCIL_ARCHITECT_MODEL": "gpt-5.6-sol",
        "COUNCIL_CONTRARIAN_MODEL": "deepseek-reasoner",
        "COUNCIL_TIMEOUT_MS": "120000"
      }
    }
  }
}

2. Claude Code / Claude Desktop

Add to ~/.claude/mcp.json or claude_desktop_config.json:

{
  "mcpServers": {
    "llm-council": {
      "command": "node",
      "args": [
        "D:/Repositories/llm-council-mcp/dist/index.js"
      ],
      "env": {
        "OPENAI_API_KEY": "sk-proj-YOUR_OPENAI_KEY",
        "DEEPSEEK_API_KEY": "sk-YOUR_DEEPSEEK_KEY"
      }
    }
  }
}

3. Cursor & Codex

Add the same server block to ~/.cursor/mcp.json or Cursor Settings → Features → MCP.


Environment Variables

Variable

Description

Default

OPENAI_API_KEY

Your OpenAI Platform API key (sk-proj-...)

Required

DEEPSEEK_API_KEY

Your DeepSeek Platform API key (sk-...)

Required

OPENAI_BASE_URL

OpenAI API Base URL

https://api.openai.com/v1

DEEPSEEK_BASE_URL

DeepSeek API Base URL

https://api.deepseek.com

COUNCIL_ARCHITECT_MODEL

Default model for the Architect role

gpt-5.6-sol

COUNCIL_CONTRARIAN_MODEL

Default model for the Contrarian role

deepseek-reasoner

COUNCIL_TIMEOUT_MS

Max API timeout in milliseconds

120000 (2 minutes)


Economics & Cost Efficiency

Because the host orchestrator absorbs 95% of workspace file searches, git diffs, and terminal runs within your base plan, the Council only burns external API tokens during high-level planning rounds:

  • OpenAI (gpt-5.6-sol): ~$0.025 / round

  • DeepSeek (deepseek-v4-pro): ~$0.007 / round

  • Combined Cost: ~$0.032 (~3 to 4 cents) per full Council deliberation.

  • A $50 balance ($35 OpenAI + $15 DeepSeek) funds ~1,400 full deliberations (5 to 7+ months of active development).


Credits & License

  • Inspired by the LLM Council architecture conceived by Andrej Karpathy.

  • Released under the MIT License.

Available Tools

5 tools
consult_architectC

Directly queries The Architect (OpenAI gpt-5.6-sol) for high-level system decomposition, modular design, API interfaces, and structured implementation steps.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNoOptional override for the Architect model (default: gpt-5.6-sol).
effortNoReasoning effort level (default: medium).
promptYesThe architectural question, design specification, or system requirement.
contextNoAdditional codebase background, existing file schemas, or constraints.

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full responsibility for behavioral disclosure. It says it 'directly queries' an external AI model, but does not describe the return format, whether the call is synchronous, potential costs, rate limits, authentication requirements, or any side effects. An agent calling this tool would have no idea what to expect in the response.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that immediately names the action and the target. It is concise and to the point, with no filler. It could be considered slightly terse but is appropriately sized for the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that the tool queries an AI model and has no output schema or annotations, the description should clarify what the agent can expect back (e.g., text, structured steps, reasoning). It also fails to connect the tool to its siblings, leaving the agent in the dark about when this is the appropriate consultation route. These gaps make the description incomplete for safe and correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already describes all four parameters (model, effort, prompt, context) with 100% coverage, so the baseline is 3. The description adds no parameter-specific information beyond what the schema provides, so it neither improves nor detracts from the schema's clarity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'queries' and the resource 'The Architect (OpenAI gpt-5.6-sol)', and enumerates the kind of output it provides (system decomposition, modular design, API interfaces, structured implementation steps). This is specific and distinguishes it from generic query tools, but it does not reference any sibling tools, so an agent cannot tell how this differs from consult_contrarian or deliberate_council without additional context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus its siblings. The description only states what it does, not under what circumstances it should be chosen over consult_contrarian, deliberate_council, offload_task, or fast_context_reader. An agent is left to guess which consultation tool fits a given request.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

consult_contrarianA

Directly queries The Contrarian (DeepSeek-V4 Pro) for adversarial code review, bug-hunting, edge cases, race conditions, and over-engineering checks.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNoOptional override for the Contrarian model (default: deepseek-v4-pro).
effortNoReasoning effort level (default: high). Maximum depth for adversarial critique.
promptYesThe code snippet, proposed design, or logic to stress-test and critique.
contextNoSurrounding system context, concurrency model, or requirements.

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses that this makes a direct query to a named external model and describes the nature of the analysis (adversarial, edge-case, race-condition checks). However, it does not mention return format, potential latency/cost of an LLM call, or whether state is modified, leaving some important behavioral context unspecified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that names the action, the resource, and the outcome. There is no filler or repetition; every phrase earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter tool with no annotations and no output schema, the description is somewhat thin. It makes the purpose clear and the schema documents parameters, but it does not explain the response shape or provide explicit usage boundaries relative to siblings. Adequate, but with clear gaps an agent must fill by inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%—every parameter has a description, including the enum values for effort and the semantics of prompt and context. The tool description adds high-level purpose context but no parameter-specific detail beyond what the schema already provides, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('queries') plus a named resource ('The Contrarian (DeepSeek-V4 Pro)') and a concrete set of purposes (adversarial code review, bug-hunting, edge cases, race conditions, over-engineering checks). This clearly differentiates it from siblings like consult_architect or deliberate_council, which imply different consultation modes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool—when adversarial critique or bug-hunting is needed—but it never explicitly states when not to use it or names alternatives. Sibling names suggest different roles (e.g., architect vs. contrarian), yet the description leaves that routing entirely to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

deliberate_councilA

Runs a full multi-model LLM Council deliberation. Concurrently queries the Architect (OpenAI gpt-5.6-sol) for a structural blueprint and the Contrarian (DeepSeek-V4 Pro) for adversarial critique and edge cases. Returns both perspectives for the Host Agent (Chairman) to synthesize and execute.

ParametersJSON Schema
NameRequiredDescriptionDefault
contextNoRelevant context, codebase conventions, interface definitions, or constraints.
problemYesThe core engineering task, architectural question, design choice, or bug to solve.
architectModelNoOptional override for the Architect model (default: gpt-5.6-sol).
architectEffortNoReasoning effort for the Architect (default: medium). Use 'high' for complex cross-cutting concerns.
contrarianModelNoOptional override for the Contrarian model (default: deepseek-v4-pro).
contrarianEffortNoReasoning effort for the Contrarian (default: high). Maximum depth adversarial stress-testing.

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden, and it discloses key behaviors: concurrent queries, specific model identities, and that the tool returns raw perspectives for the Host Agent to synthesize rather than a final answer. It does not address cost, latency, or side effects, but the core operational behavior is transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with the main action front-loaded and no filler. Each sentence earns its place: what the tool does, how it works (concurrent queries), and what it returns. The size is appropriate for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main purpose and the shape of the output, and the absence of an output schema means return values need not be detailed. However, for a six-parameter tool with no annotations, it omits when to prefer this over its single-model siblings and gives no caution about cost or latency. Adequate but with clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds some context by mapping the model parameters to their roles (structural blueprint vs adversarial critique), but it does not provide syntax, format, or effort guidance beyond what the schema already documents. The marginal contribution does not raise the score above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Runs a full multi-model LLM Council deliberation') and details the two sub-queries (Architect for structural blueprint, Contrarian for adversarial critique). It clearly differentiates from the single-perspective sibling tools by emphasizing concurrent execution and the return of both perspectives. No tautology or ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for getting both perspectives at once, but it never explicitly names alternatives or states when-not-to-use. An agent must infer that consult_architect or consult_contrarian would be the right choice for a single-perspective need. Guidance is left to inference rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fast_context_readerA

Parses, filters, or summarizes raw file contents, large logs, cache dumps, or complex schemas using a high-speed worker (DeepSeek-V4 Flash) in ~1-2 seconds. Prevents bloating host agent context window.

ParametersJSON Schema
NameRequiredDescriptionDefault
focusYesExtraction target (e.g. 'all error stack traces', 'exported interface signatures', 'list of changed state variables').
modelNoOptional model override (default: deepseek-v4-flash).
contentYesThe raw text, code file, log output, or cached content to extract from.
providerNoWorker provider (default: 'deepseek').

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that a high-speed worker (DeepSeek-V4 Flash) is used, gives expected latency (~1-2 seconds), and states the context-bloat prevention effect. It stops short of describing error cases or output format, but for a simple read/filter operation the disclosed behavior is meaningful and non-obvious.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The first sentence front-loads the action and resource, the second explains the benefit. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter tool with no output schema and no annotations, the description covers the what, the why, and the performance characteristics. It could add example extraction targets or clarify how 'focus' interacts with the parse/filter/summarize modes, but the core calling guidance is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds context about the overall purpose and the effect on context window, but it does not provide parameter-specific details beyond what the schema already states for 'content' and 'focus'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verbs (parses, filters, summarizes) tied to explicit resources (raw file contents, large logs, cache dumps, complex schemas). It clearly differentiates itself from the sibling consultation/offload tools by positioning itself as a context-preserving extraction utility rather than a deliberation or task-delegation tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'Prevents bloating host agent context window' gives a clear usage context: use this when content is large and only a focused extraction is desired. It does not explicitly name alternatives or exclusion conditions, but the sibling names and the description make the intended scenario reasonably clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

offload_taskB

Offloads a focused implementation subtask, utility function, unit test suite, regex, or refactoring step to a fast external worker (DeepSeek-V4 Flash or OpenAI gpt-5-mini) to save host agent context and execution limits.

ParametersJSON Schema
NameRequiredDescriptionDefault
taskYesThe exact subtask, function to write, unit test table, or transformation to perform.
modelNoOptional model override (defaults to deepseek-v4-flash or gpt-5.6-sol).
effortNoReasoning effort if using a reasoning model (default: 'low' for GPT SOL to achieve sub-2s latency).
contextNoSurrounding code, types, constraints, or interfaces needed to execute the task accurately.
providerNoWorker provider (default: 'deepseek' for sub-2s latency and minimal cost).

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are absent, so the description bears full responsibility. It discloses that an external worker is used and mentions default models and latency, but it doesn't clarify whether the call is synchronous, what happens on failure, network dependencies, or cost implications. It also doesn't describe the return value or any side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core action and resource, then adds the purpose. It's not overly verbose and avoids redundancy, though it could be slightly more structured by separating the purpose from the resource list.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 5 parameters, no output schema, and no annotations, the description is too thin. It doesn't explain expected output format, error conditions, when to choose specific providers/models, or how the result is returned. An agent would need to inspect the schema or rely on defaults without clear guidance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all parameters. The description adds no additional meaning beyond what the schema provides; it doesn't explain relationships between parameters or edge-case behaviors, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('offloads') and lists concrete resources ('focused implementation subtask, utility function, unit test suite, regex, or refactoring step'), clearly distinguishing this tool from siblings like consult_architect or deliberate_council, which are about thinking rather than execution.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the motivating purpose ('to save host agent context and execution limits') but doesn't explicitly say when to use this vs alternatives, nor when not to use it. It implies usage for small, well-defined tasks but no explicit exclusions or comparison with doing the work inline.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 5 tool updatesv1.0.0
    • First observedconsult_architect
    • First observedconsult_contrarian
    • First observeddeliberate_council
    • First observedfast_context_reader
    • First observedoffload_task

TDQS

A3.6/5.0

Scored across 5 tools

Disambiguation4/5

deliberate_council is clearly the aggregate entry point, while consult_architect and consult_contrarian are focused single-perspective queries. offload_task and fast_context_reader both use fast workers, but their purposes are separated by execution versus context reading, so confusion is unlikely.

Naming Consistency4/5

Most tools follow a clear verb_noun pattern: consult_architect, consult_contrarian, offload_task, and deliberate_council. fast_context_reader breaks the pattern as a noun phrase, but the overall naming style remains recognizable and readable.

Tool Count5/5

Five tools is well-scoped for an LLM council orchestration server: one aggregate deliberation, two direct consultant queries, and two supporting execution/context utilities. Each tool has a distinct role and none feel redundant or missing.

Completeness4/5

The set covers full council deliberation, individual expert consultation, task offloading, and context preprocessing. There is no explicit synthesis or decision-recording tool, but the workflow intentionally leaves synthesis to the host agent, so this is only a minor gap.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers