MCP-Brain: Multi-agent Cognitive Processing Framework

A lightweight AI framework that runs locally on your machine using MiniMax API. Three specialized agents — Analyst, Creator, and Critic — collaborate through a structured cognitive pipeline to solve complex problems.

User Task
   │
   ▼
┌──────────┐   Analyst breaks it down
│ Analyst ├─────────────────────────┐
└──────────┘                       │
   │                                │
   ▼                                │
┌──────────┐   Creator drafts   ┌──────────┐
│ Creator  │◄──────────────────┤ Analyst  │
└──────────┘                    │ Context  │
   │                            └──────────┘
   │                                │
   ▼                                │
┌──────────┐   Critic evaluates  ┌──────────┐
│ Critic   │◄────────────────────┤ Creator  │
└──────────┘                     │ Draft    │
   │                            └──────────┘
   │                                │
   ▼                                │
┌──────────┐   Creator improves   ┌──────────┐
│ Creator  │◄────────────────────┤ Critic   │
└──────────┘                     │ Feedback │
   │                            └──────────┘
   │
   ▼
┌──────────┐   Critic final     ┌──────────┐
│ Critic   │◄──────eval─────────│ Improved │
└──────────┘                    │ Solution │
   │                            └──────────┘
   ▼
Final Solution + Evaluation

Features

• Local-only — API key and data never leave your machine
• Multi-agent cognition — mimics human collaborative problem-solving
• Persistent memory — sessions saved to ~/.mcp/ for review
• Simple CLI — mcp setup, mcp process, mcp sessions
• Streaming support — stream responses token-by-token
• OpenAI-compatible HTTP server — use as a drop-in LLM provider for any OpenAI client
• Hermes integration — works as both an MCP tool server and a full LLM provider

Installation

# Install from PyPI
pip install mcp-brain

# Or install with pipx (recommended on Ubuntu)
pipx install mcp-brain

# Or install from source
git clone https://github.com/MC80s/mcp.git
cd mcp
pip install -e .

Quick Start

# 1. Configure your MiniMax API key
mcp setup

# 2. Process your first task
mcp process "Design a logo for a tech startup called Quantum Leap"

# 3. View previous sessions
mcp sessions

# 4. Check config status
mcp status

How It Works

Cost Estimation

MiniMax API is pay-per-use. Each task runs 5 agent calls.

No subscription fees. You control your usage.

Project Structure

mcp-brain/
├── src/mcpbrain/
│   ├── minimax_client.py   # MiniMax API client
│   ├── agents.py            # Creator/Critic/Analyst agents
│   ├── memory.py            # Working memory
│   ├── mcp_core.py          # Orchestration engine
│   ├── http_server.py       # OpenAI-compatible HTTP server
│   ├── server.py            # MCP stdio server
│   ├── tools.py             # Local tool registry
│   └── cli.py               # CLI commands
├── scripts/
├── tests/
├── setup.py
├── pyproject.toml
├── install.sh
└── README.md

CLI Commands

mcp setup              Interactively configure API key
mcp process "task"    Run a task through the cognitive pipeline
mcp sessions          List recent sessions
mcp session <id>      View full session details
mcp status            Check configuration

HTTP Server (OpenAI-compatible)

The HTTP server exposes POST /v1/chat/completions in OpenAI format, making mcp-brain usable as a drop-in LLM provider for any OpenAI-compatible client.

Two Routing Modes

Mode 1: Passthrough (tools present) — When the request includes tools or functions, the cognitive pipeline is bypassed. The full messages array is forwarded directly to MiniMax with the tool definitions. The LLM decides whether to call a tool or respond with text. This is the mode used by Hermes agent integration.

Mode 2: Cognitive Pipeline (no tools) — When no tools are present, the full adaptive pipeline runs. Tasks are classified as SIMPLE (1 step), MODERATE (2 steps), or COMPLEX (5 steps) and routed accordingly.

Starting the server

