Skip to main content

Stash help

AI connections

Stash exposes an MCP server so any AI assistant can read (and with your permission, modify) your inventory. Install once, query forever.

Skip to the connector reference if you need scopes, tool names, or server endpoints. Most users only need the day-to-day below.

Install in one click

Visit /connect and click the button for your AI client:

  • Claude Desktop — downloads a .mcpb file. Double-click to install. First tool call triggers an OAuth flow in your browser.
  • Claude Code — runs /plugin marketplace add stashmanagement/stash-plugin followed by /plugin install stash. First tool call shows a device code; enter it at /activate.
  • ChatGPT — deeplinks to ChatGPT’s custom connector page with the URL prefilled. Click Connect.
  • Cursor — uses a cursor:// deeplink that opens Cursor and prompts for auth.

What the AI can do

Read-only by default (you can grant write access during install). Useful prompts:

  • “What’s in my collection?”
  • “Show me my major keys sorted by value.”
  • “How much have I spent vs sold this year?”
  • “Find my Amazing Spider-Man 1963 issues.”
  • “Which publisher dominates my collection?”

With write access granted:

  • “Add Action Comics #1, CGC 9.0, acquired for $200.”
  • “Mark Spider-Man #129 as sold for $240.”
  • “Refresh prices on my X-Men keys.”
  • “Export everything I sold in April as a CSV.”

How permissions work

Each AI client gets one or more scopes:

  • inventory:read — search items, see stats, list recent activity. Granted by default.
  • inventory:write — add, update, mark-sold, refresh prices. Requires explicit approval at the OAuth consent screen.
  • actions:trigger — bulk operations (enrich, export). Same — explicit approval.

Write tools always run in dry-run mode by default in the slash commands shipped with the Claude Code plugin — the AI previews what it would change and waits for you to say yes.

Seeing who has access

Settings → AI Connections shows every active connection with the client name, scopes, connection date, and last used. Revoke any of them with one click — the next tool call from that client returns 401 and the OAuth flow re-runs.

Activity

Every tool call is logged. See the per-tool stats (call count, error rate, p50/p95 latency) at the bottom of /settings/connections, or skim the cross-system activity log for a chronological view.

Plan limits

  • Free can install the connector and see it listed in their AI client, but tool calls return an upgrade message. Capped at 10 requests/minute per token (enough to verify install).
  • Collector / Shop get full tool access at 60 requests/minute per token.

Troubleshooting

  • Tool calls return 401 — token expired or you revoked the connection. Reconnect from your AI client.
  • The AI can’t find any of your items — you may have approved the wrong workspace at consent time. Revoke from Settings → AI Connections and reconnect, picking the right workspace.
  • Hit the rate limit — pause a few seconds, the sliding window resets.

Connector reference

Everything below is the deep technical reference — endpoints, OAuth flows, full tool list. Useful for building your own client or wiring an AI assistant we don’t list at /connect.

Two OAuth flows

Stash supports both authorization code with PKCE (the standard browser-redirect flow) and device authorization grant (RFC 8628, the GitHub-CLI-style flow with a one-time code).

  • Browser clients (Claude Desktop, ChatGPT, Cursor) use the authorization-code flow — the redirect to your AI app is seamless because they have a callback URL.
  • CLI clients (Claude Code, gcloud-style terminals) use the device flow — they display a code, you visit /activate in any browser to enter it, and the CLI polls until you’ve approved. No callback URL or custom URL scheme needed.

Server endpoints

  • MCP server: https://stashmanagement.com/api/mcp
  • OAuth authorization server metadata: https://stashmanagement.com/.well-known/oauth-authorization-server
  • MCP discovery: https://stashmanagement.com/.well-known/mcp-config.json

Read tools (inventory:read)

  • get_inventory_summary — one-shot collection overview (count, P/L, top items, top publishers, recent activity). Preferred for broad “what’s in my collection?” prompts.
  • search_inventory — full-text search by title, publisher, creator.
  • get_inventory_item — fetch a single item by id.
  • list_recent_items — most recently added or updated.
  • list_keys — major / minor key issues.
  • list_top_items_by_value — sorted by going rate or unrealized gain.
  • get_collection_stats — total count, cost, value, P/L.
  • get_publisher_breakdown — counts grouped by publisher.
  • get_recent_activity — recent actions in your workspace.

Write tools (inventory:write)

  • add_inventory_item — create a new comic. Supports dry_run: true to preview without writing.
  • update_inventory_item — partial update by id. Supports dry_run.
  • mark_item_sold — convenience for recording a sale. Dry-run includes computed net gain/loss.
  • sync_price_for_item — refresh going-rate for a single item using live market data.

Action tools (actions:trigger)

  • export_inventory_csv — long-running export with filters (date range, status).
  • bulk_enrich — run automated cover + metadata enrichment across the unenriched portion of the catalog.
AI connections · Stash help | Stash