MCPBasket

MCPBasket is a local-first product research workspace for agents. Every research response becomes a durable search with product snapshots and verified sources. Users can compare searches and add selected products to one persistent Main Basket without purchasing anything.

The public core is provider-neutral. It does not store payment credentials, authenticate to merchants, or place orders.

Install

MCPBasket ships as an npm package and as an Agent Plugin 1.0 bundle containing both the skill and MCP configuration.

npx -y --package mcpbasket@0.2.0 mcpbasket-setup --host codex

Replace codex with vscode, cursor, claude, hermes, openclaw, or generic. The setup command:

• installs the correct skill or agent rule for the selected host;

• registers the stdio MCP server when the host exposes a supported CLI or config file;

• creates private persistent storage under ~/.mcpbasket;

• starts the local viewer automatically whenever the MCP server starts.

Restart the agent host after setup. The viewer is available at http://127.0.0.1:4377 after the host starts MCPBasket.

See installation by host for VS Code, Cursor, Codex, Claude, Hermes, OpenClaw, servers, containers, and Tailscale.

Related MCP server: BizNetAI MCP Server

Agent Workflow

1. The skill routes product research and comparison requests to MCPBasket.

2. The agent creates a saved search and records structured product candidates.

3. Direct product links and images are validated before being exposed as verified sources.

4. The user reviews searches in the local viewer.

5. Explicit selections are copied to the persistent Main Basket.

6. Approved items can be exported as neutral checkout line items for a separately installed integration.

The MCP tools never authorize or execute a purchase.

Surfaces

Configuration

MCPBASKET_STORE_PATH=/absolute/path/to/basket.json
MCPBASKET_PORT=4377
MCPBASKET_BIND_HOST=127.0.0.1
MCPBASKET_VIEWER_URL=http://127.0.0.1:4377
MCPBASKET_START_VIEWER=true

The store path must be absolute. The MCP server starts the viewer by default; set MCPBASKET_START_VIEWER=false only when running mcpbasket-viewer separately.

For private access from another device, keep the viewer bound to localhost and proxy it with Tailscale Serve. Do not expose the unauthenticated local HTTP API to the public internet.

Development

git clone https://github.com/gordo-labs/mcpbasket.git
cd mcpbasket
npm install
npm run verify
npm run viewer

The verification suite builds the MCP server, runs deterministic tests, packs the exact npm artifact, installs it into a temporary clean project, and validates the bundled skill and plugin manifests.

Documentation

• Installation by host

• Architecture

• HTTP API

• Product model

• Agent prompting

• Remote service research

• Remote service boundary

License

MIT