# Auto-start on boot (systemd user service)
systemctl --user enable mcp-brain-http
systemctl --user start mcp-brain-http

# Or run manually
mcp-brain-http --port 8080

systemd user service

# ~/.config/systemd/user/mcp-brain-http.service
[Unit]
Description=MCP Brain HTTP Server (OpenAI-compatible)
After=network.target

[Service]
ExecStart=/home/YOUR_USERNAME/.local/share/pipx/venvs/mcp-brain/bin/mcp-brain-http --host 127.0.0.1 --port 8080
Restart=always
RestartSec=10

[Install]
WantedBy=default.target

Verify

curl http://127.0.0.1:8080/health                    # {"status":"ok"}
curl http://127.0.0.1:8080/v1/models                # {"object":"list","data":[{"id":"mcp-brain",...}]}

Test a completion

curl -X POST http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"mcp-brain","messages":[{"role":"user","content":"What is 2+2?"}],"stream":false}'

Hermes Integration

mcp-brain integrates with Hermes in two ways:

Option A — MCP Tool Server (manual invocation)

Connect mcp-brain as a native MCP tool server. Hermes can delegate complex reasoning tasks to the multi-agent pipeline by calling the process_task tool.

# ~/.hermes/config.yaml
mcp_servers:
  mcp-brain:
    command: "/home/YOUR_USERNAME/.local/bin/mcp-brain-server"

Option B — Full LLM Provider (recommended, automatic)

Route all LLM conversations through the cognitive pipeline. Every message goes through the adaptive multi-agent architecture automatically.

# ~/.hermes/config.yaml
custom_providers:
  - name: "mcp-brain"
    base_url: "http://127.0.0.1:8080/v1"
    api_key: "local"      # any value — the server ignores it
    provider: "openai"     # OpenAI-compatible endpoint

Why Option B: With Option A, you manually invoke mcp-brain tools. With Option B, every conversation automatically benefits from the cognitive pipeline — no explicit invocation needed.

Configuration

Config file: ~/.mcp/config.json

{
  "api_key": "...",
  "model": "MiniMax-M2.7",
  "max_tokens": 2000,
  "temperature": 0.7
}

Run setup: mcp setup

Important: MiniMax API base URL is https://api.minimax.io/v1 (NOT .chat — that returns 401 on everything).

Working model names: MiniMax-M2.7, MiniMax-M2, MiniMax-M2.5.

Changelog

v0.6.3 — OpenAI Compatibility Fix

Fixed critical OpenAI streaming format violations that caused "empty response" errors in Hermes and other OpenAI-compatible clients:

• Streaming done chunk — Changed from choices[0].message to choices[0].delta{} per OpenAI streaming spec. The final chunk must use delta, not message.
• Tool call responses — Changed from deprecated function_call to modern tool_calls array format with proper id, type, and function fields. finish_reason changed from "function_call" to "tool_calls".
• Reasoning tag stripping — MiniMax M2.7 leaks <think>...</think> reasoning blocks in content. Added a state machine (_process_token) that strips these from the passthrough token stream, and re.sub() stripping for non-streaming responses.
• Non-streaming tool_calls — All non-streaming responses now use tool_calls format consistently.

v0.6.2 — Passthrough max_tokens Fix

• Fixed max_tokens hardcoded to 2000 in passthrough mode — now reads from request body (default 4096).

v0.6.1 — Passthrough Mode

• Added passthrough mode: when tools are present in the request, the cognitive pipeline is bypassed and messages are forwarded directly to MiniMax. This preserves Hermes' system prompt and enables proper tool calling.

v0.6.0 — Native Tool Calling

• Removed regex interceptors for tool invocations. Tools are now passed directly to MiniMax API, which handles tool calling natively.

Privacy

• All API calls go directly from your machine to MiniMax
• No intermediary servers
• Session logs stored locally in ~/.mcp/logs/
• Your API key stored in ~/.mcp/config.json (keep this file private)