ai-consensus-mcp

Un servidor mínimo de stdio Model Context Protocol que expone el Protocolo de Validación de Consenso como una única herramienta consensus. Dale a Claude Code, Cursor, Windsurf —o a cualquier host MCP— una mesa redonda real con múltiples modelos.

Un envoltorio ligero sobre ai-consensus-core. Una herramienta, un archivo de configuración, cero complicaciones.

Qué te ofrece

• Una herramienta MCP: consensus. Apúntala a una lista de modelos + personas y ejecuta un debate de varias rondas.

• Cualquier proveedor compatible con OpenAI. xAI Grok, Anthropic (vía endpoint compatible con OpenAI), OpenAI, Groq, Together, Fireworks o tu propia pasarela privada. Un adaptador, configurable por participante.

• Progreso en vivo. Cada evento estructurado del motor se reenvía como una notificación de progreso de MCP; los hosts muestran el estado en tiempo real de la ronda, participante, desacuerdo y puntuación.

• Dependencias ligeras. @modelcontextprotocol/sdk, zod, ai-consensus-core. El análisis de SSE es fetch nativo; no requiere SDKs de proveedores.

Related MCP server: Claude Code AI Collaboration MCP Server

El protocolo

Para el protocolo real —rondas, fases, prompts, puntuación— consulta el diagrama del protocolo de ai-consensus-core. Este README cubre solo la superficie del servidor.

Instalación

Vía npm:

# Globally, for use as a binary
npm install -g ai-consensus-mcp

# Or as a project dependency
npm install ai-consensus-mcp

O clona y ejecuta:

git clone https://github.com/entropyvortex/ai-consensus-mcp.git
cd ai-consensus-mcp
npm install
npm run build

Configuración

Copia el ejemplo y edítalo:

cp consensus.config.example.json ./consensus.config.json

Forma mínima:

{
  "providers": {
    "xai": {
      "baseUrl": "https://api.x.ai/v1",
      "apiKeyEnv": "GROK_API_KEY"
    },
    "anthropic": {
      "baseUrl": "https://api.anthropic.com/v1",
      "apiKeyEnv": "ANTHROPIC_API_KEY"
    }
  },
  "participants": [
    { "id": "grok",   "provider": "xai",       "modelId": "grok-4",            "personaId": "pessimist" },
    { "id": "domain", "provider": "anthropic", "modelId": "claude-sonnet-4-6", "personaId": "domain-expert" },
    { "id": "devil",  "provider": "xai",       "modelId": "grok-4",            "personaId": "devils-advocate" }
  ],
  "judge": {
    "provider": "xai",
    "modelId": "grok-4"
  }
}

Referencia de configuración

providers.<id>.baseUrl         string   OpenAI-compatible base URL. No trailing /chat/completions.
providers.<id>.apiKeyEnv       string   Name of the env var holding the API key.
providers.<id>.extraHeaders    object?  Static headers sent on every request (rarely needed).

participants[].id              string   Stable participant id (appears in events + progress).
participants[].provider        string   Key into providers.
participants[].modelId         string   Opaque model id the provider accepts.
participants[].personaId       enum     One of: pessimist, first-principles, vc-specialist,
                                        scientific-skeptic, optimistic-futurist,
                                        devils-advocate, domain-expert.
participants[].label           string?  Optional display label.

judge.provider                 string?  Key into providers.
judge.modelId                  string?  Opaque judge model id.
judge.temperature              number?  Defaults to 0.3.
judge.maxOutputTokens          number?  Defaults to 1500.

defaults.maxRounds             int?     1–10, defaults 4.
defaults.earlyStop             bool?    Defaults true.
defaults.convergenceDelta      number?  Defaults 3.
defaults.disagreementThreshold number?  Defaults 20.
defaults.blindFirstRound       bool?    Defaults true.
defaults.randomizeOrder        bool?    Defaults true.
defaults.participantTemperature number? Defaults 0.7.
defaults.maxOutputTokens       int?     Defaults 1500.
defaults.useJudge              bool?    Defaults true if `judge` is declared, else false.

Cada campo que no esté en esa lista es rechazado por el cargador de configuración; los errores tipográficos fallan de forma evidente en lugar de silenciosa.

Ejecución independiente

export GROK_API_KEY=xai-...
export ANTHROPIC_API_KEY=sk-ant-...

ai-consensus-mcp --config ./consensus.config.json

El servidor habla JSON-RPC sobre stdio. Una línea de preparación como:

ai-consensus-mcp ready — 3 participant(s) from 2 provider(s), judge=grok-4 (config: /abs/consensus.config.json)

se escribe en stderr al iniciar; stdout está reservado para el flujo del protocolo MCP.

Registro en un host MCP

Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o el equivalente en Windows:

