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.

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

Request ids and error tracking

Every tool call has one x-scry-request-id (feature observability-request-id; contract in scry-management/features/observability-request-id/briefs/_request-id-contract.md).

• Minted per tool call as a ULID (26 chars, Crockford base32, time-sortable). An inbound x-scry-request-id is always ignored: the MCP server faces end users and API clients, so under the contract's trust rule it never accepts a caller-chosen id. Code: src/lib/request-id.ts, src/lib/tool-request.ts.
• Langfuse sampling uses a server-side random draw per call (serverDraw in src/telemetry/producer.ts), never the id.
• Forwarded on every Scry hop: search (/api/search, /api/image/presign, /api/image/upload), the dashboard issue API, and the diff-service credits ledger. It is not sent to Google.
• Tool errors carry it: every JSON error body gets "request_id": "<id>" (added by the tool wrapper, so no tool has to remember), e.g. {"error":"SEARCH_API_500","message":"…","retryable":true,"request_id":"01M3…"}. A handler that throws becomes INTERNAL_ERROR / UPSTREAM_TIMEOUT with the id.
• One request line per call, written at the end, keys from a fixed allow-list: {"msg":"request","request_id":"01M…","route":"search_components","outcome":"ok","ms":412,"project_id":"4vR5…"} (code is added when outcome is error). No uid, email, query text or body. Find a call in Workers Logs by request_id. This replaces the old entry-only {tool, userId} line; Analytics Engine counts are unchanged.
• generate_image uses the request id as its run id: the AI Gateway run metadata, the Langfuse trace (metadata.request_id; the trace id is the ULID's 128 bits in hex, traceIdFor in src/telemetry/ids.ts). The request id is for tracing only and is never a billing or idempotency key: the credits hold ref_id stays a server-minted UUID per call (mcp-image:<uuid>), so a reused inbound id cannot replay a hold or merge two charges.
• Sentry (src/lib/sentry-options.ts): environment = SCRY_ENV (staging | production), sendDefaultPii: false, no bodies, and a scrubber (src/lib/sentry-scrub.ts, copied from build-processing) on events and breadcrumbs. The tool Durable Object is instrumented too, so a tool that throws reaches Sentry tagged request_id and tool. Without SENTRY_DSN the SDK is a no-op. Stage DSN: wrangler secret put SENTRY_DSN --env staging (the shared Workers project, tagged service=scry-mcp).

Project Structure

scry-mcp/
├── src/
│   ├── index.ts                # Entry point — OAuthProvider wrapper
│   ├── firebase-handler.ts     # Auth handler — login UI + Firebase verification
│   ├── mcp.ts                  # MCP server — 5 tools (search, screenshot, generate_image, whoami)
│   ├── credits.ts / wallet.ts  # AI-credits hold/settle against the diff-service ledger
│   ├── llm-gateway.ts          # Cloudflare AI Gateway routing for Gemini
│   ├── telemetry/              # Langfuse spans -> TELEMETRY_QUEUE producer
│   └── utils/
│       └── firebase-verify.ts  # Firebase ID token verification (Workers-compatible)
├── test/
│   ├── firebase-verify.test.ts # Unit tests for token verification
│   ├── firebase-handler.test.ts# Integration tests for auth handler
│   ├── mcp.test.ts             # Tests for MCP tools
│   ├── e2e.test.ts             # E2E smoke tests (requires dev server)
│   └── fixtures/
│       └── tokens.ts           # Test JWT fixtures
├── vitest.config.ts
├── wrangler.jsonc
├── package.json
├── tsconfig.json
├── eslint.config.mjs
└── worker-configuration.d.ts

Prerequisites

• Node.js v22+
• A Cloudflare account
• A Firebase project with Authentication enabled
• The Scry Next.js search API running (provides /api/search and /api/image/presign)

Local Development

1. Install dependencies

npm install

2. Create local environment file

cp .dev.vars.example .dev.vars

Edit .dev.vars with your values:

FIREBASE_API_KEY=your-firebase-api-key
FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
FIREBASE_PROJECT_ID=your-project-id
SCRY_SEARCH_API_URL=http://localhost:3000
SCRY_SEARCH_API_KEY=your-search-api-key
SCRY_CALLER_ASSERTION_SECRET=same-value-as-scry-nextjs-SCRY_CALLER_ASSERTION_SECRET
COOKIE_ENCRYPTION_KEY=any-random-string-for-dev

SCRY_SEARCH_API_KEY is transport auth: it proves a request came from this worker. SCRY_CALLER_ASSERTION_SECRET signs the short-lived X-Scry-Caller JWT that tells the search API which user the worker is acting for; it is the only channel that carries the uid, and the search API verifies it with the same secret before it trusts the uid. Without the secret the search tools return SERVER_MISCONFIGURED rather than searching anonymously.

3. KV configuration

The production and staging KV namespaces already exist and are configured in wrangler.jsonc. Local development uses Wrangler's local KV emulator; no cloud namespace creation is needed.

4. Start the dev server

npm run dev

The server runs at http://localhost:8787.

5. Test with MCP Inspector

npx @modelcontextprotocol/inspector
# Enter: http://localhost:8787/mcp

Running Tests

# Unit + integration tests
npm test

# With verbose output
npx vitest run --reporter=verbose

# Watch mode
npm run test:watch

# E2E tests (requires dev server running in another terminal)
npm run dev          # terminal 1
npm run test:e2e     # terminal 2

# Full verification (typecheck + lint + tests)
npm run verify

Deployment