home / mcp / vibe check mcp server

Vibe Check MCP Server

Vibe Check is a tool that provides mentor-like feedback to AI Agents, preventing tunnel-vision, over-engineering and reasoning lock-in for complex and long-horizon agent workflows. KISS your over-eager AI Agents goodbye! Effective for: Coding, Ambiguous Tasks, High-Risk tasks

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "pv-bhat-vibe-check-mcp-server": {
      "url": "http://127.0.0.1:2091",
      "headers": {
        "DEFAULT_MODEL": "gemini-2.5-pro",
        "GEMINI_API_KEY": "your_gemini_key",
        "OPENAI_API_KEY": "your_openai_key",
        "ANTHROPIC_API_KEY": "your_anthropic_key",
        "ANTHROPIC_VERSION": "2023-06-01",
        "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
        "OPENROUTER_API_KEY": "your_openrouter_key",
        "ANTHROPIC_AUTH_TOKEN": "your_auth_token",
        "DEFAULT_LLM_PROVIDER": "gemini"
      }
    }
  }
}

Vibe Check MCP is a plug-and-play mentor layer that helps keep your agents on the minimal viable path while surfacing risk, uncertainty, and reflective feedback. It acts as an external metacognitive supervisor, interrupting pattern inertia so your agents stay aligned, safe, and capable of better decision-making.

How to use

You run the Vibe Check MCP server and connect it to an MCP-aware client. Choose a transport option based on your workflow: use STDIO when your client can spawn processes directly, or use HTTP when you want an isolated, networked service.

How to install

Prerequisites: Node.js version 20 or newer.

Option 1: Run via STDIO with an MCP client (recommended for tight integration). You launch the server from your client using the following command. Then configure the client to spawn the server using the provided block.

Option 2: Run via HTTP for a standalone service you can query with JSON-RPC. You start the server with HTTP transport and a port, then send requests to the health endpoint and RPC endpoint.

Configuration and quick references

This server supports two primary MCP connection methods. The STDIO method runs locally via the npx command, while the HTTP method exposes a networked endpoint on a configurable port.

Security and maintenance

Keep API keys and provider credentials in environment variables. Review startup logs for transport status and health signals. When uninstalling, revert to backups created during installation and remove the MCP entry from your client configuration.

Usage: example configurations

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

Usage: HTTP transport example

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

- Health: curl http://127.0.0.1:2091/health
- RPC: curl http://127.0.0.1:2091/rpc

What happens when I run with HTTP vs STDIO

STDIO: The server launches as a child process and communicates with your MCP client through standard I/O streams. This is ideal for embedded workflows where you want tight coupling with your client. HTTP: The server runs as a standalone service reachable at a local port. This is ideal when you want a decoupled, network-accessible MCP server.

Notes on transports and ports

When using HTTP, you can specify the port with --port or via MCP_HTTP_PORT. The default port is 2091.

Agent prompts and tools

Integrate vibe_check into your agent prompts so it is invoked after planning and before major actions. This helps surface reflections and maintain alignment while avoiding reasoning drift.

Troubleshooting

If the server is not responding, verify the transport configuration in your MCP client, confirm the port is reachable, and check that the server process is running. For HTTP, confirm the health endpoint returns a live status.

Development and testing notes

The server can be run in a development flow with npm-based commands. Ensure you have Node.js >= 20, install dependencies, build, and run tests as part of your workflow.

Additional sections

The Vibe Check MCP implements a meta-cognitive signaling layer and Chain-Pattern Interrupts (CPI) to prompt reflection at risk inflection moments. It surfaces traits, uncertainty, and risk scores to guide decision-making and prevent overengineering.

Available tools

vibe_check

Invoke a metacognitive signal to surface reflection and surface risk cues before major actions.

vibe_learn

Optionally log mistakes and fixes to build a historical reflection for future use.

update_constitution

Set or merge per-session rules that CPI will enforce during a session.

reset_constitution

Clear per-session rules to reset the CPI constraints.

check_constitution

Inspect the effective rules applied to a given session.