How do I install Portage Store?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Portage Store need an API key?

The publisher lists these environment variables: SHOPIFY_SHOP_DOMAIN, SHOPIFY_STOREFRONT_ACCESS_TOKEN, SHOPIFY_ADMIN_ACCESS_TOKEN.

What transport does Portage Store use?

Portage Store runs locally over stdio.

When was Portage Store last checked?

Last checked 2026-11-10. Shopify catalog search and product lookup via MCP; the Portage CLI adds full agentic buying.

Portage Store MCP server

Status: pre-1.0. APIs may still change between minor versions. Latest release set: 0.22.0 (changelog).

Quickstart

Two ways in: let Claude shop for you with the buy plugin, or run the portage CLI yourself. Both use the same CLI and take about five minutes.

Install the `buy` plugin

The plugin teaches Claude Code to shop through the portage CLI, so install the CLI first.

Install the CLI (portage-cli 0.9.0 or newer):
```
brew install tomtom87/portage/portage
```
Or, on Ruby 3.2 or newer, gem install portage-cli. Homebrew bundles every adapter. With RubyGems, also install portage-ucp-webmcp 0.2.0 or newer if you want the Portage browser profile and checkout autofill.

Add the plugin. Inside Claude Code:

/plugin marketplace add tomtom87/Portage
/plugin install buy@portage

Or from a shell:

claude plugin marketplace add tomtom87/Portage
claude plugin install buy@portage

Run portage setup once, in a terminal. It asks for your shipping address, optional search keys and spending caps, one skippable step at a time. It is interactive, so run it yourself rather than through Claude.
Ask Claude. Type /buy a burton snowboard under $600, or just ask in plain words. The skill is listed as buy:buy. Claude checks your setup, shows real offers and a dry-run total, and waits for your yes before any purchase.

To update or remove it:

claude plugin marketplace update portage
claude plugin update buy@portage        # then restart Claude Code

claude plugin uninstall buy@portage
claude plugin marketplace remove portage

A listing in the Claude plugin directory is coming. Until then, this marketplace is the install route.

Other agents: Codex, Cursor, OpenCode and more

The buy skill is a plain SKILL.md file, so any agent that loads skills and can run commands on your machine can use it. Install the CLI and run portage setup first, as above. The plugin carries a second skill, shop-research: read-only, for price, stock, store and order questions with no purchase in mind, and it hands over to buy to buy. Install it next to buy the same way.

With dotagents (Codex, Cursor, OpenCode): one command installs the plugin into ~/.agents/ and generates each agent's plugin or skill files.
```
npx @sentry/dotagents add tomtom87/Portage
```
Refresh it with npx @sentry/dotagents install. Remove it with npx @sentry/dotagents remove buy. If your agents.toml only allows trusted sources, run npx @sentry/dotagents trust add tomtom87/Portage first.
As a plain skill (VS Code, or any agent without plugin support): copy the plugins/buy/skills/buy/ folder into the agent's skills directory, and plugins/buy/skills/shop-research/ next to it. With dotagents, declare them in ~/.agents/agents.toml and run npx @sentry/dotagents install to get them in ~/.agents/skills/buy and ~/.agents/skills/shop-research:
```
[[skills]]
name = "buy"
source = "tomtom87/Portage"
path = "plugins/buy/skills/buy"

[[skills]]
name = "shop-research"
source = "tomtom87/Portage"
path = "plugins/buy/skills/shop-research"
```
OpenClaw. Install the CLI first (above), then the skill from ClawHub: openclaw skills install @tomtom87/portage-buy puts it in your active OpenClaw workspace, and clawhub install @tomtom87/portage-buy puts it in ./skills under the current directory (ClawHub docs). Then run portage setup. The skill's frontmatter carries OpenClaw's metadata.openclaw block (needs the portage binary, names every env var it reads as optional, brew install spec), so OpenClaw gates the skill until portage is installed. To skip ClawHub, use the plain-skill route above: OpenClaw reads personal skills from ~/.agents/skills and managed ones from ~/.openclaw/skills (OpenClaw skills docs), so copy or symlink plugins/buy/skills/buy/ into either. shop-research is on ClawHub too, as (install it the same way), or copy or symlink . Its frontmatter has the same shape, with only the search and retailer keys it names. ClawHub republishes skills under MIT-0; this repo stays MIT.

Use Portage from any MCP client

portage mcp serves the same search, quote, approve and buy tools over MCP on stdio, for any client that runs local servers. Install the CLI (brew install tomtom87/portage/portage or gem install portage-cli, 0.14.0 or newer) and run portage setup in a terminal first. Spending policy and approval stay in Portage: the agent can search and price, but a purchase waits for your approval.

Claude Desktop. Add this to claude_desktop_config.json (Settings, Developer, Edit Config) and restart. Claude Desktop doesn't inherit your shell PATH, so give the absolute path from which portage (typically /opt/homebrew/bin/portage or /usr/local/bin/portage):
```
{
  "mcpServers": {
    "portage": { "command": "/opt/homebrew/bin/portage", "args": ["mcp"] }
  }
}
```
Claude Code. claude mcp add --scope user portage -- portage mcp (drop --scope user to keep it to the current project).
Docker. docker run -i --rm -v "$HOME/.portage:/root/.portage" ghcr.io/tomtom87/portage-mcp:0.14.0 runs the same server from the registry image. A container can't open your browser, so a hand-off prints the checkout link instead.

