Vibe Check MCP
A second-model mentor that interrupts tunnel vision before an AI agent commits to a risky or overengineered plan.
- Source repo
- PV-Bhat/vibe-check-mcp-server
- Stars
- ★ 504
- Last updated
- 2mo ago
- License
- MIT
- Primary language
- TypeScript
- FA score
- 81/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformClaude.ai · OpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A developer using Cursor, Windsurf, or Claude Desktop wants an agent to reconsider assumptions before a large refactor, dependency migration, or irreversible code change.
- Not a fit if
- Teams expecting ongoing feature development; the project is in maintenance mode
- Teams serving HTTP on a non-loopback hostname without configuring MCP_ALLOWED_HOSTS
- Source review
- 81/100 · Good
What does this agent do, and when should you use it?
Vibe Check MCP is a self-hosted Model Context Protocol server that asks a separate mentor model to review an agent's goal, plan, uncertainty, and risk. Its interface includes the vibe_check reflection tool, optional vibe_learn history capture, and three constitution tools for session-specific rules. It runs as an MCP child process over STDIO or as a streamable HTTP service that accepts JSON-RPC requests at /mcp. Feedback can be generated through Gemini, OpenAI, OpenRouter, or Anthropic, while a supplied sessionId lets the server summarize earlier advice for continuity. The project is now in maintenance mode at v2.9.0, so it is a better fit for adopters comfortable with a stable, self-managed feature set than for teams expecting ongoing feature development.
A primary agent sends its full user request, goal, and current plan to vibe_check; the server calls a configured second model and returns feedback intended to challenge assumptions, surface uncertainty, and interrupt reasoning lock-in. Its CPI layer introduces short reflection points when risk rises, after which the primary agent can revise or continue its plan. When sessionId is present, the service summarizes prior advice from that session, and vibe_learn can optionally record resolved mistakes, preferences, and successful corrections. update_constitution({ sessionId, rules }) merges or sets session rules, check_constitution({ sessionId }) returns the effective rules, and reset_constitution({ sessionId }) clears them. The server supports STDIO and HTTP transports; HTTP mode exposes /healthz and /mcp and applies CORS restrictions, Host validation, and a configurable JSON body limit.
- A developer using Cursor, Windsurf, or Claude Desktop wants an agent to reconsider assumptions before a large refactor, dependency migration, or irreversible code change.
- A team handling ambiguous requirements wants a second model to detect when the primary agent has misunderstood the goal or added complexity without evidence.
- Engineers running long-horizon automation want advice continuity through
sessionIdand enforceable session rules such as testing before refactoring or avoiding secret writes. - Builders of high-risk agent workflows want CPI pause points when risk increases, reducing the chance that one flawed decision cascades through later steps.
- A self-hosting team wants one MCP interface while retaining a choice among Gemini, OpenAI, OpenRouter, and Anthropic for mentor-model inference.
How do you install or deploy this agent?
Node.js 20 or newer is required. The shortest path is to run the package on demand through npx:
npx -y @pv-bhat/vibe-check-mcp start --stdioAdd the server to an MCP client configuration:
{
"mcpServers": {
"vibe-check-mcp": {
"command": "npx",
"args": ["-y", "@pv-bhat/vibe-check-mcp", "start", "--stdio"]
}
}
}Configure at least one provider credential. Gemini is the default provider:
GEMINI_API_KEY=your_gemini_api_key
OPENAI_API_KEY=your_openai_api_key
OPENROUTER_API_KEY=your_openrouter_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key
DEFAULT_LLM_PROVIDER=geminiFor source development and verification:
git clone https://github.com/PV-Bhat/vibe-check-mcp-server.git
cd vibe-check-mcp-server
npm ci
npm run build
npm testThe repository also supplies a Docker setup helper:
bash scripts/docker-setup.shHow do you use this agent?
STDIO mode is intended for MCP-aware clients such as Claude Desktop, Cursor, and Windsurf. After connecting it, instruct the primary agent to call vibe_check after planning and before major actions, including the complete user request and current plan; it may call vibe_learn after resolving a mistake.
For manual HTTP operation, start the service with:
npx -y @pv-bhat/vibe-check-mcp start --http --port 2091Confirm that it is live:
curl http://127.0.0.1:2091/healthzSend JSON-RPC requests to:
http://127.0.0.1:2091/mcpA call can override both provider and model:
{
"goal": "...",
"plan": "...",
"modelOverride": {
"provider": "anthropic",
"model": "claude-opus-5"
}
}For HTTP deployment behind Docker, a reverse proxy, or any non-loopback hostname, set MCP_ALLOWED_HOSTS to the deployed hostname or requests will receive HTTP 403. CORS_ORIGIN and MCP_MAX_BODY_SIZE control browser-origin access and the JSON body limit.
What are this agent's strengths and limitations?
- It adds an independent MCP tool and second-model review instead of relying only on the primary agent to critique itself.
- Both STDIO and streamable HTTP transports are documented, covering desktop MCP clients, local subprocesses, and self-hosted services.
- Gemini, OpenAI, OpenRouter, and Anthropic are supported, with per-call selection through
modelOverride. - The constitution APIs provide explicit per-session rule management, while
sessionIdenables continuity across earlier advice. - HTTP mode defaults to loopback CORS and Host restrictions and enforces an explicit JSON request-size limit.
- The repository is in maintenance mode and no longer receives active feature development; structured output, broader retries, and input sanitization remain roadmap items.
- Each model-backed review introduces another network call, provider cost, and latency into the primary agent's workflow.
- Deployment requires Node.js 20 or newer and an API key for at least one supported provider.
- The primary agent must be prompted to call
vibe_checkat appropriate moments, so coverage depends on workflow integration and tool-use compliance. - The v2.9.0 Host validation can break existing Docker, proxy, or remote HTTP deployments until
MCP_ALLOWED_HOSTSis configured.
How does this agent compare with similar options?
Compared with asking the primary agent to reflect on its own work, Vibe Check MCP obtains external metacognitive feedback from a second model. Compared with a single-provider integration, it offers Gemini, OpenAI, OpenRouter, and Anthropic behind one MCP service. STDIO is the direct fit for clients such as Claude Desktop, Cursor, and Windsurf, while HTTP provides a fixed service endpoint at the cost of additional Host, CORS, and port configuration.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Vibe Check MCP This agent | 81 · Good | MCP serverFree + model costs | ★ 504 | 2mo ago | TypeScript | Claude.ai · OpenAI API · Claude API |
| Concierge AI | 45 · Major gaps | Library / SDK | ★ 527 | 5mo ago | Python | — |
| Kun Workspace | 49 · Major gaps | Desktop appFree + model costs | ★ 6.4k | 1d ago | TypeScript | ChatGPT · Codex · OpenAI API · Claude API |
| Vix | 43 · Major gaps | CLIFree + model costs | ★ 283 | 1mo ago | Go | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
The evidence confines the server to advice, session-rule management, and a dedicated learning log; the security policy says it neither executes commands nor reads arbitrary files. HTTP defaults restrict origins and hosts to loopback and cap request bodies. Prompt forwarding to third-party LLMs, log storage, configuration writes, and network exposure are clearly disclosed. Installer tests support atomic 0600 writes, managed-entry safeguards, backups, and rollback. Dependency auditing, CI security checks, and the Hono override are documented thoroughly, including the important limitation that the override does not propagate to consumers. Deductions apply because no per-operation confirmation is shown before external transmission, learning-log writes, or client configuration changes. Sensitive-data protection relies substantially on avoidance guidance and an optional disable setting, while input sanitization remains roadmap work. Authorship, repository, research, and license attribution are clear; unknown registry identity is not treated as suspicious.
The README, package manifest, CI, and tests are broadly consistent about Node 20, version 2.9.0, transports, and installer behavior. Tests show understandable handling of unsupported Node versions, invalid configuration shapes, and conflicts with unmanaged entries. Deductions apply because no lockfile, complete implementation, or executed results are supplied, so provider and dependency availability cannot be confirmed statically; only Gemini has a described fallback attempt. The headline claim of harmful actions being reduced by 41% is ambiguous against the later approximately 83% to 42% figures, which represent percentage points rather than a 41% relative reduction, and assertions such as fully functional lack runtime evidence here.
The intended users and scenarios are explicit, including coding, ambiguous work, high-risk actions, and long-running workflows. The material clearly bounds the five tools, absence of code execution, lack of built-in HTTP authentication, maintenance status, and unfinished input sanitization and structured output. Trigger guidance is precise: after planning, before major or irreversible actions, with a suggested 10–20% interrupt dosage. Node requirements, environment variables, model overrides, stdio and HTTP, Docker, multiple clients, and operating-system-specific paths are covered in depth, justifying full scores for these criteria.
The README has strong navigation, quick starts, configuration tables, security guidance, tool-selection help, and documentation links. Installation, runtime requirements, client differences, and removal procedures are detailed. Package, MCP, and tool naming are stable in the supplied files; version 2.9.0 is consistent, and the complete MIT text matches the metadata. Limitations are unusually explicit, including maintenance mode, missing authentication, prompt-injection risk, network exposure, and the scope of the dependency override. Deductions apply because the table of contents advertises Usage Examples and FAQ sections that are not present in the supplied README excerpt. The changelog is referenced but absent, while the release workflow only demonstrates tag-based note generation. A maintainer and issue channel are identified, but feature development has ended and the security policy's claimed package.json email is not present in the supplied manifest.
A second-model review layer, per-session rules, and optional learning history provide plausible incremental value over a single-agent workflow, supported by a stated study sample and effect claims. Setup is lightweight and the documentation recommends limiting interrupt frequency. Deductions apply because each check adds another model call without quantified latency, token, or monetary cost. Output usability is the largest weakness: the roadmap states that structured output is not yet implemented, implying the central advice remains free-form and less dependable for downstream machine processing. The referenced paper and underlying evaluation data are not included for static validation.
Versioning, dependencies, security controls, CI commands, and configuration-write behavior are corroborated across the README, security policy, package manifest, workflows, and tests. Atomic writes, backups, file permissions, and conflict handling receive particularly concrete support. Deductions apply because the research paper, architecture documents, changelog, audit output, lockfile, and complete implementation are not supplied, leaving effectiveness, model compatibility, clean-audit, and runtime-safety claims only partly traceable. The roadmap separates future work reasonably well, but marketing phrases such as enterprise-ready, fully functional, and trusted are not consistently distinguished from independently demonstrated facts.
- The server forwards the full user request and relevant context to a configured third-party LLM. Do not submit credentials, personal data, proprietary code, or other sensitive material unless that provider and its data policy are approved.
- HTTP mode has no built-in authentication. If it is not strictly loopback-only, place it behind an authenticating proxy, configure MCP_ALLOWED_HOSTS and CORS_ORIGIN explicitly, and avoid wildcard exposure to untrusted networks.
- vibe_learn writes to ~/.vibe-check/vibe-log.json. Confirm the disable mechanism, retention period, file permissions, and deletion procedure before deployment.
- The repository-level @hono/node-server override does not propagate when the npm package is consumed as a dependency. Consumers should pin the fixed version themselves and audit the resolved dependency tree.
- Core feedback is not yet structured and input sanitization remains roadmap work. Do not treat its advice as automatic authorization for irreversible actions; enforce validation and approval in the calling agent.
- The project is in maintenance mode and only the latest release receives security fixes. Plan for dependency updates, provider model-name changes, and a possible community-maintained successor.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
What's Changed * Fix CLI entrypoint detection via symlinks by @PV-Bhat in https://github.com/PV-Bhat/vibe-check-mcp-server/pull/77 * Bump version from 2.7.5 to 2.7.6 by @PV-Bhat in https://github.com/PV-Bhat/vibe-check-mcp-server/pull/78 * Stop integration tests from requiring a real Gemini key by @PV-Bhat in https://github.com/PV-Bhat/vibe-check-mcp-server/pull/79 Full Changelog: https://github.com/PV-Bhat/vibe-check-mcp-server/compare/v2.7.5...v2.7.6View on GitHub ↗ -
Release notes excerpt
What's Changed * Bump version to 2.7.4 and update changelog by @PV-Bhat in https://github.com/PV-Bhat/vibe-check-mcp-server/pull/69 * Fix: Correct ensureEnv missing keys handling and invalid key prompting by @croakingtoad in https://github.com/PV-Bhat/vibe-check-mcp-server/pull/57 * Improve JSON-RPC compat shim and HTTP fallback by @PV-Bhat in https://github.com/PV-Bhat/vibe-check-mcp-server/pull/64 * Add Anthropic provider integration by @PV-Bhat in https://github.com/PV-Bhat/vibe-check-mcp-server/pull/65 …View on GitHub ↗ -
Release notes excerpt
What's Changed * Refresh README metrics, recognition, and community roadmap by @PV-Bhat in https://github.com/PV-Bhat/vibe-check-mcp-server/pull/48 * feat: enforce Anthropic key prompts and document smithery CLI by @PV-Bhat in https://github.com/PV-Bhat/vibe-check-mcp-server/pull/51 * Add integration coverage for HTTP server and storage utilities by @PV-Bhat in https://github.com/PV-Bhat/vibe-check-mcp-server/pull/52 * Fix CLI root command option handling by @PV-Bhat in https://github.com/PV-Bhat/vibe-check-mcp-server/pull/53 …View on GitHub ↗
FAQ
Does using it add model costs?
vibe_check asks a configured second model to generate feedback, consuming the relevant Gemini, OpenAI, OpenRouter, or Anthropic account quota. The supplied material does not state specific prices.Is Gemini mandatory?
modelOverride.What happens when a model request fails?
gemini-3.5-flash-lite, after which the service falls back to static questions. General retry and exponential-backoff handling remains on the roadmap.Can it run on a remote server?
localhost, 127.0.0.1, and ::1. Remote, containerized, or reverse-proxied deployments must set MCP_ALLOWED_HOSTS and may also need CORS_ORIGIN.Does it automatically block every harmful action?
vibe_check before significant actions. Protection therefore depends on how the workflow and prompting policy are integrated.