Scry

Scry MCP Server

A spec-compliant remote MCP server on Cloudflare Workers that exposes multi-modal vector search over the Scry component database. Authenticates users via Firebase and issues its own OAuth tokens to MCP clients.

Compatible with Claude Desktop, ChatGPT, Cursor, and any MCP client via mcp-remote.

Architecture

Claude Desktop / ChatGPT / Any MCP Client

│ │ (stdio via mcp-remote) ▼ mcp-remote (local proxy) │ │ (Streamable HTTP + OAuth 2.1) ▼ Cloudflare Worker ──────────────► Firebase Auth (upstream IdP) ├─ OAuthProvider (token mgmt) ├─ FirebaseAuthHandler (login UI + token verify) └─ ScryMCP (Durable Object) │ ▼ Scry Search API (Next.js) ├─ POST /api/search — vector search (text, image, hybrid) ├─ GET /api/image/... — image proxy (CDN auth) └─ POST /api/image/presign — presigned URL generation

The Worker acts as both an OAuth server to MCP clients (issuing its own tokens) and an OAuth client to Firebase (authenticating users upstream). The MCP client never sees the Firebase token.

Tools

Issue resolution tools (stage; ISSUE_TOOLS_ENABLED="1")

Design-drift issues a human has promoted in the dashboard, resolvable in code or in Figma. All six call the dashboard's /api/agent/issues/* with a signed X-Scry-Caller (audience scry-dashboard-agent, claims sub = uid and agent_client = the MCP client's name); the dashboard checks membership and role and records actor_kind: "agent". Needs SCRY_DASHBOARD_API_URL, SCRY_AGENT_ASSERTION_SECRET (a secret shared only with the dashboard, separate from the search secret; unset = SERVER_MISCONFIGURED) and, for the protected stage dashboard, the SCRY_DASHBOARD_BYPASS_TOKEN secret. Writes are capped at 30/min/user on top of the 60 req/min limit.

Snip capture tools (stage; CAPTURE_TOOLS_ENABLED="1")

Screenshots the user took with Scry Snip, read by an agent ("fix the screenshot I just took"). Four tools, no more. They call the dashboard's /api/agent/captures/* over the same signed X-Scry-Caller hop and the same env vars as the issue tools; the dashboard decides who may read a snip (the owner, or an audience the owner turned on) and writes nothing about it to a log. Production has no flag until the feature's Gate B. delete_capture is capped at 10/min/user.

Every result starts with a text block (capture id, how old, who took it, size), then the picture (WebP, long edge at most 1280 px, about 70 KB, inlined only up to 75,000 bytes (about 100k base64 characters); both numbers live in src/captures/constants.ts as CAPTURE_AGENT_IMAGE), and a signed link to the original that expires in one hour. A picture that is over budget or cannot be fetched degrades to the link only. The Sync app produces the rendition; this server does no image processing.

latest_clipboard (feature mcp-clipboard) is registered only when SYNC_CLIPBOARD="on" as well (stage on, production "off" until the release; off or unset, the tool is not listed). It calls the dashboard's GET /api/agent/clipboard/latest, which answers 404 while the caller's sync-clipboard switch is off (CLIPBOARD_OFF, "Clipboard sharing is not on for your account.") and reads nothing else. The result is a text block (one-line summary, then the content labelled as untrusted data from the user's clipboard: text, else HTML, else RTF, cut at 60 000 characters, or 8 000 when a picture is attached, so the whole result stays under Claude Code's 25k-token tool-output cap: CLIPBOARD_TEXT in src/captures/constants.ts), then the picture (PNG, JPEG, WebP or GIF; any other type, an SVG say, is link-only; redirects are not followed) inline only up to the capture tools' budget (CAPTURE_AGENT_IMAGE.inlineMaxBytes, 75,000 bytes), else a line with its signed link (valid 5 minutes); a snip over the budget also says get_capture returns its agent picture. A snip item names its capture id for get_capture. An empty clipboard is a normal result; a dashboard 429 is RATE_LIMITED.

