MCP Server

Active

MIT

io.github.PV-Bhat/vibe-check-mcp-server MCP Server

io.github.PV-Bhat/vibe-check-mcp-server

Adds research-backed Chain-Pattern Interrupts so AI agents pause, reflect, and avoid reasoning lock-in.

What is the io.github.PV-Bhat/vibe-check-mcp-server MCP server?

The Vibe Check MCP server is a Model Context Protocol server that provides metacognitive oversight for AI agents by injecting Chain-Pattern Interrupts (CPI) — brief, evidence-triggered reflective pauses that challenge assumptions before an agent takes major or irreversible actions. It acts as an external "mentor layer," calling a second LLM (Gemini, OpenAI, Anthropic, or OpenRouter) to review an agent's plan and surface risks, uncertainty, or reasoning lock-in. It also supports per-session "constitution" rules and a learning log so agents can record and reflect on past mistakes.

Vibe Check MCP is a lightweight, research-backed server implementing Anthropic's Model Context Protocol that gives AI agents a built-in "sanity check" mechanism. It uses Chain-Pattern Interrupts (CPI) to pause an agent at risk-inflection points, prompting reflection before overengineering or misaligned actions cascade. The server supports multiple LLM providers, session history continuity, per-session rule enforcement via a "constitution," and optional logging of mistakes/fixes for future self-improvement. It is currently in maintenance mode (security/bug fixes only) but remains fully functional, with STDIO and HTTP transport support and CLI installers for Claude Desktop, Cursor, Windsurf, and VS Code.

How to install io.github.PV-Bhat/vibe-check-mcp-server

Copy-paste configuration for popular MCP clients.

transport: stdio

Config generated by PluginBench — verify against the source before use.

Environment / auth

YOUR_API_KEY
required
secret
Your API key for the service

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "vibe-check-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@pv-bhat/vibe-check-mcp"
      ],
      "env": {
        "YOUR_API_KEY": "<YOUR_YOUR_API_KEY>"
      }
    }
  }
}

Tools & capabilities

Tools this server exposes to the agent.

vibe_check — Calls a second LLM to challenge assumptions, surface risks, and prevent tunnel vision; meant to be called after planning and before major agent actions.
vibe_learn — Logs mistakes, preferences, and successes so agents can reflect on and learn from past issues.
update_constitution — Merges or sets a per-session rule set (a 'constitution') that the CPI layer will enforce, e.g. 'no external network calls' or 'never write secrets to disk'.
reset_constitution — Clears the rule set for a given session.
check_constitution — Returns the effective rules currently in force for a session.

Use cases

Insert a mandatory reflection checkpoint in an agent's system prompt to catch flawed plans before irreversible actions
Enforce session-specific safety rules (e.g., no network calls, no writing secrets to disk) that persist across an agent's run
Log and review past agent mistakes and fixes via vibe_learn to improve future task performance
Add metacognitive oversight to agents built with Claude Desktop, Cursor, Windsurf, or VS Code via MCP
Reduce overengineering and reasoning lock-in in autonomous coding or task-execution agents

io.github.PV-Bhat/vibe-check-mcp-server MCP server FAQ

What does Vibe Check MCP do?

It adds a metacognitive oversight layer to AI agents using Chain-Pattern Interrupts (CPI), which pause the agent at risky decision points and call a second LLM to challenge assumptions before the agent proceeds. Research cited in the README reports a 27% improvement in success rate and roughly halved harmful actions when agents use it.

Is Vibe Check MCP free?

The server itself is free and open-source under the MIT license. You need your own API key(s) for the LLM provider(s) you configure (Gemini, OpenAI, Anthropic, or OpenRouter), which may incur usage costs from those providers.

How do I install Vibe Check MCP in Claude Desktop or Cursor?

Run it via npx (`npx -y @pv-bhat/vibe-check-mcp start --stdio`) and add the corresponding entry to your client's MCP config file — `claude_desktop_config.json` for Claude Desktop or `~/.cursor/mcp.json` for Cursor. The project also ships CLI installers that automatically add and manage these config entries.

What authentication or API keys are required?

You need an API key for at least one supported LLM provider (GEMINI_API_KEY by default, or OPENAI_API_KEY, OPENROUTER_API_KEY, ANTHROPIC_API_KEY) set in a .env file or environment variables, since Vibe Check calls a second LLM to generate its meta-cognitive feedback.

