← Back to directory
V

Vibe Check MCP

Community
KISS overzealous agents goodbye: plug & play agent oversight tool.
GitHub source repository ↗
★ 502 Stars Category · Dev Tools Very popular Source revision ed8452f2d626
63FMRS · C
Reliability
10/20
Security and permissions
12/20
Maintenance
13/20
Documentation
14/20
Setup experience
14/20

Vibe Check MCP offers a unique metacognitive oversight layer with research-backed CPI methodology. It is easy to integrate (npx + MCP clients) and supports multiple LLM providers. However, the server is in maintenance mode (only security/bug fixes), and reliance on external LLMs introduces cost and privacy considerations.

Read the FMRS scoring method →

Vibe Check MCP is a lightweight server implementing Anthropic's Model Context Protocol (MCP). It acts as an AI meta-mentor for your agents, interrupting pattern inertia with Chain-Pattern Interrupts (CPI) to prevent Reasoning Lock-In (RLI). It keeps agents on the minimal viable path, escalating complexity only when evidence demands it. The server invokes a second LLM to provide metacognitive feedback, helping agents pause and reflect before major actions, improving alignment, common sense, and safety. Research-backed: in evaluations, agents using Vibe Check improved success by ~27% and halved harmful actions (-41%).

Tools

vibe_check
Challenges assumptions and prevents tunnel vision after planning and before major actions.
vibe_learn
Logs mistakes, preferences, and successes for future reflection and self-improvement.
update_constitution
Sets or merges session rules for a given sessionId that the CPI layer will enforce.
reset_constitution
Clears session rules for a given session.
check_constitution
Inspects the effective rules for a given session.

Setup

  1. Ensure Node.js >= 20. 2. Run npx -y @pv-bhat/vibe-check-mcp start --stdio for stdio or --http --port 2091 for HTTP. 3. Obtain a Gemini API key (default provider) or optionally keys for OpenAI, OpenRouter, or Anthropic. 4. Add the server entry to your MCP client config (e.g., Claude Desktop, Cursor, Windsurf, VS Code). 5. Optionally set environment variables DEFAULT_LLM_PROVIDER and DEFAULT_MODEL to choose the provider and model.
claude_desktop_config.json
{
  "mcpServers": {
    "vibe-check-mcp": {
      "command": "npx",
      "args": ["-y", "@pv-bhat/vibe-check-mcp", "start", "--stdio"]
    }
  }
}

Fit and risk

Best for

  • Developers and teams building AI agents that need extra oversight to prevent reasoning lock-in and over-engineering.
  • Users working with MCP clients like Claude Desktop, Cursor, Windsurf, or VS Code who want long-horizon workflows to stay on track.
  • Developers seeking research-backed reliability improvements for agents.

Not for

  • Simple or fast tasks where an external oversight call adds unwanted latency and cost.
  • Scenarios where you cannot or do not want to rely on external LLM API calls (requires at least one provider key).
  • Projects requiring active feature development or official support, as the server is in maintenance mode.

Required permissions

  • Requires at least one LLM provider API key (Gemini, OpenAI, OpenRouter, or Anthropic) to function.
  • HTTP mode opens a network port; recommend restricting to loopback for security.
  • May modify client configuration files (e.g., Claude Desktop, Cursor, Windsurf, VS Code) during installation to add the server entry.

Risks and side effects

  • Sending prompts and context to external LLM APIs; ensure sensitive data is not exposed.
  • HTTP mode with non-loopback access increases attack surface; v2.9.0 adds host validation and CORS restrictions but misconfiguration could cause outages.
  • Over-frequent `vibe_check` calls can slow down agent execution and increase costs; optimal dose is ~10-20% of steps.

Troubleshooting

  1. Check Node.js version (>=20) if startup fails.
  2. Ensure at least one API key is set; if keeping Gemini as default, set `GEMINI_API_KEY`.
  3. If HTTP requests are rejected, verify `MCP_ALLOWED_HOSTS` includes your hostname or set to `*` to disable the check.
  4. If encountering rate limits or errors, review model compatibility and consider using `modelOverride`.
  5. Use `npx -y @pv-bhat/vibe-check-mcp doctor` (if available) to diagnose configuration issues.

Use cases

Coding tasks: check plans before writing code to avoid over-engineering.
Ambiguous tasks: help agents navigate unclear requirements and stay aligned.
High-risk tasks: inject reflective pauses before irreversible actions to reduce harmful behavior.

Supported clients

Claude DesktopFull support
CursorFull support
WindsurfFull support
Visual Studio CodeFull support