Use the CLI yourself

Install the CLI as in step 1 above, run portage setup, then:

portage find --query "burton snowboards" --json
portage buy "burton snowboards" --max-price 600 --dry-run --json

find works with no keys. Its default search, DuckDuckGo's keyless API, resolves brand and store names ("burton snowboards") but not open-ended queries ("waterproof hiking boots"). For those, add a Brave or Google search key: portage setup asks, and search backends has the details. buy without a store URL lists offers and, in a terminal, lets you pick one. --dry-run shows the real total and never charges.

With a store URL, buy goes straight to that store's /.well-known/ucp manifest:

portage buy https://some-ucp-store.example --query "hoodie" --dry-run --json

To buy for real, enroll a payment method (portage payment enroll <store-url>), set spending caps (portage policy set), then drop --dry-run and add --yes. buy checks out only through a store's published UCP endpoint, or a platform API you already hold credentials for (your own store). Everything else ends in a hand-off. It never scrapes. The CLI tutorial walks through all of this, including what to do when search comes back empty.

portage setup saves to ~/.portage/.env (chmod 600), and .env.example lists every variable. Only ~/.portage/.env loads automatically, never a .env in the current directory, so a cloned repo can't quietly redirect your purchases or traffic (why). Upgrading, two installs on one PATH, and the Linux keychain: installation.

How a purchase finishes

Most stores don't let a third party complete payment, so buy usually builds the cart and hands off to you:

Tier	What happens	Default
A	Opens the checkout in your own browser. You pay.	On
B	A separate Portage browser profile builds the cart, then stops at payment. You pay.	Off (opt in)
C	Hand-off only. Portage opens the page and you buy it yourself. No requests to the site, no scraping, no automation of any kind.	Every Amazon site, plus walmart.com, ebay.com, bestbuy.com and any host you add

Amazon and similar retailers restrict automated purchasing agents in their terms, so Portage never automates them. The Amazon entries are on by default and yours to edit; walmart.com, ebay.com and bestbuy.com are always hand-off only. Details: tiers and hand-off targets.

Safety

These rules hold in every tier, for the CLI and the plugin:

No raw card data. Card data never passes through Portage. Payment methods are tokens from portage payment enroll, kept in your OS keychain, and the plugin refuses anything that looks like a card number.
You approve every payment. Nothing is bought without your explicit yes. A search result is never bought on --yes alone: you name the store. The plugin shows you the offers to pick from and the exact total to approve, each with a link to the product page, and one yes covers one purchase. portage policy set --require-approval person makes only a yes you type in your own terminal count. In a browser hand-off, you click pay.
Your browser's secrets stay closed. Portage never reads your browser's password, cookie or autofill stores, and never attaches to your default browser profile.
No CAPTCHA or bot-wall bypass. Portage reports it and hands off.
Spending caps. portage policy set adds per-transaction, rolling and velocity caps and a store allowlist.

Portage is open-source software provided as-is, without warranty of any kind (MIT). How you use it on any site, and compliance with that site's terms, is your responsibility. Report security issues as described in SECURITY.md.

Commands

portage --help prints this. Flags and env vars for each command are in portage-cli/README.md, also published as the CLI reference.