Is this project actively developed?

No — as of the README, the project is in maintenance mode. Active feature development has ended and only security/bug-fix patches are published (latest is v2.8.1), though the server remains fully functional and community forks are welcomed.

What transports does the server support?

It supports both STDIO (for MCP-aware clients like Claude Desktop, Cursor, Windsurf) and streamable HTTP transport (default port 2091), selectable via CLI flags or the MCP_TRANSPORT environment variable.

README (reference)

Source of truth, from the repository.

Vibe Check MCP

This project is in maintenance mode. Active feature development has ended; only maintenance patches (security and bug fixes) are published. v2.8.1 is the latest maintenance release. The server remains fully functional. Community forks and contributions are welcome under the MIT license.

<p align="center"><b>KISS overzealous agents goodbye. Plug & play agent oversight tool.</b></p> <p align="center"> <b>Based on research:</b><br/> In our study agents calling Vibe Check improved success +27% and halved harmful actions -41% </p> <p align="center"> <a href="https://www.researchgate.net/publication/394946231_Do_AI_Agents_Need_Mentors_Evaluating_Chain-Pattern_Interrupt_CPI_for_Oversight_and_Reliability?channel=doi&linkId=68ad6178ca495d76982ff192&showFulltext=true"> <img src="https://img.shields.io/badge/Research-CPI%20%28MURST%29-blue?style=flat-square" alt="CPI Research"> </a> <a href="https://github.com/modelcontextprotocol/servers"><img src="https://img.shields.io/badge/Anthropic%20MCP-featured-111?labelColor=111&color=555&style=flat-square" alt="Anthropic MCP: listed"></a> <a href="https://registry.modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP%20Registry-listed-555?labelColor=111&style=flat-square" alt="MCP Registry"></a> <a href="https://www.pulsemcp.com/servers/pv-bhat-vibe-check"> <img src="https://img.shields.io/badge/PulseMCP-Most%20Popular%20(Oct 2025)-0b7285?style=flat-square" alt="PulseMCP: Most Popular (this week)"> </a> <a href="https://github.com/PV-Bhat/vibe-check-mcp-server/actions/workflows/ci.yml"><img src="https://github.com/PV-Bhat/vibe-check-mcp-server/actions/workflows/ci.yml/badge.svg" alt="CI passing"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0b7285?style=flat-square" alt="MIT License"></a> </p> <p align="center"> <sub> Featured on PulseMCP “Most Popular (This Week)” • 5k+ monthly calls on Smithery.ai • research-backed oversight • STDIO + streamable HTTP transport</sub> </p> <img width="500" height="300" alt="Gemini_Generated_Image_kvdvp4kvdvp4kvdv" src="https://github.com/user-attachments/assets/ff4d9efa-2142-436d-b1df-2a711a28c34e" />

Plug-and-play mentor layer that stops agents from over-engineering and keeps them on the minimal viable path — research-backed MCP server keeping LLMs aligned, reflective and safe.

<div align="center"> <a href="https://github.com/PV-Bhat/vibe-check-mcp-server"> <img src="https://unpkg.com/@lobehub/icons-static-svg@latest/icons/github.svg" width="40" height="40" alt="GitHub" /> </a>    <a href="https://registry.modelcontextprotocol.io"> <img src="https://unpkg.com/@lobehub/icons-static-svg@latest/icons/anthropic.svg" width="40" height="40" alt="Anthropic MCP Registry" /> </a>    <a href="https://smithery.ai/server/@PV-Bhat/vibe-check-mcp-server"> <img src="https://unpkg.com/@lobehub/icons-static-svg@latest/icons/smithery.svg" width="40" height="40" alt="Smithery" /> </a>    <a href="https://www.pulsemcp.com/servers/pv-bhat-vibe-check"> <img src="https://www.pulsemcp.com/favicon.ico" width="40" height="40" alt="PulseMCP" /> </a> </div> <div align="center"> <em>Trusted by developers across MCP platforms and registries</em> </div>

Quickstart (npx)

Run the server directly from npm without a local installation. Requires Node >=20. Choose a transport:

Option 1 – MCP client over STDIO

npx -y @pv-bhat/vibe-check-mcp start --stdio

Launch from an MCP-aware client (Claude Desktop, Cursor, Windsurf, etc.).
[MCP] stdio transport connected indicates the process is waiting for the client.
Add this block to your client config so it spawns the command:

{
  "mcpServers": {
    "vibe-check-mcp": {
      "command": "npx",
      "args": ["-y", "@pv-bhat/vibe-check-mcp", "start", "--stdio"]
    }
  }
}

Option 2 – Manual HTTP inspection

npx -y @pv-bhat/vibe-check-mcp start --http --port 2091

curl http://127.0.0.1:2091/health to confirm the service is live.
Send JSON-RPC requests to http://127.0.0.1:2091/rpc.

npx downloads the package on demand for both options. For detailed client setup and other commands like install and doctor, see the documentation below.

Recognition

Featured on PulseMCP “Most Popular (This Week)” front page (week of 13 Oct 2025) 🔗
Listed in Anthropic’s official Model Context Protocol repo 🔗
Discoverable in the official MCP Registry 🔗
Featured on Sean Kochel's Top 9 MCP servers for vibe coders 🔗

What is Vibe Check MCP?

Vibe Check MCP keeps agents on the minimal viable path and escalates complexity only when evidence demands it. Vibe Check 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 Chain-Pattern 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.

Overview

Vibe Check MCP pairs a metacognitive signal layer with CPI so agents can pause when risk spikes. Vibe Check surfaces traits, uncertainty, and risk scores; CPI consumes those triggers and enforces an intervention policy before the agent resumes. See the CPI integration guide and the CPI repo at https://github.com/PV-Bhat/cpi for wiring details.

Vibe Check invokes a second LLM to give meta-cognitive feedback to your main agent. Integrating vibe_check calls into agent system prompts and instructing tool calls before irreversible actions significantly improves agent alignment and common-sense. The high-level component map: docs/architecture.md, while the CPI handoff diagram and example shim are captured in docs/integrations/cpi.md.

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. Vibe Check provides that nudge through short reflective pauses, improving reliability and safety.

Key Features

Feature	Description	Benefits
CPI Adaptive Interrupts	Phase-aware prompts that challenge assumptions	alignment, robustness
Multi-provider LLM	Gemini, OpenAI, Anthropic, 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

What's New in v2.8.1 (Maintenance Release)

Maintenance Notice: This project is in maintenance mode and is no longer under active feature development. It remains fully functional and available under the MIT license. Community forks are welcome. For details, see the Changelog.

