Skip to main content

ADR 0007: Agent commerce — public REST + MCP API at api.acesense.io

  • Status: ✅ Accepted
  • Date: 2026-04-26
  • Deciders: Akshay Sarode
  • Tags: api, billing, mcp, agents, infrastructure

Context​

In April 2026 the AceSense GPU pipeline was reachable from one place: the Flutter app, via the requestUploadPath callable. Discovery audits flagged that the marketing site advertised an MCP server card with status: "planned" but no actual MCP endpoint, no public REST API, and no agent payment surface.

Three forces pushed for opening this up:

  1. Adjacent demand. Tennis-coaching bots, training-platform integrations, and club-management software are real buyers of "give me back a per-shot analysis JSON for a video URL." None of them want to ship a Flutter app.
  2. Marginal cost is well-understood. RunPod GPU cost is ~€0.05–0.10/min depending on which GPU. Pricing at €0.75/min keeps healthy margin.
  3. Existing infra reuse. The pipeline already runs from a videos/{uid}/{sessionId}/... Storage write triggering processVideoOnUpload. An agent submission can reuse the trigger by writing to the same path with a different userId namespace. No backend rewrite needed.

The blocker was abuse risk: agent-scale submissions multiply the impact of every threat in compliance/upload-threat-model.md. Without the P0/P1 controls in place, opening this up would be reckless.

Options considered​

Option A — REST + MCP, prepaid credits, behind threat-model controls​

  • Pros: Real new revenue surface; closest fit to how agent operators actually buy compute today; leverages the existing pipeline; abuse risk capped by per-key quota + per-key balance + content-validation gates.
  • Cons: Real build (≥1 week even reusing pipeline); needs Stripe wiring; legal exposure (DPA scope, content-licensing clarity); Cloud Functions cost grows with traffic.
  • Cost: Engineering 1 week + ongoing Stripe % + Cloud Functions invocation cost.

Option B — MCP-only (no REST)​

  • Pros: Less surface area; targets the LLM-tool integration market specifically.
  • Cons: Excludes operators who don't speak MCP yet (most server-to-server integrations); can't run x402 / OpenAPI discovery cleanly without a REST surface.
  • Cost: A bit less than A.

Option C — REST-only (no MCP)​

  • Pros: Simplest spec.
  • Cons: Misses the LLM-tool ecosystem (Claude desktop, ChatGPT custom GPTs), which is exactly where agent-discoverability research is concentrated today.

Option D — Hold, ship later​

  • Pros: Buys time to land a Stripe deal, finalize DPA, etc.
  • Cons: Discovery audits already advertise a "planned" surface; sitting on it indefinitely makes the audit assertions look untrue. Threat-model controls have to ship anyway for the human path.

Decision​

We will ship Option A: REST + MCP at api.acesense.io, behind the threat-model P0/P1 controls.

  • REST base: https://api.acesense.io/v1 — /jobs, /usage, /pricing, /healthz. OpenAPI 3.1 published at /openapi.json.
  • MCP base: https://api.acesense.io/mcp — Streamable-HTTP transport, six tools (analyze_tennis_video, get_job_status, get_analysis_result, get_pricing, get_my_usage, list_my_jobs), seven acesense://*.md resources.
  • Auth: Authorization: Bearer phk_<keyId>_<secret>, SHA-256-hashed at rest, constant-time compare. Keys created via Firebase-auth-callable createApiKey({name, plan}).
  • Pricing: €0.75/min default, ceil(durationSeconds/60) * 75 cents. €10 free credit per new key.
  • Billing: Prepaid balance in Firestore (api_keys/{keyId}.balanceCents), credited manually through admin balance adjustment. Payment-rail integration deferred until volume justifies.
  • Rate limits: Per-key sliding window — default 10 req/min + 200 jobs/day.

Threat-model controls landed alongside this work (per ADR-0007 prerequisite): atomic per-user quota, magic-byte file validation, 30-min signed-URL TTL, audit log, locked Firestore rules. ffprobe runtime check is documented as deferred — needs the binary bundled in the deploy.

Consequences​

Positive​

  • New revenue surface decoupled from App Store / Google Play.
  • Same pipeline infra serves both consumer (in-app) and agent (API) traffic — no fork.
  • Threat-model P0/P1 controls protect both paths.
  • Discovery surface (api-catalog, mcp/server-card, x402, MPP, ACP, UCP) is now real, not aspirational.

Negative​

  • No self-serve top-up yet. Agent operators can use credited balances, but payment collection is manual until a real payment rail is worth shipping.
  • DPA scope grows. When an agent processes a real human's video, AceSense becomes a sub-processor. New DPA template needed.
  • CSAM / illegal-content risk increases at agent scale. Magic-byte gate is in; first-frame moderation is on the P1 list and not yet wired. Until it lands, content moderation depends on the magic-byte gate + RunPod's own filters + a human review queue.
  • One more payment vendor when wired. Adds processing fees and cross-border data-processing considerations.

Neutral​

  • Per-minute pricing is industry-standard for GPU-tied work; easy to compare against alternatives.
  • API key model mirrors how every other agent platform issues credentials; little surprise for operators.

Follow-up actions​

Done​

  • Implement apiServer REST + JSON-RPC mcpServer Cloud Functions.
  • Per-user upload quota + magic-byte + signed-URL audit + locked Firestore rules (threat-model P0/P1).
  • Update /.well-known/mcp/server-card.json from status: "planned" → status: "live".
  • Publish /.well-known/x402, /.well-known/mpp.json, ACP/UCP transactional discovery.
  • Marketing surface at /agents with full pricing + discovery table.
  • Custom domain api.acesense.io — separate hosting site acesense-prod-api with /v1/** → apiServer and /mcp → mcpServer rewrites. Repo: acesense-api-hosting/. DNS configured 2026-04-26.
  • ffprobe runtime metadata gate — @ffprobe-installer/ffprobe + fluent-ffmpeg bundled in the function image; ffprobeGate() in shared/video-validation.ts cross-checks claimed duration/width/height within ±5% tolerance, fails open when binary unavailable so partial deploys don't wedge.
  • First-frame Cloud Vision moderation — moderateFirstFrame() in shared/moderation.ts extracts a still at 5 s, ships to Cloud Vision SafeSearch, rejects on adult/violence/racy ≥ LIKELY. Audit row per decision in moderation_audit/{autoid}. Currently gated off by GOOGLE_CLOUD_VISION_ENABLED env var until Vision API billing is enabled — see pending item below.
  • Admin panel UI — /developer route in acesense-admin exposes Create / List / Revoke for API keys, with the one-shot full-key reveal.

Pending — manual external setup​

  • Payment rail. Pick the provider and ship checkout/webhook only when there is real paid demand. Until then, use adminAdjustApiKeyBalance for credited agent balances.
  • Enable Google Cloud Vision API on acesense-prod + set GOOGLE_CLOUD_VISION_ENABLED=true env var on processVideoOnUpload. The code path is wired and tested (6 unit tests); it just no-ops until the env var flips. Surface impact: the magic-byte + ffprobe gates remain in force; the Cloud Vision check is the deferred extra layer for adult/violence/racy first-frame content.

Pending — internal​

  • DPA template for agent operators — sub-processor agreement covering when an agent submits a real human's video. Owner: legal review.
  • Real machine-payment integration — discovery is published; actual settlement integration deferred until ≥1 customer requests it. Spec is still moving.

References​