usage: portage buy <url> --query "..." [--qty N] [--payment-token TOKEN]
                          [--product-id ID] [--yes] [--dry-run]
                          [--auto-open|--no-auto-open] [--notify-webhook URL]
                          [--handoff-target default|print|profile|agent:NAME]
                          [--decision-backend jev|laya] [--min-confidence N] [--json]
                          [--wait [--wait-timeout DURATION|off]]
       portage buy --offer REF [--qty N] [--yes] [--dry-run] ...
       portage buy --quote QUOTE_ID --yes [--json] ...
       portage buy --query "..." [--store URL] [--max-price N] [--limit N] ...
       portage find --query "..." [--max-price N] [--limit N] [--json]
       portage compare <url> --product-id ID [--id VALUE ...] [--results N]
                              [--max-price N] [--json]
       portage check <url> [--json]
       portage pick [--search LAST|SEARCH_ID] [--via auto|tty|agent] [--json]
                    [--choose REF | --compare REF | --view REF]
       portage approve QUOTE_ID [--via auto|tty|agent] [--relayed-yes | --view] [--json]
       portage history [list] [--purchases|--searches] [--limit N] [--json]
       portage history clear [--purchases|--searches]
       portage payment list [--json]
       portage payment enroll <url> [--label NAME] [--json]
                              [--scope-merchant HOST ...] [--scope-max-amount N] [--scope-currency CUR]
       portage payment set-default <id>
       portage payment remove <id>
       portage payment freeze <id>
       portage payment revoke <id>
       portage policy show [--json]
       portage policy set [--per-transaction-cap N --currency CUR]
                           [--rolling-cap N --rolling-window-seconds N --currency CUR]
                           [--velocity-count N --velocity-window-seconds N]
                           [--allow HOST ...] [--clear-allowlist]
                           [--require-approval person|any|off]  (lowering asks at a terminal)
       portage orders reconcile [--checkout ID] [--json]
       portage index build [--sources a,b] [--queries FILE] [--dry-run] [--export DIR] [--json]
       portage index refresh [--sources a,b] [--queries FILE] [--dry-run] [--export DIR] [--json]
       portage index show [--stores|--products [--page N] [--per-page N]] [--json]
       portage index search QUERY [--category ID] [--store HOST] [--limit N] [--json]
       portage index add <url> [--crawl] [--json]
       portage index remove <host> [--json]
       portage index sources [--json]
       portage browser import [--browser chrome|edge|brave|arc|firefox|safari] [--profile-root DIR]
                              [--history-days 90] [--include-product-pages] [--max-probes 200]
                              [--exclude HOST,HOST] [--dry-run] [--yes] [--json]
       portage browser profile init|open|status [--browser chrome|edge|brave|arc] [--port N]
                              [--url URL (open only)] [--json]
       portage doctor [--require FILE] [--adapter CLASS_NAME] [--json]
       portage configure [--require FILE] [--adapter CLASS_NAME] [--json]  (alias for doctor)
       portage setup [--json]  (interactive wizard on a TTY; --json/no TTY: today's doctor report)
       portage generate adapter NAME [--dir DIR]
       portage generate agent-profile [--out FILE] [--key-out FILE] [--rotate]
       portage --version

     proxy flags (buy/find/compare/doctor/payment enroll):
       [--proxy URL] [--proxy-mode forward|gateway] [--proxy-header "Name: value"]
       [--no-proxy HOSTS] [--proxy-route ROUTE=URL|direct] [--proxy-chain URL,URL,...]
       [--proxy-passthrough HEADER] [--proxy-ca FILE] [--no-env-proxy]

Packages and docs

Package	Version	For	What it does	Docs
`buy` plugin	0.10.5	Shoppers	Claude Code plugin that shops through `portage`, plus a read-only shop-research skill	buy skill, shop-research skill
`portage-cli`	0.15.0	Shoppers	The `portage` command	CLI reference, tutorial
`shop-via-ucp` skill	–	Agent builders	Buy through a store's UCP endpoint, with or without `portage`	skill page
`browse-via-ucp` skill	–	Agent builders	Read-only: a store's manifest, catalog and whether it supports automated buying	skill page
`portage-ucp-client`	0.7.0	Agent builders	Ruby client: connect to a store's manifest, or drive your own `Adapter`, as the shopper's agent	walkthrough, agent profile, tool gating

Merchants: an adapter gem, or your own Adapter subclass of portage-ucp, serves your catalog, cart and checkout over MCP and UCP. Each adapter gem ships an exe/ server and the PORTAGE_UCP_CONFIG hook, with a shared examples/portage_ucp.rb starting point (library usage, credentials, capability coverage). On Shopify, the native Universal Commerce Agent app covers checkout and orders with no code; Portage adds cart, catalog and a signed manifest (serving /.well-known/ucp).

Contributors and adapter authors: architecture · writing adapters · spec conformance · development · CONTRIBUTING.md.

AI agents reading the docs: the docs site publishes llms.txt and llms-full.txt.

Running behind a proxy

buy, find, compare, check, doctor and payment enroll take --proxy* flags. The same settings work as PORTAGE_PROXY* env vars or a "proxy" section in ~/.portage/config.json. Anything left unconfigured falls back to the standard HTTPS_PROXY/HTTP_PROXY/NO_PROXY variables, except payment traffic, which goes direct unless you name a proxy for it. portage doctor shows the effective proxy for each route, with credentials redacted. Recipes for corporate egress, rotating pools, API gateways, mitmproxy and nginx/Cloudflare, plus the env-var caveats, are in docs/proxy.md.

Requirements

Ruby 3.2 or newer, and the mcp gem ~> 1.8 (pulled in by portage-ucp). The Homebrew formula brings its own Ruby, so a Homebrew install needs neither.

Contributing

Bug reports and pull requests are welcome at tomtom87/Portage. The project is pre-1.0 and still tracking the spec, so open an issue before any change bigger than a bugfix. CONTRIBUTING.md has the workflow; the Code of Conduct applies.

Portage Store

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Portage Store?

Does Portage Store need an API key?

What transport does Portage Store use?

When was Portage Store last checked?

Documentation

Quickstart

Install the `buy` plugin

Other agents: Codex, Cursor, OpenCode and more

Use Portage from any MCP client

Use the CLI yourself

How a purchase finishes

Safety

Commands

Packages and docs

Running behind a proxy

Requirements

Contributing

License

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Portage Store?

Does Portage Store need an API key?

What transport does Portage Store use?

When was Portage Store last checked?

Documentation

Quickstart

Install the buy plugin

Other agents: Codex, Cursor, OpenCode and more

Use Portage from any MCP client

Use the CLI yourself

How a purchase finishes

Safety

Commands

Packages and docs

Running behind a proxy

Requirements

Contributing

License

Install the `buy` plugin