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

Every client below takes the same shape. Paste this and swap in your key. The server runs through npx, so there is nothing to install first.

mcp config

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

Where the key lives

The key is read from VIBEBEACON_API_KEY. Keep it in the config file your client owns, not in a file you commit. Most of these config files sit outside the repository for exactly this reason.

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 --env VIBEBEACON_API_KEY=vb_live_your_key_here -- npx -y vibebeacon-mcp

Check it with /mcp in the Claude Code session. The server should list four 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 in the current folder 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_alerts

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

explain_alert

Returns one alert in plain English with the upgrade command and whether the fix is a major bump.

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.

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.