npm release: v2.8.0 was never published to npm; v2.8.1 ships all of its fixes to the registry, including everything below
Bug fix (v2.8.0): check_constitution now returns valid MCP content types (fixes #84)
Security (v2.8.0): All dependencies updated — resolves 14 npm audit vulnerabilities (axios, MCP SDK, diff, express, and transitive deps)
MCP SDK 1.26 (v2.8.0): Updated to latest SDK with critical cross-client data leakage fix; HTTP transport adapter updated for compatibility
Housekeeping: registry metadata (server.json, smithery.yaml, CITATION.cff) re-synced to the release version, dev-only vitest advisory cleared, GitHub Releases automated on tag push

Session Constitution (per-session rules)

Use a lightweight “constitution” to enforce rules per sessionId that CPI will honor. Eg. constitution rules: “no external network calls,” “prefer unit tests before refactors,” “never write secrets to disk.”

API (tools):

update_constitution({ sessionId, rules }) → merges/sets rule set for the session
reset_constitution({ sessionId }) → clears session rules
check_constitution({ sessionId }) → returns effective rules for the session

Development Setup

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

Use npm for all workflows (npm ci, npm run build, npm test). This project targets Node >=20.

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

# Gemini (default)
GEMINI_API_KEY=your_gemini_api_key
# Optional providers / Anthropic-compatible endpoints
OPENAI_API_KEY=your_openai_api_key
OPENROUTER_API_KEY=your_openrouter_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key
ANTHROPIC_AUTH_TOKEN=your_proxy_bearer_token
ANTHROPIC_BASE_URL=https://api.anthropic.com
ANTHROPIC_VERSION=2023-06-01
# Optional overrides
# DEFAULT_LLM_PROVIDER accepts gemini | openai | openrouter | anthropic
DEFAULT_LLM_PROVIDER=gemini
DEFAULT_MODEL=gemini-2.5-pro

Configuration

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

Docker

The repository includes a helper script for one-command setup.

bash scripts/docker-setup.sh

See Automatic Docker Setup for full details.

Provider keys

See API Keys & Secret Management for supported providers, resolution order, storage locations, and security guidance.

Transport selection

The CLI supports stdio and HTTP transports. Transport resolution follows this order: explicit flags (--stdio/--http) → MCP_TRANSPORT → default stdio. When using HTTP, specify --port (or set MCP_HTTP_PORT); the default port is 2091. The generated entries add --stdio or --http --port <n> accordingly, and HTTP-capable clients also receive a http://127.0.0.1:<port> endpoint.

Client installers

Each installer is idempotent and tags entries with "managedBy": "vibe-check-mcp-cli". Backups are written once per run before changes are applied, and merges are atomic (*.bak files make rollback easy). See docs/clients.md for deeper client-specific references.

Claude Desktop

Config path: claude_desktop_config.json (auto-discovered per platform).
Default transport: stdio (npx … start --stdio).
Restart Claude Desktop after installation to load the new MCP server.
If an unmanaged entry already exists for vibe-check-mcp, the CLI leaves it untouched and prints a warning.

Cursor

Config path: ~/.cursor/mcp.json (provide --config if you store it elsewhere).
Schema mirrors Claude’s mcpServers layout.
If the file is missing, the CLI prints a ready-to-paste JSON block for Cursor’s settings panel instead of failing.

Windsurf (Cascade)

Config path: legacy ~/.codeium/windsurf/mcp_config.json, new builds use ~/.codeium/mcp_config.json.
Pass --http to emit an entry with serverUrl for Windsurf’s HTTP client.
Existing sentinel-managed serverUrl entries are preserved and updated in place.

Visual Studio Code

Workspace config lives at .vscode/mcp.json; profiles also store mcp.json in your VS Code user data directory.
Provide --config <path> to target a workspace file. Without --config, the CLI prints a JSON snippet and a vscode:mcp/install?... link you can open directly from the terminal.
VS Code supports optional dev fields; pass --dev-watch and/or --dev-debug <value> to populate dev.watch/dev.debug.

Uninstall & rollback

Restore the backup generated during installation (the newest *.bak next to your config) to revert immediately.
To remove the server manually, delete the vibe-check-mcp entry under mcpServers (Claude/Windsurf/Cursor) or servers (VS Code) as long as it is still tagged with "managedBy": "vibe-check-mcp-cli".

Research & Philosophy

CPI (Chain-Pattern Interrupt) is the research-backed oversight method behind Vibe Check. It injects brief, well-timed “pause points” at risk inflection moments to re-align the agent to the user’s true priority, preventing destructive cascades and reasoning lock-in (RLI). In pooled evaluation across 153 runs, CPI nearly doubles success (~27%→54%) and roughly halves harmful actions (~83%→42%). Optimal interrupt dosage is ~10–20% of steps. Vibe Check MCP implements CPI as an external mentor layer at test time.

Links:

📄 CPI Paper (ResearchGate) — http://dx.doi.org/10.13140/RG.2.2.18237.93922
📘 CPI Reference Implementation (GitHub): https://github.com/PV-Bhat/cpi
📚 MURST Zenodo DOI (RSRC archival): https://doi.org/10.5281/zenodo.14851363

flowchart TD
  A[Agent Phase] --> B{Monitor Progress}
  B -- high risk --> C[CPI Interrupt]
  C --> D[Reflect & Adjust]
  B -- smooth --> E[Continue]

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

Tool	Purpose
🛑 vibe_check	Challenge assumptions and prevent tunnel vision
🔄 vibe_learn	Capture mistakes, preferences, and successes
🧰 update_constitution	Set/merge session rules the CPI layer will enforce
🧹 reset_constitution	Clear rules for a session
🔎 check_constitution	Inspect effective rules for a session

Documentation

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

Note: This project is in maintenance mode (latest maintenance release: v2.8.1). The roadmap below is preserved for community forks that may wish to continue development.

Structured output for vibe_check: Return a JSON envelope such as { advice, riskScore, traits } so downstream agents can reason deterministically.
LLM resilience: Wrap generateResponse with retries and exponential backoff.
Input sanitization: Validate and cleanse tool arguments to mitigate prompt-injection vectors.
Prompt externalization: Move hardcoded prompts to configuration files for transparency and auditability (see PR #71).

Contributors & Community

Contributions are welcome! See CONTRIBUTING.md.

Credits & License

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

Author Credits & Links

Apache-2.0

View repository →

Pact Tooling