{
  "mcpServers": {
    "consensus": {
      "command": "ai-consensus-mcp",
      "args": ["--config", "/absolute/path/to/consensus.config.json"],
      "env": {
        "GROK_API_KEY": "xai-...",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

(Si no lo instalaste globalmente, reemplaza "command": "ai-consensus-mcp" con "command": "node" y apunta args a /path/to/ai-consensus-mcp/dist/index.js.)

Reinicia Claude Desktop. Deberías ver una herramienta consensus disponible.

Claude Code

claude mcp add consensus \
  --scope user \
  -- ai-consensus-mcp --config /absolute/path/to/consensus.config.json

O edita ~/.claude.json directamente con la misma estructura de command / args / env.

Cursor, Windsurf y otros hosts

Apúntalos a ai-consensus-mcp --config <path>/consensus.config.json con las claves de API del proveedor relevantes en el entorno. Solo transporte stdio.

La herramienta consensus

Entrada

{
  "prompt": "Should an early-stage startup adopt microservices from day one?",
  "maxRounds": 4,            // optional, 1–10
  "participantIds": ["grok", "domain"],  // optional — subset of configured participants
  "earlyStop": true,         // optional
  "judge": true,             // optional — defaults to config.defaults.useJudge
  "blindFirstRound": true,   // optional
  "randomizeOrder": true,    // optional
  "convergenceDelta": 3,     // optional
  "disagreementThreshold": 20, // optional
  "participantTemperature": 0.7, // optional
  "maxOutputTokens": 1500,   // optional
  "randomSeed": 42           // optional — deterministic round-order shuffle
}

Solo prompt es obligatorio. Todo lo demás recurre a los defaults de la configuración, y luego a los valores predeterminados del motor.

Salida

Dos artefactos en cada llamada exitosa:

1. content[0].text — un resumen en markdown legible por humanos:

   • Puntuación final, duración, motivo de parada

   • Tabla de puntuación por ronda

   • Respuestas de la ronda final, etiquetadas por persona + modelo

   • Síntesis del juez (si judge: true)

2. structuredContent — el ConsensusResult completo como JSON para consumidores programáticos.

Notificaciones de progreso

Cada evento estructurado del motor se reenvía como un mensaje notifications/progress de MCP. Los eventos de streaming a nivel de token se descartan intencionalmente; inundarían el canal.

progress aumenta monótonamente en roundComplete y synthesisComplete; total es maxRounds + (judge ? 1 : 0).

Errores

• Los errores de carga de configuración son fatales al inicio y se imprimen en stderr con la ruta del campo infractor.

• Los errores de entrada de la herramienta devuelven { isError: true, content: [{ type: "text", text: "…" }] } — el host los ve pero el servidor permanece activo.

• Los errores del proveedor (HTTP no 2xx, flujos vacíos) se capturan en el campo response.error de cada participante y la ejecución continúa con los participantes restantes. Los errores son visibles tanto en el flujo de progreso como en el resultado estructurado final.

• Cancelación. Cuando el host cancela una llamada a la herramienta, la AbortSignal se propaga a cada fetch en curso y el motor devuelve un ConsensusResult con stopReason: "aborted".

Límites y objetivos no contemplados

• Sin persistencia. Cada llamada a la herramienta es una ejecución nueva. Si quieres historial, registra structuredContent en el lado del host.

• Sin transporte HTTP. Solo stdio. Para HTTP/SSE, envuelve ai-consensus-core directamente.

• Sin cumplimiento de presupuesto de tokens. maxOutputTokens es orientativo por llamada; coloca alertas de uso en los paneles de control de tus proveedores.

• Sin programación de ejecuciones múltiples. Una ejecución por llamada, secuencial si el host las pone en cola.

Si alguno de estos se convierte en lo que más necesitas, la biblioteca central es el lugar correcto para conectar; este servidor es intencionalmente pequeño.

Desarrollo

git clone https://github.com/entropyvortex/ai-consensus-mcp.git
cd ai-consensus-mcp
npm install
npm run test        # vitest — config loader + MCP handshake integration
npm run build
npm start -- --config ./consensus.config.json

Filosofía

La biblioteca central debería poder vivir en cualquier lugar: Next.js, CLI, worker, Durable Object, otro servidor MCP. Por eso no sabe qué es un proveedor de LLM.

Este paquete es el "cualquier lugar" que más le importa a la gente al principio: un servidor MCP stdio que se integra en Claude Code, Cursor, Windsurf o cualquier host que hable el protocolo. Es deliberadamente pequeño: carga una configuración, reenvía eventos, nada más. Si lo superas, el núcleo está ahí mismo.

Ver también

• ai-consensus-core — la biblioteca subyacente. Úsala directamente si necesitas transporte HTTP, programadores personalizados o una integración más profunda.

Licencia

MIT

Parte del stack entropyvortex — código abierto de IA práctico y sin tonterías por Marcelo Ceccon.

Hecho con ❤️ en Brasil.

Licencia MIT • Construido para ser enviado.