Commonlands MCP

Public MCP server for Commonlands precision optics. Use it to choose M12/C-mount lenses, calculate field of view, verify live Shopify product truth, and hand buyers to Shopify-owned carts safely.

Connect

• MCP endpoint: https://mcp.commonlands.com/mcp
• UCP discovery: https://mcp.commonlands.com/.well-known/ucp
• Health check: https://mcp.commonlands.com/healthz
• Client setup details: docs/client-connections.md
• Agent instruction guide: docs/agent-instructions.md
• Full live guide: docs/live-usage-and-integrations.md

Copy-paste agent instruction

Use Commonlands MCP at https://mcp.commonlands.com/mcp for lens selection. Start with tools/list. Catalog EFL, image circle, max FoV/FOV@image-circle, and distortion display fields are insufficient to compute FoV on a specific sensor; do not interpolate or estimate sensor FoV from those fields. Use calculate_field_of_view for one lens/sensor pair, match_lens_to_sensor for sensor/target-FoV selection, search_lens_catalog for broad catalog discovery, and get_lens_distortion_profile for distortion status. Preserve the returned method, distortion_model, coverage_ok, image_circle_mm, sensor_diagonal_mm, and rectilinear_comparison. Call read_shopify_products before stating live price, availability, Product/Variant GIDs, URL, SKU, media, metafields, inventory, or cart payload. Only call create_cart/update_cart after the buyer confirms exact live Variant GIDs and quantities. Checkout tools are not live unless they appear in tools/list. Never ask for card data or perform Shopify catalog/inventory/order/customer writes.

Agent workflow

1. Call tools/list and trust the live list over docs.
2. For sensor-specific lens finding, call match_lens_to_sensor first, then call calculate_field_of_view for final candidate lens/sensor FoV claims.
3. Use search_lens_catalog only for broad SKU/title/mount/lens-type discovery. It does not replace per-sensor FoV calculation.
4. Get per-object grounding with resources/read for commonlands://sensors/{part} or commonlands://lenses/{sku} when needed.
5. Use get_lens_distortion_profile for distortion/model/status questions. Do not invent polynomial coefficients or claim measured correction when the response says source-display-only.
6. Use prompts/list / prompts/get with select_lens_for_sensor_fov_working_distance when a client surfaces MCP prompts.
7. Verify purchasable truth with read_shopify_products before quoting final SKU, URL, price, availability, Shopify IDs, or cart payloads.
8. Create/update a Shopify cart only after explicit buyer confirmation of line items and quantities.
9. Send the buyer to Shopify's returned cart/checkout URL. Do not claim Checkout MCP is live until checkout tools appear in tools/list.

FoV rule

Catalog EFL, image circle, max FoV/FOV@image-circle, and distortion display fields are insufficient to compute field of view on a specific sensor. Agents must not interpolate interior-sensor FoV or substitute their own calculations. Use calculate_field_of_view, then preserve returned hfov_deg, vfov_deg, dfov_deg, method, distortion_model, coverage_ok, image_circle_mm, sensor_diagonal_mm, rectilinear_comparison, and provenance/source metadata in the answer.

Truth hierarchy

1. read_shopify_products = live Shopify product truth.
2. calculate_field_of_view / match_lens_to_sensor = live FoV backend (AWS Lambda + DynamoDB lens catalog) when configured. Sensor inputs resolve through the live DynamoDB sensor catalog with fixture fallback. These are the routed public optics tools.
3. Compatibility aliases (compute_fov, compute_fov_catalog, match_lenses_to_sensor) still dispatch where practical, but new clients should route through the intent-named tools above.
4. Ranking tools (match_lens_to_sensor, recommend_lenses_for_application, compare_lenses) rank against live FoV-backend specs and field of view when the live backend is enabled, so they use real per-SKU specs (EFL, mount, image circle, FoV). They still exclude live Shopify stock/price/variant IDs; use read_shopify_products for purchasable truth. If the live backend is unconfigured they fall back to fixture scaffold.
5. The remaining fixture catalog/product-page tools = useful engineering context, not final commerce truth. If the live backend is ever unconfigured, FoV tools fail closed and sensor lookups fall back to a small reference fixture.

If fixture data conflicts with read_shopify_products or the live FoV/sensor backends, use the live truth.

Data sources

