Docs/Local MCP

Local MCP

VibeBasket exposes a local stdio MCP server through the CLI so AI IDEs can discover catalog items, understand target capabilities, plan installs, and apply bundles without leaving the conversation.

Start command

npx vibebasket mcp serve

Run the MCP server locally with npx vibebasket mcp serve. The client should connect over stdio, not HTTP.

What it does today

This is a strong phase-1 MCP surface: catalog search, item lookup, target guidance, install planning, install apply, backup listing, rollback, and local stack save/load all run through the real CLI service layer.

Key tools

session.get_state — discover current API base URL, write policy, and local/cloud stack availability
targets.list / targets.get_setup_guide / targets.get_mcp_snippet — inspect target capabilities, setup guidance, and native MCP config fragments for each IDE
catalog.search / catalog.get_item — search and inspect trusted catalog entries
install.plan / install.apply — dry-run first, then apply through the real adapter pipeline
install.list_backups / install.rollback — inspect and restore local backups

Safety model

Low-risk tools run directly. Medium- and high-risk tools are policy-gated. Runtime secrets stay local, and the MCP surface does not pretend cloud stack save is linked when it is not.

Current limitations

Cloud/profile-backed stack save is still handled on the website, not inside local MCP.
The MCP server is stdio-only in this phase.
Target guidance is intentionally conservative and follows the current adapter-backed install model.

Native config snippets

Ask the local MCP for target-native fragments with targets.get_mcp_snippet. These examples show the exact merge shape for a few representative clients.

Cursor / JSON

mcpServers

{
  "mcpServers": {
    "vibebasket": {
      "command": "npx",
      "args": [
        "-y",
        "vibebasket",
        "mcp",
        "serve"
      ],
      "env": {
        "VIBEBASKET_API_URL": "https://vibebasket.dev",
        "VIBEBASKET_MCP_WRITE_POLICY": "confirm"
      }
    }
  }
}

Each snippet is a merge fragment, not a complete config file. Preserve the rest of the user's config.

Open the CLI reference if you want the full command surface, or jump back to the catalog to build a bundle first.

Open CLI reference Open catalog