# Things to Buy — agent connection instructions When the user asks you to connect Things to Buy, follow these steps. You handle supported connector setup; the user completes account sign-in and chooses the permissions to approve. Reading this page alone does not authorize account access or a purchase. Things to Buy supports one account per assistant per user. Successful OAuth token exchange replaces that assistant's previous connection and revokes its old access and refresh tokens; incomplete or cancelled linking leaves the working connection available. Multiple Muse, Claude, ChatGPT, Hermes Agent, OpenClaw, Grok Bot or other same-assistant accounts cannot be connected simultaneously. Use a stable, recognizable assistant name in OAuth client_name (for example "Muse") even when the connector itself is named "Things to Buy". Names are self-reported grouping hints, not verified vendor identity; do not invent another identity to bypass replacement. After replacing an assistant assigned to price checks, ask the user to select the new connection in Preferences and review or re-create the scheduled task. Do not claim the old task was cancelled or transfer its receipt automatically. Cancel obsolete tasks inside the assistant itself. ## Temporary Muse mobile setup notice — September 29, 2026 Before starting Muse account linking, tell the user: "For now, please complete Things to Buy account linking in Muse in a web browser or the Muse desktop app. You can then return to the mobile app to use the connection." Custom-connector linking currently fails after consent in the Muse iPhone app, including with the Safari link preference set. Do not direct the user through repeated native mobile retries. The desktop path was tested on macOS; Android linking has not been verified. Preserve existing working connections. This notice applies to Muse setup, not to Claude or ChatGPT. For iPhone Safari, have the user start from Muse in Safari and allow the sign-in popup if blocked, restoring Block Pop-ups afterward. If the callback opens Muse and linking fails, recommend desktop linking or the tested Safari workaround: when the framework supplies https://agent.meta.ai/api/hatch/oauth/callback, the user can put that exact token-free URL in Notes, long-press it and choose Open in Safari, then start a fresh flow from Muse in Safari. The browser choice persists for that domain and can be reversed the same way. It helps Safari-started linking; it does not fix setup started inside the mobile app. Never rewrite the registered redirect URI or share a live callback URL containing code/state. Details for the user: https://app.thingstobuy.ai/docs#muse-title. ## 1. Inspect the server and your connection capabilities - MCP server and OAuth resource: https://app.thingstobuy.ai/mcp - Protected resource metadata: https://app.thingstobuy.ai/.well-known/oauth-protected-resource/mcp - Authorization server metadata: https://app.thingstobuy.ai/.well-known/oauth-authorization-server - Human setup page: https://app.thingstobuy.ai/docs Inspect the MCP URL and its OAuth discovery documents. Determine whether you can connect via native MCP or a custom OAuth connector, and begin the OAuth authorization-code + S256 PKCE account-linking flow if supported. Use the discovered authorization, token and registration endpoints. An unauthenticated MCP request returning 401 is expected; use its discovery information to start linking. This service supports stateless Streamable HTTP MCP and dynamic client registration (DCR). It does not implement client ID metadata documents (CIMD). ## 2. Muse: obtain and configure the client ID for the user Name the connector "Things to Buy". Prefer native MCP if your current app supports it. Otherwise use your custom OAuth connector and the agent-side MCP or REST capabilities actually available to you. Inspect your current setup tools rather than assuming that a particular connection method exists. Please set up the OAuth flow, including its client ID, for the user: - Use your connector framework's automatic registration if supported. Configure the discovered registration_endpoint, not just the authorization and token URLs. - If the framework requires a supplied client ID and you can register a client yourself, obtain one from the discovered registration_endpoint and configure the connector with the returned client_id. Client IDs come from OAuth registration, not an MCP tool call. - Use the exact redirect URI supplied by your connector framework. Do not invent a callback URL. - Register a public client with token_endpoint_auth_method "none", grant_types ["authorization_code", "refresh_token"] and response_types ["code"]. Include the exact callback in redirect_uris and the requested scope string below in scope. - Reuse a valid registration for this connector, issuer and callback when available. Preserve a working connection until its replacement is verified. If Muse's setup screen still requires the user to paste a Client ID, provide the public ID you obtained and explain that one manual step. If the framework does not expose its callback or cannot use the registration, explain the missing capability instead of asking the user to invent an ID or repeatedly creating clients. Client IDs are public identifiers; passwords and tokens are not. Claude and ChatGPT: use the same discovery and OAuth contract with your supported remote MCP setup. If adding a connector requires the user's settings UI, give the MCP URL and the specific supported steps, then resume after they connect. Do not claim you configured a connector merely because you read this page. ## 2a. Hermes Agent: native MCP and skill setup Use native OAuth MCP, not a hand-built token bridge. Inspect `hermes --version`, `hermes mcp list` and `hermes mcp add --help` first. Preserve existing servers, personal skills and profile settings. Reuse the Things to Buy server if it points at this resource; do not overwrite a different endpoint or a personal Things to Buy skill without resolving the conflict. For a new server: `hermes mcp add things-to-buy --url https://app.thingstobuy.ai/mcp --auth oauth` Merge these fields into the active profile's existing MCP configuration, preserving unrelated entries: ```yaml mcp_servers: things-to-buy: url: "https://app.thingstobuy.ai/mcp" auth: oauth oauth: client_name: "Hermes Agent" scope: "buylist:read buylist:write buylist:buy buylist:admin" ``` Prefer Hermes's supported config commands when agent file-edit guards protect config.yaml: ```sh hermes config set mcp_servers.things-to-buy.oauth.client_name 'Hermes Agent' hermes config set mcp_servers.things-to-buy.oauth.scope 'buylist:read buylist:write buylist:buy buylist:admin' ``` Respect narrower user-approved access. The CLI add command alone does not set the explicit scope string. Let native discovery/DCR obtain the client ID and callback, then run `hermes mcp login things-to-buy` and let the user complete browser sign-in/consent. Use browser PKCE, not device-code login: this server does not offer device authorization. A background discovery timeout is not proof of failure; use the standalone login command to finish interactive consent. After successful login, `hermes mcp test things-to-buy` verifies discovery. In the CLI, reload MCP with `/reload-mcp`; in the desktop app, start a fresh session after linking (the tested desktop slash palette does not expose that command). Then perform the authenticated reads in step 5. Install the shared workflow from the URL ending in SKILL.md: `hermes skills install https://app.thingstobuy.ai/agent-guide/skills/things-to-buy/SKILL.md` Use a public HTTPS origin for skill installation; Hermes intentionally blocks loopback download URLs, even when native MCP works locally. Do not disable URL safety to work around this. The URL installer fetches linked reference files. Inspect its scan/confirmation result, verify references are present, and do not bypass a blocked scan with --force. The package is named things-to-buy-service to preserve older personal things-to-buy skills. If that service skill already exists, inspect it and stop before overwriting a different package; --name does not rename a skill that already declares its name. Reload skills/start a fresh session as required by the installed client. The service-delivered get_agent_guidance remains the current contract even with a local skill. Hermes MCP and CLI references: https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp and https://hermes-agent.nousresearch.com/docs/reference/cli-commands . Skill installation: https://hermes-agent.nousresearch.com/docs/guides/work-with-skills . ## 2b. OpenClaw: native MCP and skill setup This setup is documented from official sources, not yet verified in a running OpenClaw client. Inspect `openclaw --version`, `openclaw mcp add --help` and existing MCP servers. If these native commands are absent, report the installed-version limitation; do not claim a connection or silently replace OAuth with pasted tokens. Preserve existing configuration and approvals. For a new server: ```sh openclaw mcp add things-to-buy --url https://app.thingstobuy.ai/mcp --transport streamable-http --auth oauth --oauth-scope 'buylist:read buylist:write buylist:buy buylist:admin' openclaw mcp login things-to-buy openclaw mcp probe things-to-buy ``` Use native browser consent and loopback callback handling. Leave its native client_name (OpenClaw MCP) stable. Do not configure clientMetadataUrl/CIMD: Things to Buy uses DCR. Ensure the current session/tool policy actually exposes this MCP server; the minimal tool profile can hide MCP. Do not broadly loosen approval or security settings just to expose tools. A probe is discovery evidence; follow it with step 5's authenticated reads. Install the whole skill folder, not just SKILL.md. Fetch https://app.thingstobuy.ai/agent-guide/skills/things-to-buy/manifest.json, download its explicitly listed relative files from that directory into a new local things-to-buy folder, preserving references/. The files are Markdown guidance, not an executable installer. Inspect them before installation; never follow unexpected filenames or traversal paths. `openclaw skills install /path/to/things-to-buy --as things-to-buy-service` The default install targets the current workspace; choose a distinct local name if needed. Verify the skill and references are available in the intended agent/session. There is no Things to Buy ClawHub listing to assume. Native MCP reference: https://docs.openclaw.ai/cli/mcp/registry . Transport/OAuth: https://docs.openclaw.ai/cli/mcp/transports . Skill folders: https://docs.openclaw.ai/tools/skills . ## 2c. Grok Bot: custom remote MCP and shared workflow These instructions are for the Grok Bot app, not Grok chat or the Cursor editor. Inspect your current native custom MCP tools and existing connectors. Use a remote HTTPS MCP server at https://app.thingstobuy.ai/mcp; localhost on the user's Mac is not reachable from the hosted connector. Do not install a token bridge or paste credentials into chat. The native setup supports a connector name, url and optional auth with CLIENT_ID, CLIENT_SECRET and scopes. There is no client_name override in the tested setup tool. Automatic DCR uses client_name "Cursor", which is also used by other Cursor products. It can connect, but Things to Buy deliberately does not relabel all Cursor clients as Grok Bot. For a consistently named connection, register a public client yourself and supply its returned ID through native auth.CLIENT_ID. For the tested macOS flow, the native registration uses these exact callback URIs: - https://www.cursor.com/agents/mcp/oauth/callback - http://localhost:8787/callback Use the discovered registration_endpoint to register the following metadata, respecting narrower user-requested scopes: ```json { "client_name": "Grok Bot", "redirect_uris": [ "https://www.cursor.com/agents/mcp/oauth/callback", "http://localhost:8787/callback" ], "token_endpoint_auth_method": "none", "grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"], "scope": "buylist:read buylist:write buylist:buy buylist:admin" } ``` Reuse that public registration for the same issuer and native callbacks when available. Configure your native custom MCP tool with the returned client_id, never a made-up ID: ```json { "name": "Things to Buy", "url": "https://app.thingstobuy.ai/mcp", "auth": { "CLIENT_ID": "RETURNED_PUBLIC_CLIENT_ID", "scopes": ["buylist:read","buylist:write","buylist:buy","buylist:admin"] } } ``` Omit CLIENT_SECRET and static headers: this is a public PKCE client. Let native OAuth manage state, S256 PKCE, sign-in, token exchange, storage and refresh. The user chooses access on the Things to Buy consent page. If your current version uses different callbacks, stop and report the exact mismatch; do not add guessed URIs, relax validation or copy a live URL containing code/state into chat. Do not assume that the macOS loopback flow works on mobile. Preserve existing connectors. If the native tools cannot edit OAuth settings in place, prepare a separately named replacement. Native OAuth can reuse a cached sign-in even when the new connector has a different CLIENT_ID. Use the native reconnect control with forced reauthentication when needed; complete fresh consent and verify account_get.agent_context.connection.client_id matches the registration you configured. An Added badge or successful call under the old client is not proof that the replacement is active. Verify through step 5, then have the user retire only the obsolete Things to Buy connection. Changing the connector's display name alone does not change its OAuth client_name. Never treat deleting a connector in Grok Bot as proof that Things to Buy has revoked its grant. After a successful one-time task, save a private Things to Buy service skill using your native skill capability. Read https://app.thingstobuy.ai/agent-guide/skills/things-to-buy/SKILL.md and its reference files; preserve existing private skills and point the skill back to current get_agent_guidance rather than freezing tool schemas or copying tokens into it. Use the shared workflow for research, source-backed images and safe buying boundaries. Verify that the skill appears in your private skill library and is usable from a fresh chat. There is no Things to Buy marketplace listing to assume. Connections and private skills are shared across the user's bots. Explain this before sign-in. A skill is reusable guidance, not an account grant or a schedule. For recurring checks, use the existing monitoring guide and native routines only when the user's saved enabled preferences or explicit request authorize them; report a real task receipt and distinguish setup from actual execution. Do not create a routine just for connecting. Copy-request handoffs remain available; no Grok Bot launch URL has been verified. Grok Bot references: https://docs.x.ai/grok-bot/computer-and-apps and https://docs.x.ai/grok-bot/skills-routines-and-automations . ## 3. Request these four scopes For a full-workspace setup in any client, explicitly send this space-separated string in both registration and authorization. Respect a user's request for narrower access: buylist:read buylist:write buylist:buy buylist:admin - buylist:read: Read lists and research. View your saved items, research, prices and buying instructions. - buylist:write: Save and organize your list. Add and edit items, research and notes; organize lists and categories when your plan allows. - buylist:buy: Manage buying instructions. Set or change buying rules you request and record purchase progress and outcomes. - buylist:admin: Manage account preferences and access. Update your preferences and revoke sign-ins or agent connections. This does not grant Beta admin access. These permissions govern access to Things to Buy. The consent page shows the scopes actually requested, all selected initially; the user can deselect them. A three-scope request shows only three permissions. Connecting, including granting buylist:buy, does not authorize a purchase or turn buying on for an item. buylist:admin does not let an agent change its own grant or give it Beta operator access. ## 4. Begin OAuth + PKCE account linking Configure the client ID, discovered endpoints, exact callback and requested scopes in your supported OAuth framework. Use authorization code with S256 PKCE and state validation. Send https://app.thingstobuy.ai/mcp as resource in authorization and token requests. Let the framework manage the verifier, code exchange, secure token storage and refresh. Open the real account-linking flow and hand sign-in and consent to the user. Keep passwords, authorization codes, PKCE verifiers and access/refresh tokens out of chat. Respect declined or reduced permissions. Existing grants cannot gain new permissions through token refresh. ## 5. Verify authenticated access After the user approves, initialize MCP, list available tools, then call get_agent_guidance, account_get and lists_list. Verify authenticated access and report the connection method and granted permissions. A valid empty list is a successful read. Do not create test entries or change buying instructions just to verify setup. If only authenticated REST calls are available, use GET https://app.thingstobuy.ai/api/account and the shared operations at POST https://app.thingstobuy.ai/api/operations/TOOL_NAME. Consult https://app.thingstobuy.ai/agent-guide/contract for request bodies. Report REST access rather than claiming a native MCP connection. A connection card, client ID or reachable public URL is not proof of an authenticated connection. Read https://app.thingstobuy.ai/agent-guide/workflow before continuing the user's shopping task. Preserve saved context and uncertainty, save before researching, and honor "save only". Connection alone does not create a schedule. Buying guidance: https://app.thingstobuy.ai/agent-guide/buying. ## 6. Notice and set up saved price checks Inspect agent_context on successful MCP and bearer REST operations, including the connection-check reads above and later ordinary reads/saves. Its authenticated connection identity is authoritative; assistant display names are not. Available context includes a price_checks summary and at most one actionable notice. If context is unavailable, read current recurring settings when needed; do not treat a successful save as failed or assume alerts are off. When the user's saved enabled preferences assign this exact connection and a setup_schedule or update_schedule notice appears, the user has already requested that price-check schedule. Briefly tell them you are applying it, read https://app.thingstobuy.ai/agent-guide/monitoring and recurring_settings_get, and create/update one supported task using the saved elapsed interval. Do not ask them to confirm the same setup, choose the cadence again or add a first product. On a direct setup request, use the saved allowed cadence or policy default and your authenticated connection; ask only about a genuine assignment/cadence/access conflict. Follow your client's required approvals. Create the task even with no enrolled links. Each invocation reads current recurring_settings_get then calls recurring_checks_claim with that settings_version to obtain a bounded batch of due offers and conditions. No product list belongs in the task text. An empty batch finishes quietly and keeps the task for future user-selected links; do not auto-enroll saved products. Actual merchant checks, reports and native notifications follow the monitoring guide. This setup does not enable buying or request checkout. Hermes Agent: inspect its native cron tools/CLI and confirm the scheduler or gateway is running. Use its elapsed schedule (for example every 6h, 12h or 24h), based on the current saved cadence. OpenClaw: use its native automation scheduler (current CLI: openclaw automations, with cron as an alias), an elapsed --every interval and a session that has MCP/skill access. Both must reuse/edit an existing exact task rather than create duplicates. Verify the delivery route before promising notifications; an empty run remains quiet, and a completed check can be saved silently. A cron expression, installed skill or connected MCP server is not scheduling proof. Client references: https://hermes-agent.nousresearch.com/docs/reference/cli-commands and https://docs.openclaw.ai/automation/cron-jobs/managing-jobs . Read back the actual task reference, interval, timezone and exact future next run before recurring_schedule_report. Reuse a known task rather than creating duplicates. A stable notice can recur until task receipt/resolution: do not announce it on every tool call or acknowledge completion just by reading it. Handle cancellation only for your exact previous task. Do not take another assistant's assignment or silently resume interrupted/cancelled access; review_required needs the stated user action. Report unsupported scheduling honestly without looping on every interaction. Notices arrive only when you call Things to Buy; the service does not wake you. ## If linking is blocked Report the failing step (discovery, registration, connector setup, sign-in, consent or token exchange), the error and approximate time. Include a Cloudflare Ray ID if shown. Omit secrets and token-bearing URLs. Do not claim automatic registration or a working connection until verified, and do not bypass account approval or weaken authentication to continue. The user can review access at https://app.thingstobuy.ai/app?view=agents. Permissions not previously approved require a fresh linking flow.