• Sensors (commonlands://sensors/{part} and the sensor used by calculate_field_of_view / match_lens_to_sensor): read from the Commonlands DynamoDB sensor table by part number when configured, with fixture fallback. Pixel pitch and pixel counts come straight from that table; active-area mm is derived as pixels x pitch.
• Lenses (commonlands://lenses/{sku}, calculate_field_of_view, match_lens_to_sensor, search_lens_catalog): the FoV Lambda reads lens optical parameters from its DynamoDB lens table when configured. Catalog-wide matching covers the full lens table when backend scanning is enabled.
• Distortion coefficients are computed server-side inside the Lambda and are never returned to clients. If the live backend only returns a display distortion string, MCP returns an honest distortion_model / distortion_status and does not claim measured polynomial correction.

Current live surface

The production surface currently exposes 20 tools across catalog/search, FoV, Shopify read-only, cart, UCP catalog, and purchase-handoff. Checkout tools, cancel_cart, and read_shopify_metaobjects are not exposed. Always trust the live tools/list over any doc.

Key tools:

• Public optics routing: calculate_field_of_view, match_lens_to_sensor, search_lens_catalog, get_lens_distortion_profile.
• Catalog/context (in tools/list): search_catalog, lookup_catalog, get_product, get_product_page_details, compare_lenses, recommend_lenses_for_application.
• Legacy hidden aliases (still dispatch for old clients, not listed in tools/list): compute_fov, compute_fov_catalog, match_lenses_to_sensor, search_lenses, get_lens_details.
• Resources/prompts: commonlands://sensors/{part}, commonlands://lenses/{sku}, commonlands://catalog/sensors, commonlands://catalog/lenses, and prompt select_lens_for_sensor_fov_working_distance.
• Live Shopify read-only truth: read_shopify_products, get_shopify_readonly_config_status.
• Buyer-confirmed Shopify cart handoff: create_cart, get_cart, update_cart when visible in tools/list.
• RFQ / question handoff: submit_rfq forwards a buyer quote request or question to the fixed Commonlands engineering inbox (SendGrid). The agent cannot choose the recipient; it sends an inquiry only (no order, payment, or Shopify write) and stays inert (routes to the contact page) until SENDGRID_API_KEY + RFQ_TO_EMAIL + RFQ_FROM_EMAIL are configured.
• Diagnostics/readiness: get_catalog_snapshot_status, get_shopify_ucp_readiness, prepare_shopify_purchase_handoff, get_purchase_route_options.

Public-data scope (Shopify reads)

The endpoint is public and unauthenticated, so read_shopify_products returns only data that is already public on commonlands.com (enforced server-side in src/shopify-read-adapter.ts, see PUBLIC_DATA_POLICY):

• Active products only. DRAFT and ARCHIVED products are filtered out and the internal status field is never returned.
• No exact inventory. Variants carry a coarse availability signal (in_stock / low_stock / out_of_stock / untracked); raw counts and inventory item IDs are never returned.
• Metafields are opt-in and allowlisted. includeMetafields defaults to false; when enabled, only the custom.* display fields rendered on public product pages are returned. App/private namespaces and non-allowlisted keys (including custom.docsend_page) are always dropped.
• read_shopify_metaobjects was removed from the public surface (2026-07): Admin metaobject definitions can hold non-public store content. Calls return an actionable error pointing to read_shopify_products.
• The requested Admin scopes were narrowed to the read scopes the surface actually needs (no metaobject, marketing, payment-terms, or shipping scopes).

Abuse controls (cart and endpoint)

Cart tools are deliberately reachable without authentication — the same trust model as Shopify's own public Storefront cart — but they are bounded:

• Per-IP rate limits (Workers Rate Limiting API, wrangler.toml): 120 requests/min per IP across /mcp, and 10 cart mutations/min per IP for create_cart/update_cart. Exceeding either returns HTTP 429 with retry-after: 60.
• Strict payloads: 1–25 line items per cart, quantity 1–999 per line, and item IDs must be live Shopify ProductVariant GIDs — fixture IDs, SKUs, and numeric IDs are rejected before any Shopify call.
• Carts are Shopify-owned and expire. The Worker is a stateless proxy; cart state, TTL, and expiry (expiryAuthority: shopify_cart_ttl_expires_at) belong to Shopify, which prunes abandoned carts automatically. No cart, session, customer, or payment state is ever stored in the Worker.
• No checkout surface: checkout/cancel tools are hidden; the server cannot take payment, create orders or customers, apply discounts, or write inventory, so an abusive caller cannot mutate anything durable.

Safety boundaries