Vibe Check

What is Vibe Check MCP?

Vibe Check MCP is a Model Context Protocol (MCP) server designed to act as an external oversight layer for AI coding agents. It "vibe checks" agents by pausing them at critical moments to challenge assumptions and prevent common AI workflow issues like scope creep, code bloat, misalignment, misinterpretation, tunnel vision, and overcomplication. It also self-improves accuracy and user alignment over time by recording what worked and what failed, ensuring smarter subsequent runs.

How to use Vibe Check MCP?

To use Vibe Check MCP, you first need to install it. You can clone the repository, install dependencies with npm install, build with npm run build, and then start the server with npm start. Node 20+ is required. Alternatively, a Docker setup is provided for easier installation and automatic startup. You'll need to provide your GEMINI_API_KEY in a .env file or as an environment variable for Docker.

Once installed, integrate Vibe Check into your agent's system prompt. It's crucial to make vibe_check a mandatory pattern interrupt. You should pass the full user request and specify the current phase (planning, implementation, or review). After correcting a mistake, log it with vibe_learn so the system can recognize it in the future.

Example agent prompting 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. Record resolved issues with vibe_learn so future checks get smarter.

Key Features of Vibe Check MCP

vibe_check: This is the core pattern interrupt tool. It uses the learnlm-2.0-flash-experimental model (with fallbacks to gemini-2.5-flash and gemini-2.0-flash) for large context awareness (up to 1M tokens) to challenge assumptions and prevent tunnel vision.
vibe_learn: This tool records mistakes, preferences, and successes, building a rich learning history. This history feeds back into vibe_check, making future checks smarter.
Large context awareness: The full learning log is summarized and included in prompts, allowing the model to identify recurring patterns and reinforce successful approaches.

These two tools work in conjunction: vibe_check interrupts questionable plans, vibe_learn captures the lesson, and the growing log informs subsequent vibe_check calls.

Use Cases of Vibe Check MCP

Vibe Check MCP is designed for scenarios where AI coding agents are prone to "pattern inertia," meaning they tend to stick to their initial solution even if it deviates from the original goal. Its primary use cases include:

Preventing agentic cascade errors: By providing an external oversight layer, Vibe Check helps prevent errors from propagating through complex AI workflows.
Enhancing complex workflow strategy: It nudges agents back to the user's actual needs, improving the overall strategy and alignment of AI-driven tasks.
Mitigating tunnel vision and overcomplication: The vibe_check tool specifically addresses these issues by forcing moments of reflection and challenging assumptions.
Improving agent resilience and alignment: Through continuous learning via vibe_learn, agents become more robust and better aligned with user intentions.

FAQ about Vibe Check MCP

Q: What problem does Vibe Check solve? A: Vibe Check addresses "pattern inertia" in LLMs, where agents stick to initial solutions even if they drift from the goal, leading to misalignment, overengineering, and wasted cycles.

Q: What models does vibe_check use? A: It primarily uses learnlm-2.0-flash-experimental, with automatic fallbacks to gemini-2.5-flash and gemini-2.0-flash.

Q: How does Vibe Check learn? A: The vibe_learn tool records mistakes, preferences, and successes, building a learning history that informs future vibe_check calls.

Q: Can I use Vibe Check with Docker? A: Yes, a helper script is provided for one-command Docker setup, which builds the image, saves your API key, and configures the container to start automatically.

Q: How do I integrate Vibe Check into my agent's prompt? A: You should explicitly instruct your agent to call vibe_check at key moments (e.g., after planning, before major actions) and to use vibe_learn to record resolved issues.

🧠 Vibe Check MCP

The Most Widely-Deployed Feedback Layer in the MCP Ecosystem

Used in 1,000+ real workflows.
Featured across 10+ orchestration platforms.
6.5K+ developers already trust it to prevent agentic cascade errors.

What is Vibe Check?

Vibe Check is a metacognitive layer that keeps AI coding agents honest. It pauses the agent at key moments, challenges shaky assumptions and records what worked (or failed) so the next run is smarter. Think of it as the agent's inner rubber duck—always nudging the conversation back to the user's actual needs.

TL;DR: Vibe Check makes AI coding agents more resilient and aligned by enforcing moments of reflection.

The Problem: Pattern Inertia

LLMs often follow the first solution they imagine. Once that pattern takes hold they elaborate on it even if it drifts from the original goal. Without an external nudge the agent seldom questions its direction, leading to misalignment, overengineering and wasted cycles.

Key Features

vibe_check – pattern interrupt tool using the learnlm-2.0-flash-experimental model (with automatic fallback to gemini-2.5-flash and gemini-2.0-flash) for up to a 1M token context window.
vibe_learn – records mistakes, preferences and successes to build a rich learning history that feeds back into vibe_check.
Large context awareness – the full learning log is summarized and included in prompts so the model can spot recurring patterns and reinforce successful approaches.

These two tools feed each other. vibe_check interrupts questionable plans, vibe_learn captures the lesson, and the growing log informs the next vibe_check call via the model's 1M token context window.

[vibe_check] <----> [vibe_learn]
      ^                |
      |________________|

The more your agent works, the more context Vibe Check has to keep it on the right path.

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 your API key:

GEMINI_API_KEY=your_gemini_api_key

Start the server:

npm start

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" }
}

Agent Prompting Essentials

In your agent's system prompt make it clear that vibe_check is a mandatory pattern interrupt. Always pass the full user request and specify the current phase (planning, implementation, or review). After correcting a mistake, log it with vibe_learn so the system can recognize it next time.

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. Record resolved issues with vibe_learn so future checks get smarter.

When to Use Each Tool

Tool	Purpose
🛑 vibe_check	Challenge assumptions and prevent tunnel vision
🔄 vibe_learn	Capture mistakes, preferences and successes

Documentation

To-do List

Add in integration for OpenRouter Keys
Repomix access to pass repositories to VC
Agents.md addendum to improve plug-and-play integration

Contributing

Contributions are welcome! See CONTRIBUTING.md.

🔗 Find VibeCheck MCP on:

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

License

MIT

Login Required

Please log in to share your review and rating for this MCP.

Vibe Check Overview