VibeCheck MCP

What is VibeCheck MCP about?

VibeCheck MCP offers a lightweight server that acts as an AI meta‑mentor, inserting reflective pauses (CPI) into agent workflows to guard against flawed planning, tunnel‑vision errors, and misalignment. It supports multiple LLM providers (Gemini, OpenAI, OpenRouter) and can retain session history for continuity.

How to use VibeCheck MCP?

1. Install – clone the repo or run the package via npx.
2. Configure – create a .env file with the required API keys (GEMINI_API_KEY, optional OPENAI_API_KEY, OPENROUTER_API_KEY).
3. Start – npm start (or the provided npx command) launches the MCP server on the default port.
4. Call the tool – agents invoke the vibe_check tool with parameters such as goal, plan, and optional sessionId. Optionally log corrections with vibe_learn.

Key features of VibeCheck MCP

• CPI Adaptive Interrupts – phase‑aware prompts that challenge assumptions and force reflection.
• Multi‑provider routing – seamless switching between Gemini, OpenAI and OpenRouter models.
• History continuity – session‑wide context summarization when sessionId is supplied.
• Optional learning logs – vibe_learn captures mistakes for future self‑improvement.
• Docker & systemd/LaunchAgent automation – one‑click setup scripts for persistent deployment.
• High test coverage (98%) and CI‑driven security scanning.

Use cases of VibeCheck MCP

• Preventing runaway planning in autonomous coding assistants.
• Adding a reflective safety layer to multi‑step AI workflows (e.g., data pipeline generation, report drafting).
• Assisting research agents to avoid reasoning lock‑in during hypothesis testing.
• Enabling enterprise AI agents to stay aligned with policy constraints by periodic sanity checks.

FAQ from the VibeCheck MCP

• Does it increase latency? A typical CPI call adds roughly 1 second, depending on the LLM provider.
• Can logging be disabled? Yes, vibe_learn is optional and can be omitted from tool calls.
• Which providers are supported? Gemini (default), OpenAI, and OpenRouter.
• Is Docker required? No, but Docker scripts simplify deployment and ensure a consistent environment.
• How to handle TypeScript build errors on Node 20.19.3? Ensure dependencies are up‑to‑date (npm install) or use the provided Docker setup which handles the build automatically.

🧠 VibeCheck MCP v2.2

Adaptive metacognitive oversight for autonomous AI agents – a research-backed MCP server keeping LLMs aligned, reflective and safe.

The Most Widely-Deployed Feedback Layer in the MCP Ecosystem

~10k+ downloads on PulseMCP and counting. Over 1k monthly tool calls via Smithery. Listed on 12+ orchestration platforms. Security rating 4.3 on MSEEP.ai.

Table of Contents

• What is VibeCheck MCP?
• The Problem: Pattern Inertia & Reasoning Lock-In
• Key Features
• What's New in v2.2
• Quickstart & Installation
• Usage Examples
• Adaptive Metacognitive Interrupts (CPI)
• Agent Prompting Essentials
• When to Use Each Tool
• Documentation
• Research & Philosophy
• Security
• Roadmap
• Contributing & Community
• FAQ
• Find VibeCheck MCP on
• Credits & License

What is VibeCheck MCP?

VibeCheck MCP is a lightweight server implementing Anthropic's Model Context Protocol. It acts as an AI meta-mentor for your agents, interrupting pattern inertia with Critical Path Interrupts (CPI) to prevent Reasoning Lock-In (RLI). Think of it as a rubber-duck debugger for LLMs – a quick sanity check before your agent goes down the wrong path.

The Problem: Pattern Inertia & Reasoning Lock-In

Large language models can confidently follow flawed plans. Without an external nudge they may spiral into overengineering or misalignment. VibeCheck provides that nudge through short reflective pauses, improving reliability and safety.

Key Features

What's New in v2.2

• CPI-driven adaptive interrupts for smarter interventions
• Multi-provider routing (Gemini, OpenAI, OpenRouter)
• Optional vibe_learn logging
• History continuity across sessions

Quickstart & Installation

