# AssistWithBuying AI Assistant Setup Guide version: 2026-07-28-ai-text-v31 Plain-text URL: https://assistwithbuying.com/ai.txt Human page: https://assistwithbuying.com/ai Signed-in agent center: https://assistwithbuying.com/agent Full agent guide: https://assistwithbuying.com/llms-full.txt If you are an AI agent reading this: - Do not try to read the user's private research by fetching website pages. - The website hides private account data from ordinary unauthenticated requests. - Use MCP after the user connects you with OAuth. - Do not ask the user for an AWB API key; static AWB API keys are not shipped yet. - If the user gives you a /share/ URL, you may read that noindex, read-only recipient page as ordinary shared source material. It contains only the dossier fields the owner selected and is not access to their workspace. Never guess or enumerate share tokens; creating, editing, replacing, and revoking links are owner website controls, not MCP tools. - For Claude, setup starts in the desktop app, a desktop browser, or claude.ai in a mobile browser. Do not tell the user to add a custom connector inside the Claude mobile app; it currently does not expose that add flow. Leave Advanced settings blank; no OAuth client ID or client secret is needed for AWB's verified Claude path. - AWB currently exposes twenty-two MCP tools, and many AI apps ask the user to approve individual tool calls. That is normal. The user can approve AWB tools as they come up, or pre-approve/trust the AWB connector if their AI app offers that setting and they are comfortable. - The MCP gateway replaces caller identity from the verified OAuth token, and every registered tool dispatches only to an internal Convex handler. Ordinary website or raw Convex clients cannot call those handlers directly. - The signed-in /agent center shows the registry-derived tool count and a redacted 30-day activity feed. "Observed activity" proves AWB received an authenticated tool call; it is not a list of active Clerk grants. The feed stores no token, tool arguments, research payload, or raw error message. - If another fetch shows only "Your AI assistant" and "Loading...", that is a stale cached copy of the old JavaScript page. Use this /ai.txt document instead. What AWB is: AssistWithBuying is a private research and memory backend for a person's own AI agent. The user captures items on the website; the assistant researches them through MCP and writes structured findings back into the user's private account. Current MCP tools: An OAuth-connected MCP client should show twenty-two AWB tools after connection: awb_add_location_contribution, awb_finalize_research, awb_find_or_create_public_location, awb_get_capture_image, awb_get_capture_images, awb_get_research_brief, awb_get_research_context, awb_search_research, awb_list_capture_queue, awb_list_public_locations, awb_list_research_sessions, awb_log_research_correction, awb_log_source_check, awb_save_research_result, awb_update_capture_queue_item, awb_upsert_interest, awb_upsert_item_claims, awb_upsert_item_profile, awb_upsert_research_questions, awb_upsert_research_session, awb_withdraw_location_contribution, and awb_write_dossier_section. If a recently added tool is missing, disconnect and reconnect the connector so the client refreshes the tool list. Research-this-item workflow: 1. List actionable captures; by default awb_list_capture_queue returns pending items plus needs_user items that may be retried. Each capture includes fileIds, uploaded photo metadata, optional typed product codes (identifiers), optional bounded recall hints (recallCandidates), optional value evidence rows (priceValues), optional ownershipStatus, optional sessionId/session metadata, selected Research Tasks (researchInterestKeys plus instructions, with buy/sell/learn category hints where present), and AWB-hosted image URLs in files[].url. A retried pending item may include userResponse, the user's authoritative answer to the prior resultNote question; use it before continuing. Legacy captures may also include priceContext as a compatibility fallback. A capture may be a new item or a research_followup for an existing interest/dossier. 2. For long tasks, optionally mark the capture processing. For normal short queue items, you can skip the claim step and complete the capture with awb_save_research_result after research is done. 3. Before starting new research, call awb_search_research when the user asks whether they have researched something similar before, or when a capture/topic sounds like it might duplicate saved work. Search returns private, workspace-scoped matches from interests, item profiles, canonical facts, dossier sections, and capture notes. 4. If the capture is a research_followup or includes context.interestId/context.dossierId, call awb_get_research_context first, then update the existing item profile and dossier rather than creating a duplicate. Check dossier.needsRefresh and section freshness.state values; prioritize user-requested refreshes and aging/stale sections using the same stable sectionKey. Treat canonicalHeader.activeClaims and itemClaims with status active as the current source of truth; dossier prose can be stale. Honor researchCorrections, especially ruled_out facts, and do not reintroduce them unless you explicitly have stronger new evidence. For follow-ups, treat the text/photos, identifiers, priceValues, ownershipStatus, and any legacy priceContext as additional follow-up context for that already researched item; treat researchInterestKeys as item-level Research Tasks to add or emphasize. Task categories like buy, sell, and learn are purpose hints only; follow the selected keys and the user's note. Typed identifier rows use kind upc_a, ean13, ean8, isbn10, isbn13, or other; preserve verified rows in itemProfile.identifiers so later scans can recall the item exactly. recallCandidates are suggestions, not proof of identity; verify before consolidating. A linked research_followup is authoritative. 5. For photos, call awb_get_capture_images with all file ids when there are several photos, or awb_get_capture_image for one photo. AWB checks ownership before retrieving storage bytes, then strips metadata, bounds dimensions, and returns inline JPEG content. Do not use web_fetch, bash, curl, or browser fetch on files[].url; those are private owner-only display URLs for the signed-in website, not the agent transport. When one uploaded user photo clearly best represents the item, pass that file id as mainImageFileId to awb_save_research_result or awb_upsert_interest; use only ids from fileIds[] / files[].id, not web/reference image URLs. 6. Always identify/classify the item as baseline work, even when identification is not selected as a Research Task. If priceValues are present on the capture or existing item profile, use those explicit UI-provided value rows before inferring value from notes; legacy priceContext is only a fallback. When you find comparable evidence, append itemProfile.priceValues rows with integer cents, optional minCents/maxCents, explicit evidenceStatus (sold/listing/observed), known shippingCents/feesCents, venue, condition, variant/dimensions, conditionKind, discoveryMethod, marketFamily, visible similarity fields (matchQuality/matchScore/matchNote), optional same-item sourceCheckIds/claimIds, evidence link, note, and asOf timestamp. Never treat an active listing as sold. AWB stamps who/when added the row; users control inclusion and AWB performs deterministic math. If the user selected a Buy task like How much should I pay, compare used prices by condition/venue and include new-price context when available. If the user selected the Sell task Price guide by place, estimate Yard Sale, Facebook Marketplace, eBay, Antique store, and New exact or New comparable expectations; include a yard_sale row even when confidence is low and say why. Store broad venue estimates in priceGuide and cited observations/estimates in priceValues. Include original retail and inflation-adjusted context only when useful and supportable. 7. Prefer awb_save_research_result after your research is complete. In one call it can create/update the interest, selected mainImageFileId thumbnail, compact item profile, canonical item claims, corrections/ruled-out facts, open questions, multiple dossier sections, source-check matrix, compact interaction entries, reference images, run stats, session membership, and mark the capture done or needs_user. Pass captureItemId for queued items, especially follow-ups, so AWB links the result to the right existing item. If the capture/context includes sessionId, pass it so the item stays grouped with that shopping session. 8. Only mark needs_user when one specific decision or fact truly blocks trustworthy research. Put one clear question in resultNote. The website stores the user's answer in userResponse and returns the item to pending. 8. In itemProfile include category/object type, maker/model, materials/marks, typed identifiers, condition, dimensions, user intent, selected item-level Research Tasks (researchInterestKeys), confidence, integer-cent value range, optional priceValues, optional priceGuide, ownershipStatus, recommendation, verdict, open questions, and short agent notes. Prefer identifier rows such as { kind: "upc_a", value: "036000291452" }; legacy string arrays remain accepted for compatibility. priceValues is the append-only value evidence ledger: each row can include kind, amountCents, optional minCents/maxCents, currency, evidenceStatus (sold|listing|observed), shippingCents, feesCents, venue, condition, variant, dimensions, conditionKind (used|new_exact|new_comparable|unknown), discoveryMethod (observed_in_person|online_discovery|reduction_price|ai_research), marketFamily, matchQuality, matchScore, matchNote, optional same-item sourceCheckIds/claimIds, citationUrl, citationLabel, sourceSummary, evidenceCount, confidence, note, and asOf. priceContext exists only for old data/tool compatibility and should not be used for new value entries. priceGuide is { currency, asOf, optional summary, estimates[] } where estimates can use keys yard_sale, facebook_marketplace, ebay, antique_store, new_exact, new_comparable, original_retail, inflation_adjusted, or other. Set ownershipStatus to owned when the user bought or owns the item; use considering for curious/evaluating, not_owned for observed/not owned, and helping_third_party when helping someone else. On later edits, omitted item profile fields stay unchanged; pass only fields you mean to update. 9. Save canonical facts as claims with awb_upsert_item_claims or the claims field on awb_save_research_result. Use stable claimKey values such as maker, model, tire_size, wheel_size, dimensions, condition, asking_price, or value_range. Include evidenceTier, confidence, and sourceRefs. User measurements/photos outrank web sources and AI inference; if a lower-evidence claim conflicts with a stronger active claim, AWB returns a conflict instead of silently overwriting. 10. Log corrected mistakes with awb_log_research_correction or the corrections field on awb_save_research_result. This is for negative knowledge: wrong model, wrong size, wrong maker, wrong price assumption, or any belief that looked plausible but was disproved. Future agents should read these before trusting old prose. 11. Track unresolved checks with awb_upsert_research_questions or the questions field on awb_save_research_result. Use this for missing dimensions, unclear marks, condition uncertainty, or source gaps, and include the cheapestResolution when obvious. 12. In sections, include a short summary for quick preview plus deeper contentMarkdown. Use structuredData on sections when you have useful machine-readable payloads; pass it as an object/array, not a JSON-encoded string. Write plain text/markdown and do not HTML-escape user-facing text. Use stable sectionKey values: standard sections can use their sectionType; follow-up or custom user requests should use keys like user_request: so multiple custom sections can coexist and be updated later. Add dependsOnClaimKeys for the canonical facts the prose relies on, so AWB can mark sections needs_review when facts change. Writing or refreshing a section updates lastUpdatedAt and clears the dossier-level refresh flag. If the user selected Make a sales listing, write a natural marketplace-ready title, asking-price guidance, and description as a custom section with sectionKey sales_listing. If the user selected Price guide by place, also write a pricing section with sectionKey venue_price_guide so the quick item-profile priceGuide panel has a readable explanation. 13. Log sources through sourceChecks on awb_save_research_result or, for incremental work, awb_log_source_check. Use checked, partial, requires_user, blocked, or failed honestly. 14. Use granular tools only when you are making incremental edits or need to keep a long task claimed as processing. Shopping/research session workflow: 1. Use awb_upsert_research_session to create or find a named session for a yard-sale run, antique trip, estate sale, or multi-day hunt. 2. Use awb_list_research_sessions when the user asks what sessions exist or what they bought during a session. 3. When processing captures or updating items that belong to a session, preserve sessionId in awb_save_research_result or awb_upsert_item_profile. 4. Set ownershipStatus to owned for items the user bought; record what they paid or observed as a priceValues row when the amount is known. This lets the website filter a session to bought/owned items while keeping all value evidence in one ledger. Public location workflow: 1. Use awb_list_public_locations to search approved public venue rows and approved anonymized notes. Results never include contributor identity, workspace ids, private item details, prices, sellers, contribution URLs, or photos. 2. Use awb_find_or_create_public_location to find an approved/pending public location by normalized name, kind, and optional city, or create a pending venue shell. Pass only non-personal venue facts. 3. Use awb_add_location_contribution only when the user explicitly opts in to sharing a public venue note. Pass confirmAnonymizedShare true. Keep noteText about the venue only; do not include private item, price, seller, listing URL, receipt, photo, contact, or workspace details. AWB caps, sanitizes, scrubs, and may hold suspicious notes pending. 4. Use awb_withdraw_location_contribution when the user wants to withdraw their own note. AWB checks ownership privately and never exposes contributor identity. MCP server URL: https://assistwithbuying.com/mcp Transport: Streamable HTTP MCP. Authentication: OAuth in the user's browser. The user signs in to AssistWithBuying and approves access. The AI assistant should not handle the user's password. AWB validates the resulting Clerk OAuth access token before listing or calling tools. Recommended normal-user path: Add the custom connector from the AI app's connector or MCP settings. Paste the MCP server URL, use browser OAuth to sign in, and do not enter an AWB API key, OAuth client ID, OAuth client secret, or password into chat. After connection, enable AssistWithBuying in the current chat and ask the assistant to research the queue or explain what AWB can help with. For Claude specifically, use the desktop app, a desktop browser, or claude.ai in a mobile browser to add the connector; the Claude mobile app can use an existing/synced connector after setup, but should not be used to add it. Leave Claude Advanced settings blank for AWB's verified path. Claude connector setup was verified on 2026-06-15. ## Claude (web or desktop) (Easiest verified) Fit: claude.ai or the Claude desktop app The simplest path. Add AWB as a custom connector once from claude.ai or the Claude desktop app, then use it wherever your Claude account syncs. Steps: 1. Open Claude in the desktop app or at claude.ai in a desktop browser. (Do not use the Claude mobile app to add the connector; it can use one after setup but does not expose the add flow.) 2. Go to Settings -> Connectors, sometimes shown as Customize -> Connectors. 3. Click Add custom connector (you may need the + button first). 4. Name it AssistWithBuying and paste the MCP server URL above. Leave Advanced settings blank; do not enter an OAuth client ID or client secret. 5. Click Add. 6. Click Connect, then sign in with your AssistWithBuying account and approve access in the browser. 7. In a Claude chat, make sure AssistWithBuying is enabled, then say: research my queue. Good to know: - Works on Claude Free, Pro, and Max. Free is limited to one custom connector, which is enough for AWB. - Verified on 2026-06-15 in Claude connectors; AWB now exposes twenty-two tools, so reconnect if Claude still shows an older tool list or is missing the expected tools. - The Claude mobile app can use the connector after it exists, but it does not currently expose the custom-connector add flow. On a phone, use claude.ai in the browser to add it. - Set it up from Claude settings, not by asking Claude in chat to connect itself. - If Claude mentions optional OAuth client credentials for AWB, skip them. The verified AWB setup uses the MCP URL only. - Claude may ask you to approve AWB tool calls one by one. If you trust the connector, you can set the AWB tool permissions to always allow/pre-approve from the connector permissions screen. - If the desktop app does not finish login, try claude.ai in a browser. ## ChatGPT (Advanced / paid / elevated risk) Fit: web only, paid plan, Developer mode Advanced and web-only. ChatGPT's custom-MCP support lives behind Developer mode on paid plans, and OpenAI itself flags it as elevated-risk. Not the path for a non-technical user. Steps: 1. Use ChatGPT on the web (not the mobile or desktop app) on a paid plan. 2. Open Settings -> Apps -> Advanced, then enable Developer mode. 3. Create an app (custom connector). 4. Paste the MCP server URL above and set Authentication to OAuth, then create it. 5. Sign in with your AssistWithBuying account and approve access in the browser. 6. In a chat, choose AssistWithBuying from the Developer mode app picker and confirm actions when prompted. Good to know: - Developer mode / custom MCP is a paid-plan, web-only feature and OpenAI labels it elevated-risk; only enable it if you understand that. - On Business, Enterprise, or Edu, an admin may need to enable or approve the connector. - Expect action/tool approval prompts until the connector is trusted or approved in that workspace. - AWB already exposes OAuth and refresh-token metadata for compliant clients. ## Claude Code (For developers) Fit: terminal / CLI Anthropic's terminal agent. Add the remote MCP server, then sign in from /mcp. Steps: 1. In a terminal, run the command below. Add --scope user if you want it available in every project. 2. Run claude, type /mcp, select assistwithbuying, and choose Authenticate. 3. Complete the browser sign-in with your AssistWithBuying account and approve access. Claude Code command: claude mcp add --transport http assistwithbuying https://assistwithbuying.com/mcp Good to know: - Do not pass an Authorization header; leaving it off is what triggers OAuth. - Authentication happens from /mcp inside Claude Code, not at add time. ## Codex (For developers) Fit: Codex app, CLI, IDE Good if you already use Codex. This is a developer-tool route, not the first path for someone new to AI agents. Steps: 1. In a terminal, run the commands below. 2. Complete the browser sign-in with your AssistWithBuying account and approve access. 3. In Codex, ask it to process your AWB queue or use the available AssistWithBuying MCP tools. Codex commands: codex mcp add assistwithbuying --url https://assistwithbuying.com/mcp codex mcp login assistwithbuying Good to know: - Codex app, CLI, and IDE extension share MCP configuration. - This path is verified for adding the remote server; login uses Codex's OAuth flow. ## Cursor (For developers) Fit: AI code editor Cursor documents remote HTTP MCP and OAuth. Use it if you are already working in Cursor. Steps: 1. Open Cursor Settings -> Tools & MCP -> New MCP Server. 2. Add the snippet below with no headers and no token. 3. Back in Tools & MCP, click Needs login next to assistwithbuying. 4. Complete the browser sign-in with your AssistWithBuying account and approve access. Cursor mcp.json: { "mcpServers": { "assistwithbuying": { "type": "http", "url": "https://assistwithbuying.com/mcp" } } } Good to know: - Just the URL; do not add static Authorization headers. - We have not live-tested Cursor's OAuth flow on this machine yet. ## VS Code (Copilot) (For developers) Fit: GitHub Copilot Agent mode, 1.101+ Copilot Agent mode supports remote MCP servers. This is a developer route, not the simple household setup. Steps: 1. Use VS Code 1.101+ signed in to GitHub Copilot. 2. Add AWB to your mcp.json (Command Palette -> MCP: Add Server -> HTTP, or edit mcp.json directly) using the snippet below. 3. When VS Code shows the Auth CodeLens above the server entry, click it to sign in. 4. Complete the browser sign-in with your AssistWithBuying account and approve access. 5. Open Copilot Chat, switch to Agent mode, and enable the tools. mcp.json: { "servers": { "assistwithbuying": { "type": "http", "url": "https://assistwithbuying.com/mcp" } } } Good to know: - Sign in via the Auth CodeLens that appears above the server entry in mcp.json. - Tools only work in Copilot Chat's Agent mode, not Ask or Edit. - On a company Copilot Business or Enterprise seat, an admin must allow MCP servers. - We have not live-tested AWB's OAuth flow inside VS Code on this machine yet. ## Other / any MCP client (Varies) Fit: Windsurf, Goose, Cline, LibreChat, custom clients Most MCP clients follow the same pattern, but OAuth support varies. Use Claude first when helping a non-technical person. Steps: 1. If the client supports remote MCP with OAuth, add a remote server with Streamable HTTP transport (not SSE), paste the MCP server URL above, then complete the browser sign-in and approve access. 2. If the client has no native OAuth, bridge it through mcp-remote using the snippet below. 3. Run the client; mcp-remote opens a browser window for the AssistWithBuying sign-in and approval the first time. mcp-remote bridge (for clients without native OAuth): { "mcpServers": { "assistwithbuying": { "command": "npx", "args": ["-y", "mcp-remote@0.1.29", "https://assistwithbuying.com/mcp"] } } } Good to know: - Clients with real remote-MCP OAuth should work with the same connector URL directly, no bridge needed. - mcp-remote is an experimental community bridge; pin a recent version (shown above) rather than letting it float. - Most clients show per-tool or per-action approval prompts. The user can approve calls as they happen, or pre-approve the AWB connector if their client supports that and they trust it. - Admin-hosted tools like LibreChat are usually configured server-side, not per user. Operational notes: - AWB never runs the AI model. - AWB never spends money or makes purchases. - AWB never asks for model API keys. - Connected MCP tools are account-scoped after OAuth. - To stop using AWB, remove the connector in the AI client. AWB never stores the client's access or refresh token and does not present a local toggle as if it revoked a Clerk grant. - Public location notes are opt-in, anonymized, and scrubbed; private research remains workspace-scoped. - Revocable dossier links are a separate explicit opt-in: long-random capability, hash-only token storage, exact included fields, optional expiry, and immediate owner revocation. Anyone holding the link can read only that selected projection. - If your environment already exposes AssistWithBuying MCP tools, use those tools instead of scraping the website.