# RefurbSitter MCP Connect your MCP client and use tools to look up configurations, manage watches, and configure alerts. ## Connect in one step Claude Code: run this command, then run `/mcp` to sign in. ```bash claude mcp add --transport http refurbsitter https://refurbsitter.com/api/mcp ``` Claude.ai and Claude Desktop: open Plugins → Add → Add custom connector, paste this URL, keep Claude’s published identity and sign in. ```text https://refurbsitter.com/api/mcp ``` ChatGPT: open Plugins → Add → Add custom MCP server, paste this URL, keep OAuth selected and sign in. If that option is missing, turn on developer mode in ChatGPT settings first. ```text https://refurbsitter.com/api/mcp ``` VS Code: [install RefurbSitter in VS Code](https://vscode.dev/redirect/mcp/install?name=refurbsitter&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Frefurbsitter.com%2Fapi%2Fmcp%22%7D), then choose Start and sign in. Cursor does not support this sign-in yet. Use an [API key in Cursor](#cursor). You approve the connection on a RefurbSitter page. No client ID or key is needed. Each connection counts against your plan’s key limit. Revoke it from [Dashboard → Agent keys](/dashboard/settings#agent-keys-title). ## Connect with an API key The server receives JSON-RPC 2.0 over Streamable HTTP at `https://refurbsitter.com/api/mcp`. To use a key, send an `Authorization: Bearer YOUR_API_KEY` header. To get a key without a browser, use `POST /api/agent/v1/signup` to request a code. Send the code to `POST /api/agent/v1/signup/verify`. See the [email-code signup flow](/docs/api#signup). Without an Authorization header, `initialize` and `tools/list` return HTTP 401 with an OAuth challenge. Keep the key in your client’s secret store or private configuration. ## Claude Code ```bash claude mcp add --transport http refurbsitter https://refurbsitter.com/api/mcp \ --header "Authorization: Bearer YOUR_API_KEY" ``` ## Cursor Add the server to `.cursor/mcp.json`. Keep the file out of version control if it contains a key. ```json { "mcpServers": { "refurbsitter": { "type": "http", "url": "https://refurbsitter.com/api/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` ## Claude Desktop Add this entry to your local `claude_desktop_config.json` and restart Claude Desktop. The `mcp-remote` bridge runs through `npx`. ```json { "mcpServers": { "refurbsitter": { "command": "npx", "args": [ "-y", "mcp-remote", "https://refurbsitter.com/api/mcp", "--header", "Authorization: Bearer YOUR_API_KEY" ] } } } ``` ## VS Code Add this to `.vscode/mcp.json`. VS Code prompts you for the key. ```json { "inputs": [ { "type": "promptString", "id": "refurbsitter-key", "description": "RefurbSitter API key", "password": true } ], "servers": { "refurbsitter": { "type": "http", "url": "https://refurbsitter.com/api/mcp", "headers": { "Authorization": "Bearer ${input:refurbsitter-key}" } } } } ``` ## Generic Streamable HTTP client Use POST with `Content-Type: application/json` and accept JSON responses. The server supports protocol versions `2025-11-25` and `2025-06-18`. It responds with JSON and does not open a GET event stream. ```bash curl -sS 'https://refurbsitter.com/api/mcp' \ -H "Authorization: Bearer $REFURBSITTER_API_KEY" \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"example","version":"1.0.0"}}}' ``` Send `notifications/initialized` without an `id` after initialization. On subsequent requests, send the negotiated version in `MCP-Protocol-Version`. Use `tools/list` for input schemas and `tools/call` with `params.name` and `params.arguments`. ## Tools | Tool | Access | Required arguments | Optional arguments | What it does | | --- | --- | --- | --- | --- | | `get_account` | Read-only | None | None | Read the account, effective plan, entitlements, and watch quota. | | `list_catalog` | Read-only | None | None | List watchable product families and configurations. | | `list_watches` | Read-only | None | None | List the account's restock watches. Spot or higher. | | `create_watch` | Write | `channels` | `config_id`, `model_family`, `chip_pattern`, `cpu_cores_min`, `gpu_cores_min`, `ram_gte`, `ram_lte`, `ssd_gte`, `screen_size`, `requires_10gb_ethernet` | Create a watch using a catalog ID or the applicable manual fields. Spot or higher. | | `delete_watch` | Write | `id` | None | Delete a watch using the ID from list_watches. Send a string or a safe integer. Invalid IDs, missing watches, and watches outside the account return watch_not_found. Spot or higher. | | `set_webhook` | Write | None | `webhook_url`, `rotate_secret` | Set or clear a webhook URL, or rotate its secret. Hunt, Fleet, and Reseller. | | `create_checkout_link` | Write | `plan` | None | Create a Stripe Checkout link for the account owner. | For `create_watch`, pass a `config_id` from `list_catalog` and a nonempty `channels` array. If you omit the ID, supply `model_family` and the applicable configuration fields. Read `allowed_channels` from `get_account`. See [plan access](/docs/api#plans) and [setting a webhook](/docs/webhooks#configure). Tool calls return a JSON string in `result.content[0].text`. Check `result.isError` before using the result. Protocol or authentication failures can return a top-level JSON-RPC `error`. The [REST API error and rate limit reference](/docs/api#errors) describes the shared operation errors and limits. ## Example prompts - “Show my RefurbSitter plan, remaining watch slots, and allowed alert channels.” - “List Mac Studio configurations with at least 64 GB of RAM.” - “Find a Mac Studio M5 Max with 48 GB RAM and 512 GB storage in the catalog and create an email watch for it.” - “Show my watches and ask me which one to delete.” - “Create a Hunt Pass checkout link and give it to me to open.” [Contact support](/contact) · [Privacy policy](/privacy) · [Terms](/terms) # Agent REST API Get an API key by email and use the v1 endpoints for account, catalog, watches, webhooks, and checkout. ## Authentication The base URL is `https://refurbsitter.com/api/agent/v1`. Send `Authorization: Bearer YOUR_API_KEY` on account, catalog, checkout, watch, and webhook requests. Send `Content-Type: application/json` on requests with a JSON body. In the examples below, set `REFURBSITTER_API_KEY` in your shell from your secret store. Create and revoke keys or connection tokens in [dashboard settings](/dashboard/settings) on paid plans. Free accounts can get a key through email-code signup and revoke it in settings when agent access is shown. Save a newly issued key immediately. Once you dismiss it, you can identify the key in settings by its prefix. Download the [OpenAPI specification](/openapi.json) for request and response schemas. ## POST /api/agent/v1/signup Start with the mailbox owner’s email and an optional `label` of up to 80 bytes after trimming. This request and the verification request work without a bearer key. ```bash curl -sS -X POST "https://refurbsitter.com/api/agent/v1/signup" \ -H 'Content-Type: application/json' \ --data '{"email":"operator@example.com","label":"Inventory agent"}' ``` The server returns `200 OK` with a `flow_id`. Save the actual value and ask the mailbox owner for the six-digit code. The code expires after 10 minutes. ```json { "flow_id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA_SW52ZW50b3J5IGFnZW50" } ``` ## POST /api/agent/v1/signup/verify Replace the example `flow_id` and `code` with the values from the previous step and the email. Send the code as a string to preserve leading zeros. ```bash curl -sS -X POST "https://refurbsitter.com/api/agent/v1/signup/verify" \ -H 'Content-Type: application/json' \ --data '{"flow_id":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA_SW52ZW50b3J5IGFnZW50","code":"012345"}' ``` The server returns `201 Created` with the key and its metadata. The response below uses synthetic values. Store the actual `key` securely. A successful verification consumes the code. ```json { "email": "operator@example.com", "key": "rs_agent_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "id": "44fa1fc8-76e3-4268-bfa5-991a0b660fa1", "key_prefix": "rs_agent_AAAAAAAA", "label": "Inventory agent", "created_at": "2026-11-20T12:00:00.000Z", "last_used_at": null, "revoked_at": null } ``` ## GET /api/agent/v1/account Returns the account email, effective plan, entitlements, watch usage and limit, allowed alert channels, alert delay in milliseconds, and whether paid access is paused or a webhook is configured. Pickup watches count toward the shared quota. ```bash curl -sS "https://refurbsitter.com/api/agent/v1/account" \ -H "Authorization: Bearer $REFURBSITTER_API_KEY" ``` ## GET /api/agent/v1/catalog Returns `specific_config_enforced` and `products`. Each product includes its family and watchable `configurations`. Use a configuration’s `config_id` when creating a watch. ```bash curl -sS "https://refurbsitter.com/api/agent/v1/catalog" \ -H "Authorization: Bearer $REFURBSITTER_API_KEY" ``` ## GET /api/agent/v1/watches Returns the account’s restock watches in one `watches` array. Use the returned `id` to delete a watch. ```bash curl -sS "https://refurbsitter.com/api/agent/v1/watches" \ -H "Authorization: Bearer $REFURBSITTER_API_KEY" ``` ## POST /api/agent/v1/watches Creates a watch and returns `201 Created` with a `watch` object. Send a catalog `config_id` and a nonempty `channels` array. RefurbSitter fills the product family, chip, core counts, RAM, and storage from the ID. Supplied values for those fields must agree with the ID. ```bash curl -sS -X POST "https://refurbsitter.com/api/agent/v1/watches" \ -H "Authorization: Bearer $REFURBSITTER_API_KEY" \ -H 'Content-Type: application/json' \ --data '{"config_id":"studio-m5-max-18-40@48/512","channels":["email"]}' ``` For manual configuration, send `model_family` and the applicable `chip_pattern`, `cpu_cores_min`, `gpu_cores_min`, `ram_gte`, `ram_lte`, `ssd_gte`, `screen_size`, or `requires_10gb_ethernet` fields. RAM and storage are in GB. When `specific_config_enforced` is true, use exact catalog fields for a Mac watch without an ID. The Ethernet filter applies to Mac mini. Choose from `email`, `web_push`, `ntfy`, and `webhook` according to `allowed_channels` from the account endpoint. Set up the destination before using the webhook channel. ## GET /api/agent/v1/watches/{id} Set `WATCH_ID` to the ID returned by the watch list. The response contains a `watch` object. Invalid IDs, missing watches, and watches outside the account return `404 watch_not_found`. ```bash curl -sS "https://refurbsitter.com/api/agent/v1/watches/$WATCH_ID" \ -H "Authorization: Bearer $REFURBSITTER_API_KEY" ``` ## DELETE /api/agent/v1/watches/{id} Set `WATCH_ID` to the ID returned by the watch list. Deleting an owned watch returns `204 No Content`. Invalid IDs, missing watches, and watches outside the account return `404 watch_not_found`. ```bash curl -sS -X DELETE "https://refurbsitter.com/api/agent/v1/watches/$WATCH_ID" \ -H "Authorization: Bearer $REFURBSITTER_API_KEY" ``` ## PUT /api/agent/v1/webhook Sets the account’s public HTTPS destination and returns `webhook_configured`. Save the `signing_secret` when returned. Send `{"webhook_url":null}` to clear the destination or `{"rotate_secret":true}` to rotate the current secret. ```bash curl -sS -X PUT "https://refurbsitter.com/api/agent/v1/webhook" \ -H "Authorization: Bearer $REFURBSITTER_API_KEY" \ -H 'Content-Type: application/json' \ --data '{"webhook_url":"https://alerts.example.com/refurbsitter"}' ``` See the [webhook guide](/docs/webhooks) for the event and verification examples. ## POST /api/agent/v1/checkout Creates a Stripe Checkout link for the signed-in key’s account and returns `{"url":"…"}`. Give the link to the account owner to open and complete payment. Read the account again to confirm the resulting plan before using paid operations. ```bash curl -sS -X POST "https://refurbsitter.com/api/agent/v1/checkout" \ -H "Authorization: Bearer $REFURBSITTER_API_KEY" \ -H 'Content-Type: application/json' \ --data '{"plan":"refurb-spot-pass-9"}' ``` | Checkout plan | Accepted plan ID | | --- | --- | | 30-Day Spot Pass | `refurb-spot-pass-19` | | 90-Day Hunt Pass | `refurb-hunt-pass-69` | | Fleet Monthly | `refurb-fleet-99` | | Fleet Annual | `refurb-fleet-annual-999` | | 30-Day Spot Pass (alias) | `refurb-spot-pass-9` | `refurb-spot-pass-19` and `refurb-spot-pass-9` select the same Spot Pass. For the Reseller tier, [contact RefurbSitter](/contact). ## Plan access Every tier can use account, catalog, and checkout through REST and MCP. The watch columns cover listing, creating, and deleting watches. REST watch access also lets you retrieve a single watch. Webhook access covers one destination per account across both transports. | Plan | API keys | Watch quota | MCP watches | REST watches | Webhook destinations | | --- | --- | --- | --- | --- | --- | | Free | 1 | 1 | No | No | 0 | | Spot | 1 | 1 | Yes | No | 0 | | Hunt | 5 | 5 | Yes | Yes | 1 | | Fleet | 5 | 20 | Yes | Yes | 1 | | Reseller | 10 | 75 | Yes | Yes | 1 | The watch quota is shared with the dashboard. Free agent keys are for account and catalog reads and checkout. ## Errors Read `error.code` for the machine-readable reason and `error.message` for details. ```json { "error": { "code": "unauthorized", "message": "A valid RefurbSitter API key is required." } } ``` `payment_required` and `plan_required` include `error.pricing_url` and `error.checkout`. `invalid_plan` includes `error.valid_plans`. | HTTP status | Codes | | --- | --- | | 400 | `invalid_body`, `invalid_label`, `invalid_signup`, `invalid_code`, `invalid_watch`, `invalid_channel`, `invalid_webhook`, `invalid_plan` | | 401 | `unauthorized` | | 402 | `payment_required`, `watch_limit` | | 403 | `forbidden`, `plan_required`, `channel_not_allowed`, `checkout_disabled` | | 404 | `watch_not_found` | | 405 | Empty response with an `Allow` header | | 408 | `body_timeout` | | 409 | `key_limit`, `webhook_not_configured`, `checkout_conflict` | | 413 | `body_too_large` or `invalid_signup` for an email address over 254 characters | | 415 | `unsupported_media_type` | | 422 | `invalid_signup` | | 429 | `rate_limited` | | 503 | `agent_api_disabled`, `unavailable` | Other checkout failures can use `checkout_failed`. Use `OPTIONS` to inspect the `Allow` header. Account, catalog, and watch-list routes also support `HEAD`. ```bash curl -sS -i -X OPTIONS 'https://refurbsitter.com/api/agent/v1/watches' curl -sS -I 'https://refurbsitter.com/api/agent/v1/watches' \ -H "Authorization: Bearer $REFURBSITTER_API_KEY" ``` ## Rate limits The REST API and MCP share IP and authenticated account budgets. For `429`, wait for `Retry-After` in seconds when it is present. If signup verification says you’ve used all guesses, request a new code. | Scope | Limit | | --- | --- | | Agent requests per IP | 120 per minute | | Authenticated agent requests per account | 60 per minute, shared by the account’s keys | | Signup starts per IP | 5 per minute | | Signup codes per email identity | 3 per hour and 10 per day | | Signup starts across the service | 50 per UTC day by default | | Verification attempts | 5 per flow during the code’s lifetime | | Watch creation per account | 20 per minute | | Agent checkout per account | 5 per hour, with a separate checkout limit of 8 per minute per IP | Request bodies are limited to 64 KiB and must arrive within 10 seconds. # Signed webhooks Receive restock alerts at an HTTPS endpoint and verify signatures with Node.js or Python. ## Set a destination Hunt, Fleet, and Reseller accounts can set one public HTTPS destination. Use [PUT /api/agent/v1/webhook](/docs/api#set-webhook) or the MCP `set_webhook` tool with `webhook_url`. 1. Save the `signing_secret` securely when you first set the URL, change it, or rotate the secret. If you save the same URL and receive no new secret, keep using the one you stored. 2. Include `webhook` in the `channels` of a watch. 3. Send `{"rotate_secret":true}` to rotate the current URL’s secret. Send `{"webhook_url":null}` to clear the destination. ## The restock event RefurbSitter sends an HTTPS POST with `Content-Type: application/json` for a matched restock. The payload below uses illustrative values. ```json { "content": "Mac Studio restock — A configuration matched your watch.\nhttps://www.apple.com/shop/refurbished/mac/mac-studio", "text": "Mac Studio restock — A configuration matched your watch.\nhttps://www.apple.com/shop/refurbished/mac/mac-studio", "title": "Mac Studio restock", "body": "A configuration matched your watch.", "url": "https://www.apple.com/shop/refurbished/mac/mac-studio", "part_number": "EXAMPLE/A", "type": "restock.alert", "schema_version": 1, "id": "evt_0123456789abcdef0123456789abcdef" } ``` `content` and `text` contain the same summary. `part_number` is present when the listing provides a part number. `id` is the event identity and also appears in `X-RefurbSitter-Event-Id`. Use the ID from the signed body for deduplication. ## Verify the signature Read `X-RefurbSitter-Timestamp` as a Unix timestamp in seconds and `X-RefurbSitter-Signature` as `v1=` followed by a lowercase hex digest. Compute HMAC-SHA256 over the UTF-8 timestamp string, one period, and the raw request body bytes. Use the signing secret as UTF-8 text, even though the returned secret looks like hex. Compare `v1=` plus the computed hex digest to the header with a constant-time comparison. The examples use a five-minute clock tolerance. Pass the original request bytes to the function and parse the JSON only after verification succeeds. ## Node.js verification Pass a `Buffer`, such as `Buffer.from(await request.arrayBuffer())`, along with the two header values and your signing secret. ```javascript import { createHmac, timingSafeEqual } from "node:crypto"; export function verifyRefurbSitter(rawBody, timestamp, signature, secret) { if (!/^[0-9]+$/.test(timestamp ?? "")) return false; if (!/^v1=[a-f0-9]{64}$/.test(signature ?? "")) return false; const now = Math.floor(Date.now() / 1000); if (Math.abs(now - Number(timestamp)) > 300) return false; const digest = createHmac("sha256", secret) .update(timestamp + ".", "utf8") .update(rawBody) .digest("hex"); return timingSafeEqual(Buffer.from("v1=" + digest), Buffer.from(signature)); } ``` ## Python verification Pass the raw body as `bytes`, the two header values as strings, and your signing secret as a string. ```python import hashlib import hmac import re import time def verify_refurbsitter(raw_body, timestamp, signature, secret): if not re.fullmatch(r"[0-9]+", timestamp or ""): return False if not re.fullmatch(r"v1=[a-f0-9]{64}", signature or ""): return False if abs(int(time.time()) - int(timestamp)) > 300: return False signed_bytes = (timestamp + ".").encode("utf-8") + raw_body digest = hmac.new(secret.encode("utf-8"), signed_bytes, hashlib.sha256) return hmac.compare_digest("v1=" + digest.hexdigest(), signature) ``` ## Delivery and retries DNS lookup and the HTTPS request share an eight-second deadline. A `2xx` response marks delivery successful. Redirects count as failures. A connection failure before TLS is established can try another resolved public address within the same deadline. On Hunt, Fleet, and Reseller, RefurbSitter sends webhooks as soon as it detects a matching restock. If delivery fails, RefurbSitter may try again if it processes the same restock event again. Webhooks have no scheduled retries. If the same event is sent again, it keeps its event ID. Each request is signed with its send timestamp. Verify the signature first, then record the signed `id` with your event processing. Return `2xx` for an event you already processed.