# Clone and install
git clone https://github.com/PV-Bhat/vibe-check-mcp-server.git
cd vibe-check-mcp-server
npm install
npm run build

This project targets Node 20+. If you see a TypeScript error about a duplicate require declaration when building with Node 20.19.3, ensure your dependencies are up to date (npm install) or use the Docker setup below which handles the build automatically.

Create a .env file with the API keys you plan to use:

# Gemini (default)
GEMINI_API_KEY=your_gemini_api_key
# Optional providers
OPENAI_API_KEY=your_openai_api_key
OPENROUTER_API_KEY=your_openrouter_api_key
# Optional overrides
DEFAULT_LLM_PROVIDER=gemini
DEFAULT_MODEL=gemini-2.5-pro

Start the server:

npm start

See docs/TESTING.md for instructions on how to run tests.

Docker

The repository includes a helper script for one-command setup. It builds the image, saves your GEMINI_API_KEY and configures the container to start automatically whenever you log in:

bash scripts/docker-setup.sh

This script:

• Creates ~/vibe-check-mcp for persistent data
• Builds the Docker image and sets up docker-compose.yml
• Prompts for your API key and writes ~/vibe-check-mcp/.env
• Installs a systemd service (Linux) or LaunchAgent (macOS) so the container starts at login
• Generates vibe-check-tcp-wrapper.sh which proxies Cursor IDE to the server After running it, open Cursor IDE → Settings → MCP and add a new server of type Command pointing to:

~/vibe-check-mcp/vibe-check-tcp-wrapper.sh

See Automatic Docker Setup for full details. If you prefer to run the commands manually:

docker build -t vibe-check-mcp .
docker run -e GEMINI_API_KEY=your_gemini_api_key -p 3000:3000 vibe-check-mcp

Integrating with Claude Desktop

Add to claude_desktop_config.json:

"vibe-check": {
  "command": "node",
  "args": ["/path/to/vibe-check-mcp/build/index.js"],
  "env": { "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY" }
}

Usage Examples

import { vibe_check } from 'vibe-check-mcp';
const result = await vibe_check({
  goal: 'Write unit tests',
  plan: 'Use vitest for coverage',
  sessionId: 'demo1'
});
console.log(result.questions);

Adaptive Metacognitive Interrupts (CPI)

Agent Prompting Essentials

In your agent's system prompt, make it clear that vibe_check is a mandatory tool for reflection. Always pass the full user request and other relevant context. After correcting a mistake, you can optionally log it with vibe_learn to build a history for future analysis.

Example snippet:

As an autonomous agent you will:
1. Call vibe_check after planning and before major actions.
2. Provide the full user request and your current plan.
3. Optionally, record resolved issues with vibe_learn.

When to Use Each Tool

Documentation

• Agent Prompting Strategies
• Advanced Integration
• Technical Reference
• Automatic Docker Setup
• Philosophy
• Case Studies
• Changelog

Research & Philosophy

See docs/philosophy.md for the alignment research behind VibeCheck. The approach draws inspiration from Reflexion, Constitutional AI and other high-trust frameworks.

Security

This repository includes a CI-based security scan that runs on every pull request. It checks dependencies with npm audit and scans the source for risky patterns. See SECURITY.md for details and how to report issues.

Roadmap

1. Benchmarks and latency profiling
2. Adaptive tuning based on agent performance
3. Multi-agent cooperation support
4. Optional human-in-the-loop review

Contributing & Community

Contributions are welcome! See CONTRIBUTING.md and join our Discord for discussion.

FAQ

• Does it increase latency? A single CPI call typically adds ~1 second depending on the provider.
• Can I disable logging? Yes, vibe_learn is optional.

Find VibeCheck MCP on

• 🌐 MSEEP
• 📡 MCP Servers
• 🧠 MCP.so
• 🛠️ Creati.ai
• 💡 Pulse MCP
• 📘 Playbooks.com
• 🧰 MCPHub.tools
• 📇 MCP Directory
• 🧙 MagicSlides
• 🗃️ AIAgentsList

Star History

Credits & License

VibeCheck MCP is released under the MIT License. Built for reliable, enterprise-ready AI agents.