by PV-Bhat
Provides metacognitive sanity checks for autonomous AI agents, interrupting pattern inertia and preventing reasoning lock‑in through adaptive Critical Path Interrupts.
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.
npx..env file with the required API keys (GEMINI_API_KEY, optional OPENAI_API_KEY, OPENROUTER_API_KEY).npm start (or the provided npx command) launches the MCP server on the default port.vibe_check tool with parameters such as goal, plan, and optional sessionId. Optionally log corrections with vibe_learn.sessionId is supplied.vibe_learn captures mistakes for future self‑improvement.vibe_learn is optional and can be omitted from tool calls.npm install) or use the provided Docker setup which handles the build automatically.Adaptive metacognitive oversight for autonomous AI agents – a research-backed MCP server keeping LLMs aligned, reflective and safe.
~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.
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.
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.
| Feature | Description | Benefits |
|---|---|---|
| CPI Adaptive Interrupts | Phase-aware prompts that challenge assumptions | alignment, robustness |
| Multi-provider LLM | Gemini, OpenAI and OpenRouter support | flexibility |
| History Continuity | Summarizes prior advice when sessionId is supplied |
context retention |
| Optional vibe_learn | Log mistakes and fixes for future reflection | self-improvement |
vibe_learn logging# 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.
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:
~/vibe-check-mcp for persistent datadocker-compose.yml~/vibe-check-mcp/.envvibe-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
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" }
}
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);
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.
| Tool | Purpose |
|---|---|
| 🛑 vibe_check | Challenge assumptions and prevent tunnel vision |
| 🔄 vibe_learn | Capture mistakes, preferences and successes |
See docs/philosophy.md for the alignment research behind VibeCheck. The approach draws inspiration from Reflexion, Constitutional AI and other high-trust frameworks.
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.
Contributions are welcome! See CONTRIBUTING.md and join our Discord for discussion.
vibe_learn is optional.VibeCheck MCP is released under the MIT License. Built for reliable, enterprise-ready AI agents.
Please log in to share your review and rating for this MCP.
{
"mcpServers": {
"vibe-check-mcp": {
"command": "npx",
"args": [
"-y",
"vibe-check-mcp"
],
"env": {
"GEMINI_API_KEY": "<YOUR_GEMINI_API_KEY>",
"OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>",
"OPENROUTER_API_KEY": "<YOUR_OPENROUTER_API_KEY>"
}
}
}
}claude mcp add vibe-check-mcp npx -y vibe-check-mcpExplore related MCPs that share similar capabilities and solve comparable challenges
by activepieces
A self‑hosted, open‑source platform that provides a no‑code builder for creating, versioning, and running AI‑driven automation workflows. Pieces are TypeScript‑based plugins that become MCP servers, allowing direct consumption by large language models.
by Skyvern-AI
Automates browser‑based workflows by leveraging large language models and computer‑vision techniques, turning natural‑language prompts into fully functional web interactions without writing custom scripts.
by ahujasid
Enables Claude AI to control Blender for prompt‑assisted 3D modeling, scene creation, and manipulation via a socket‑based Model Context Protocol server.
by PipedreamHQ
Connect APIs quickly with a free, hosted integration platform that enables event‑driven automations across 1,000+ services and supports custom code in Node.js, Python, Go, or Bash.
by elie222
Organizes email inbox, drafts replies in the user's tone, tracks follow‑ups, and provides analytics to achieve inbox zero quickly.
by grab
Enables Cursor AI to read and programmatically modify Figma designs through a Model Context Protocol integration.
by CursorTouch
Enables AI agents to control the Windows operating system, performing file navigation, application launching, UI interaction, QA testing, and other automation tasks through a lightweight server.
by ahujasid
Enables Claude AI to control Ableton Live in real time, allowing AI‑driven creation, editing, and playback of tracks, clips, instruments, and effects through a socket‑based server.
by leonardsellem
Provides tools and resources to enable AI assistants to manage and execute n8n workflows via natural language commands.