Vibe Check

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.

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.

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 🔗

Table of Contents

• Quickstart (npx)
• What is Vibe Check MCP?
• Overview
• The Problem: Pattern Inertia & Reasoning Lock-In
• Key Features
• What's New
• Development Setup
• Release
• Usage Examples
• Adaptive Metacognitive Interrupts (CPI)
• Agent Prompting Essentials
• When to Use Each Tool
• Documentation
• Research & Philosophy
• Security
• Roadmap
• Contributors & Community
• FAQ
• Listed on
• Credits & License

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

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.

…