Errors are JSON {error, message, retryable} with isError: CAPTURE_STALE (newest is older than the window; carries its id and age), AMBIGUOUS_PROJECT (the message lists the projects), CAPTURE_NOT_READY (still uploading), CAPTURE_NOT_FOUND (a missing capture and one the caller may not see are byte-identical), CAPTURE_NOT_OWNER (delete), plus the generic RATE_LIMITED, SERVER_MISCONFIGURED, TIMEOUT, DASHBOARD_UNREACHABLE. The note a user typed is returned quoted and labelled as untrusted data. No log line carries a capture id, note, app name or URL.

Stock picture search (stage; STOCK_TOOLS_ENABLED="1")

One tool, search_stock(query, type?, provider?, limit?): a live search of free stock libraries (Pixabay, Unsplash, Openverse; Pexels when the service enables it) through the scry-stock Worker (STOCK_SERVICE_URL, secret STOCK_SERVICE_TOKEN). The call carries the service bearer, a 60-second X-Scry-Caller assertion with audience scry-stock (signed with SCRY_CALLER_ASSERTION_SECRET, the secret the stock Worker verifies) and the call's request id, and is abandoned after 3 s. Each result has provider, title, creditLine, creditParts (the credit as ordered {text, href?} parts), pageUrl, providerUrl, previewUrl, type, licenseLabel and licenseUrl, plus a status per provider. The text output prints the credit as markdown with its links (Unsplash photographer and Unsplash links carry the utm_source=scry pair), the licence as a link when the service gives a deed URL, a Sources: line, and the provider notices the terms require (Openverse: "made with Openverse, not endorsed or certified by Openverse"; Pexels: "Photos provided by Pexels"); the same notices are in structuredContent.notices. The tool description tells the agent to show the credit exactly as given, links included, and to open pictures on the provider's site. Nothing is stored, and the query is never logged: it travels only in the POST body, and the tool does not get the injected analytics context / conversation_id arguments (NO_AGENT_ARGS_TOOLS). Staging only; production sets neither variable, so the tool is absent there until the feature's Gate B. Source: src/stock/.

Errors are JSON {error, message, retryable} with fixed text per status (never the service's body): RATE_LIMITED, VALIDATION_ERROR, STOCK_TIMEOUT, STOCK_UNREACHABLE, STOCK_SERVICE_ERROR, STOCK_PROVIDERS_UNAVAILABLE, SERVER_MISCONFIGURED.

Usage analytics

Each tool handler invocation records one Workers Analytics Engine data point for use by the dashboard's staff-only KPI page. The only recorded values are the tool name (blob1), environment (blob2), and Firebase uid (blob3 and index1), plus double1 = 1 for counting. Missing environment/uid values become unknown and anonymous. No query text, prompts, image data, tokens, or other tool data is sent to Analytics Engine. Internal diagnostic logs do not add usage points. Missing or failing analytics bindings never affect tool responses.

The MCP_USAGE binding writes to scry_mcp_usage in production and scry_mcp_usage_staging in staging. Query production with the Analytics Engine SQL API (substitute the staging dataset name for staging):

SELECT blob1 AS tool, count() AS n FROM scry_mcp_usage WHERE timestamp > NOW() - INTERVAL '30' DAY GROUP BY tool

Analytics

Feature mcp-analytics. Every tool call produces ONE vendor-neutral event, mcp_tool_call.v1 (src/analytics/event.ts), built from an allow-list. The event goes to the sinks named in ANALYTICS_SINKS (comma-separated). The log sink is always on, whatever the value says (none, off and unset all mean log only), so keep it listed; an unknown name is ignored and logs one warning line.

What is collected: tool name, outcome, latency, error code, the confirmed project id, a salted hash of the user id (uid_hash, never the uid or email), MCP client name/version/protocol, the calling model when the client states it (Codex only), argument NAMES, the response SIZE, and a session id (the Durable Object id). PostHog also gets the agent's optional context sentence, scrubbed of emails, URLs and key-shaped strings and capped at 300 characters. Logs never carry it.

What is never collected: argument values, response bodies, image data, queries, raw uid, email, tokens.

Client labels (client name/version, protocol version, model) are sent only when they are a short safe token (letters