MCP server

The MCP server puts VibeBeacon inside the editor you already use. Ask it to scan and upload, or ask it what is currently wrong with an app, without leaving the chat.

The config

Run this once from a terminal on the same machine, no key to copy:

bash

npx vibebeacon@latest login

Then every client below takes the same shape, with no key in it at all - the server reads the credential the login step just stored. It runs through npx, so there is nothing to install first.

mcp config

{
  "mcpServers": {
    "vibebeacon": {
      "command": "npx",
      "args": ["-y", "vibebeacon-mcp"]
    }
  }
}

No terminal on this machine, or running in CI?

Set VIBEBEACON_API_KEY in the config instead. Keep it in the config file your client owns, not in a file you commit.

mcp config (with a key)

{
  "mcpServers": {
    "vibebeacon": {
      "command": "npx",
      "args": ["-y", "vibebeacon-mcp"],
      "env": {
        "VIBEBEACON_API_KEY": "vb_live_your_key_here"
      }
    }
  }
}

Where each client keeps that file

Client	Config location
Claude Code	.mcp.json in the project root, or claude mcp add
Cursor	.cursor/mcp.json in the project, or ~/.cursor/mcp.json globally
Windsurf	~/.codeium/windsurf/mcp_config.json
Claude Desktop	claude_desktop_config.json (Settings, Developer, Edit Config)

Claude Code

Either drop the config above into .mcp.json in the project root, or add it from the command line:

bash

claude mcp add vibebeacon -- npx -y vibebeacon-mcp

Check it with /mcp in the Claude Code session. The server should list seven tools.

Cursor

Create .cursor/mcp.json in the project with the config above, or put the same file in ~/.cursor/ to make the server available everywhere. Cursor shows the server under Settings, MCP. Restart Cursor after the first edit.

Windsurf

Open Settings, Cascade, MCP servers and edit the raw config, or edit ~/.codeium/windsurf/mcp_config.json directly. The block is identical. Windsurf needs a reload of the window to pick up changes.

Claude Desktop

Settings, Developer, Edit Config opens claude_desktop_config.json. Paste the same block and restart the app fully, not just the window. Claude Desktop has no project folder, so use it for reading alerts rather than scanning.

Tools the server exposes

scan_project

Reads the project at an absolute path and returns the manifest without uploading it.

upload_manifest

Sends a manifest to VibeBeacon and returns the app id, the component count and any new alerts.

list_apps

Lists your apps: name, slug, open alert count, plan and when each was last scanned.

list_alerts

Returns alerts for an app, open by default, with severity, the affected component and the version that fixes it.

explain_alert

Returns one alert with recorded fix guidance and major-version risk. A version match does not establish exploitability.

review_app

Fetches the fix plan for an app, grouped into bands, with a review prompt telling the tool to verify each claim against the lockfile before recording a verdict.

update_alert

Records a verdict on an alert: acknowledged, resolved, snoozed, or not applicable with a reason.

What to say once it is connected

Scan this project with vibebeacon and upload it.
What security alerts are open on my coffee shop app?
Explain the top alert and tell me if upgrading will break anything.
Review my coffee shop app and tell me what to fix first.
Mark that alert not applicable, we do not use that code path.

If it does not appear

Restart the client. Most of them read MCP config only at startup.
Check Node is 20 or newer. Run node --version in the same shell the editor launches from.
A missing key gives an authentication error on the first tool call, not at startup. The message names the environment variable.
On Windows some clients need npx.cmd rather than npx as the command.

Read-only score and findings

For the versioned score and findings JSON contract, use the CLI command npx vibebeacon@latest findings --name "My app" --json. It reads without uploading or changing verdicts. review_app retains review-only prompts; upload_manifest sends data and update_alert changes alert state. See scan results and agent access and handoff approval boundaries.