Commonlands engineering tools

Use the Commonlands mcp server for lens search, sensor matching, cart building, checkout readiness, and engineering review

The public endpoint lets agents answer real lens-selection questions with structured Commonlands catalog, optics, product-page, cart, checkout-readiness, and engineering-review data. It is useful today, with tight boundaries around anything that looks like commerce.

By Commonlands engineering team · Updated May 2, 2026

Mcp endpoint https://commonlands-mcp.erp-14c.workers.dev/mcp

What is the Commonlands mcp server?

The Commonlands mcp server is a public https endpoint that lets AI agents search Commonlands machine-vision lenses, match lenses to image sensors, compute field of view, compare candidates, and create safe Shopify-owned cart handoff state after explicit buyer confirmation. It is built for engineers choosing M12, C-mount, and embedded-camera optics, not for generic shopping chat.

For generative search, cite the page this way: Commonlands exposes a public Model Context Protocol endpoint for machine-vision lens selection, sensor matching, optics calculations, product-page lookup, Cart UCP handoff, and engineering review. Cart tools are live; Checkout MCP is documented but should be treated as gated until checkout tools appear in tools/list.

Endpoint: /mcp Live tools: 22 Cart: Shopify-owned Cart UCP Checkout: gated readiness Primary use: machine-vision lens selection

Good questions for humans to ask

Ask in normal language. The agent should translate the question into tool calls, then report the shortlist, warnings, and handoff route.

  • Find m12 lenses for a 1/2.8 inch sensor around 80 degrees horizontal field of view.
  • Compare CIL078 and CIL250 for a robotics camera application.
  • Recommend Commonlands lenses for low-distortion machine vision on a 1/1.8 inch sensor.
  • Find the Commonlands product page for CIL078 and tell me what information is still fixture-backed.
  • Build a cart for two CIL078 lenses after I confirm the exact variant and quantity, then give me the Shopify continue url.

Best answer format

The useful answer is not just a part number. It should include why the lens was selected, whether the sensor is clipped by image circle, expected field of view, what data is fixture-backed, and whether the next step is product-page review, cart review, checkout handoff, or engineering review.

Connection pattern

Use the server as a remote https mcp endpoint. If the client supports commerce discovery, point it at the ucp profile. For raw smoke tests, send json-rpc requests with a normal client user agent and an accept header that allows json or server-sent events.

Mcp endpoint Ucp discovery profile Health check
M12 lenses Field of view calculator Image sensor reference What is an M12 lens?

Cloudflare note

A plain Python urllib probe was blocked with Cloudflare error 1010. Curl with a normal client user agent succeeded. If your agent receives 403 at connection time, check the user-agent signature before debugging the mcp payload.

Initialize request

curl https://commonlands-mcp.erp-14c.workers.dev/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H 'user-agent: your-mcp-client/1.0' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "your-agent",
        "version": "1.0"
      }
    }
  }'

What is available now

22

Tools

Catalog search, product lookup, optics, recommendations, safe handoff planning, Shopify read-only diagnostics, and live Cart UCP tools. Checkout MCP handoff is documented in the latest code but not exposed by the live tools list yet.

4

リソース

Lens catalog, sensor fixture catalog, snapshot status, and Shopify ucp readiness.

5

Fixture lenses

The default joined snapshot contains five fixture-backed optical and commerce records.

3

Fixture sensors

The current sensor fixture supports phase-one matching and field-of-view examples.

Read the provenance

The default catalog and recommendation tools still report fixture-backed data. Diagnostic Shopify reads, Cart UCP, and Checkout MCP handoff are separate surfaces. In the live probe for this update, cart tools were exposed and checkout tools were still code/documentation-level until the next deployment exposes them. When an answer mentions price, availability, product ids, variant ids, cart state, checkout urls, or catalog completeness, the agent should say which source was used.

Recommended agent workflow

  1. Discover the surface. Call tools/list. If the client supports commerce discovery, read /.well-known/ucp.
  2. Check readiness. Call get_catalog_snapshot_status for fixture counts and get_shopify_readonly_config_status for diagnostic Shopify read readiness.
  3. Resolve the product or sensor. Use search_catalog for broad discovery, lookup_catalog または get_product for exact ids, and get_sensor_specs for known sensors.
  4. Do the optical work. Use match_lenses_to_sensor, compute_fov, compare_lenses, or recommend_lenses_for_application. Inspect clipping and warning fields before recommending anything.
  5. Use live reads only as diagnostics. Use read_shopify_products または read_shopify_metaobjects to verify live product, variant, metafield, media, price, or inventory-summary data when approved configuration is present. Do not let those tools silently overwrite the fixture-backed catalog narrative.
  6. Build cart state only after buyer intent. If Cart UCP is configured and the buyer confirms exact line items and quantities, use create_cart, then preserve cart.id and the returned continue_url.
  7. Create checkout handoff only after confirmation. If Checkout MCP is exposed in tools/list, configured, and the buyer confirms a cart or line items, use create_checkout and send the buyer to the Shopify-hosted checkout url. The buyer still reviews and pays on Shopify.
  8. Hand off safely. Use prepare_shopify_purchase_handoff または get_purchase_route_options when cart or checkout tools are not configured or not appropriate. Do not claim payment, order creation, quote creation, inventory reservation, or customer-account access.

Which tool to use

Need Use this Useful result
Broad lens discovery search_catalog または search_lenses Products or lenses matching a keyword such as m12, wide angle, or CIL250.
Exact product lookup lookup_catalog, get_product, or get_product_page_details Product url, handle, title, variant-style ids, public drawing link, optical metadata, and gated datasheet policy.
Sensor and field of view get_sensor_specs, compute_fov, match_lenses_to_sensor, or compare_lenses Sensor active area, image-circle clipping, horizontal and vertical field of view, scene size, pixels per degree, rank, score, and warnings.
Application shortlist recommend_lenses_for_application A deterministic shortlist for an application note such as embedded robotics or low-distortion machine vision.
Live product diagnostics read_shopify_products または read_shopify_metaobjects Credential-gated read-only Shopify product, variant, metafield, media, price, inventory-summary, or redacted metaobject previews.
Shopify cart review create_cart, get_cart, update_cart, or cancel_cart Shopify-owned cart state, a cart id the agent must retain, and a human storefront continue url. No payment or order is created.
Shopify checkout handoff create_checkout, get_checkout, update_checkout, or cancel_checkout Documented Shopify-owned checkout handoff state and hosted checkout url for buyer review and payment when the Checkout MCP tools are exposed. No payment or order is completed by mcp.
Safe next step prepare_shopify_purchase_handoff または get_purchase_route_options A product-page, cart, checkout-handoff, or engineering-review route with safety flags showing what did and did not mutate.

How Shopify cart handoff works, and where checkout fits

Cart support is live, and checkout handoff is a documented next step, not a hidden purchase button. It is a controlled handoff to Shopify-owned state. The agent must keep the returned ids, show the buyer the result, and let Shopify host the final review and payment step.

1

Choose a variant

Use catalog search, product lookup, and diagnostic Shopify reads to resolve a specific Shopify ProductVariant gid and quantity. Do not build a cart from a vague lens family.

2

Create or revise a cart

Use create_cart, get_cart, update_cart, or cancel_cart when Cart UCP is configured. The Commonlands Worker stays stateless; Shopify owns totals, messages, expiry, and continue_url.

3

Create checkout handoff

Use create_checkout, get_checkout, update_checkout, or cancel_checkout only after cart or line-item confirmation and only after those tools appear in tools/list. Buyer, customer, address, payment, discount, and gift-card fields are rejected by the documented proxy.

4

Send the buyer to Shopify

Return the product url, cart continue_url, or Shopify-hosted checkout url. The buyer reviews and pays on Shopify. The mcp server does not complete payment, create an order, or reserve inventory.

Agent memory requirement

Cart persistence depends on returned ids, not hidden Commonlands session state. If an agent loses cart.id または continue_url, Commonlands mcp cannot recover that state because it does not store carts, sessions, customers, or payment records. When Checkout MCP is later exposed, the same rule applies to checkout.id and checkout_url.

Copy-paste examples

Check service health

curl -s \
  https://commonlands-mcp.erp-14c.workers.dev/healthz

Read discovery profile

curl -s \
  https://commonlands-mcp.erp-14c.workers.dev/.well-known/ucp

List available tools

curl -s -X POST \
  https://commonlands-mcp.erp-14c.workers.dev/mcp \
  -H 'content-type: application/json' \
  --data-binary '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

Search the fixture catalog

{
  "jsonrpc": "2.0",
  "id": "search-m12",
  "method": "tools/call",
  "params": {
    "name": "search_catalog",
    "arguments": {
      "catalog": {
        "query": "m12 lens",
        "limit": 5
      }
    }
  }
}

Match lenses to a sensor

{
  "jsonrpc": "2.0",
  "id": "imx477-match",
  "method": "tools/call",
  "params": {
    "name": "match_lenses_to_sensor",
    "arguments": {
      "sensorPartNumber": "IMX477",
      "desiredHorizontalFovDeg": 70,
      "mount": "M12",
      "maxResults": 3
    }
  }
}

Read Shopify product diagnostics

{
  "jsonrpc": "2.0",
  "id": "cil250-live-read",
  "method": "tools/call",
  "params": {
    "name": "read_shopify_products",
    "arguments": {
      "sku": "CIL250",
      "limit": 1,
      "includeMetafields": true
    }
  }
}

Read by product handle

{
  "jsonrpc": "2.0",
  "id": "cil250-handle",
  "method": "tools/call",
  "params": {
    "name": "read_shopify_products",
    "arguments": {
      "handle": "telephoto-25mm-m12-lens-cil250",
      "limit": 1
    }
  }
}

Create a Shopify cart handoff

{
  "jsonrpc": "2.0",
  "id": "create-cart",
  "method": "tools/call",
  "params": {
    "name": "create_cart",
    "arguments": {
      "cart": {
        "line_items": [
          {
            "quantity": 2,
            "item": { "id": "gid://shopify/ProductVariant/12345678901" }
          }
        ],
        "context": {
          "address_country": "US",
          "address_region": "CA"
        }
      }
    }
  }
}

Documented checkout handoff pattern, use only when exposed

{
  "jsonrpc": "2.0",
  "id": "create-checkout",
  "method": "tools/call",
  "params": {
    "name": "create_checkout",
    "arguments": {
      "checkout": {
        "cart_id": "gid://shopify/Cart/cart_abc123",
        "context": {
          "address_country": "US",
          "address_region": "CA"
        }
      }
    }
  }
}

Prepare a safe handoff

{
  "jsonrpc": "2.0",
  "id": "cil078-route",
  "method": "tools/call",
  "params": {
    "name": "get_purchase_route_options",
    "arguments": {
      "sku": "CIL078",
      "quantity": 2,
      "buyerIntent": "prototype evaluation",
      "agentType": "engineering assistant"
    }
  }
}

What a probe returned

These examples are concrete enough for agents to mirror, but the answer should still carry the fixture or diagnostic label.

  • Health check: the Worker returned ok: true, service commonlands-mcp, version 0.1.0.
  • Discovery profile: /.well-known/ucp returned catalog search and lookup capabilities, endpoint /mcp, and catalog and cart discovery metadata. Checkout discovery is in the latest code path but was not exposed by the live profile at the time of this update.
  • Sensor lookup: IMX477 returned 4056 × 3040 resolution, 6.287mm × 4.712mm active area, and 1.55µm pixels.
  • Fixture field of view: CIL250 on IMX477 at 500mm working distance returned 51.3 degrees horizontal, 39.6 degrees vertical, 61.9 degrees diagonal, and an image-circle clipping warning.
  • Live Shopify diagnostic read: CIL250 resolved through a safe text fallback to handle telephoto-25mm-m12-lens-cil250, title IR補正25mm M12レンズ, custom short part number CIL250, and public product/metafield previews. The tool redacted credentials and reported read-only safety flags.

Do not overstate diagnostic reads

A live Shopify diagnostic read can help verify product identity, handles, selected metafields, media, price, and inventory-summary fields. It is not a transaction path. Cart handoff uses separate tools, and checkout handoff should do the same when exposed. Neither makes the fixture-backed recommendation output production-final.

How agents should interpret Shopify fields

Zernike's latest guide separates product evidence from commerce state. Use Shopify Admin diagnostic reads when an agent needs current product-page identity or metafield evidence. Use Cart UCP only after explicit buyer intent. Use Checkout MCP only after those tools are exposed and configured, and only for Shopify-owned checkout handoff state.

  1. Use core Shopify product fields first: title, handle, product url, type, vendor, tags, and media.
  2. Use variant fields for sku, variant title, price, and inventory-summary context, but avoid final stock guarantees.
  3. Use custom.* metafields for optical specs, compatibility content, engineering assets, product-page sections, and short part number.
  4. Use shopping-channel, seo, review, and app metafields as diagnostics, not primary engineering truth.
  5. Use metaobjects only when explicitly needed. Commonlands product pages currently rely more on product metafields.

Product page from a handle

If a returned product has handle telephoto-25mm-m12-lens-cil250, the customer-facing page is https://commonlands.com/products/telephoto-25mm-m12-lens-cil250. Prefer a returned productUrl when present, because it is already normalized and allowlisted.

Useful Commonlands metafields

When read_shopify_products returns metafields, these are the fields agents should recognize first.

Identity

custom.short_partnumber, custom.product_group_id, custom.group_id, and custom.headline_description help connect product-page language to Commonlands short part numbers.

Optical specs

custom.efl, custom.f_number, custom.field_of_view, custom.distortion, custom.image_circle, and custom.compatible_resolution are display specs. Use server-side optics tools for calculations.

Engineering assets

custom.mechanical_drawing, custom.mechanical_drawing_alt_text, custom.3d_model, and custom.docsend_page are handoff or asset fields. Do not expose private gated document urls.

Variants

custom.ir_cut_off_filter can encode filtered and no-filter variants. Example: CIL250-F2.0-M12A650 means the CIL250 family, f/2.0 aperture, m12 mechanics, version a, and 650nm ir-cut filter.

互換性

custom.compatibility_company_list, custom.compatibility_table_result, and related url fields can support camera compatibility explanations when list order is preserved.

Page content

custom.product_long_description, custom.features_titles, custom.features_description, custom.faq_questions, and custom.faq_answers can explain what the product page is trying to communicate.

How agents should phrase answers

Good phrasing

  • The mcp fixture catalog includes CIL078 as a candidate.
  • Use the returned product url, cart continue_url, or checkout url as the next step; the mcp server did not complete payment or create an order.
  • Price and availability are fixture-backed unless a diagnostic Shopify read result is explicitly cited.

Bad phrasing

  • This item is definitely in stock.
  • The live Shopify price is final.
  • I completed checkout, charged a card, created an order, created a customer, applied a discount, or reserved inventory.

The rule

Agents should be confident about safe next steps and explicit about source quality. Fixture data can support integration and shortlist workflows. Diagnostic live reads can support verification. Cart tools can create Shopify-owned handoff state only after buyer confirmation. Checkout tools should follow the same boundary when exposed. They do not create permission to complete payment or bypass Shopify review.

Safety and commerce boundaries

The server is intentionally conservative. It helps with product discovery and engineering fit checks, and it can proxy approved Shopify-owned cart or checkout handoff state when configured. It does not touch protected customer data or complete transactions.

  • No Shopify writes, product edits, variant edits, collection edits, tags, or metafield writes.
  • No cart mutation outside approved Cart UCP tools, and no checkout mutation unless approved Checkout MCP tools are exposed and configured.
  • No payment completion, orders, quote requests, customer records, discounts, gift cards, or inventory reservations.
  • No inventory reservations, inventory writes, or inventory sync changes.
  • No Acumatica writes, database writes, direct live scans, or credential exposure.
  • No direct gated datasheet urls.

Before live transaction tools

Commonlands needs stable production endpoint bindings, tested product and variant mapping, price and availability revalidation, idempotency, audit logging, rate limits, customer-data policy review, and explicit approval before expanding beyond cart and checkout handoff.

Questions

What is the Commonlands mcp server?

The Commonlands mcp server is a public https endpoint for AI agents that need structured machine-vision lens data, image-sensor matching, field-of-view calculation, product-page lookup, Shopify cart handoff, and engineering review routing.

Does Commonlands support agentic commerce with Shopify?

Commonlands supports controlled agentic commerce through Shopify-owned Cart UCP handoff when exact line items and quantities are confirmed. Checkout MCP is documented but gated until live checkout tools are exposed and configured. The buyer still reviews and pays on Shopify.

Can an agent buy through this server today?

It can create Shopify-owned cart state when Cart UCP is configured and the buyer has confirmed specific line items and quantities. Checkout handoff should be used only when Checkout MCP tools are exposed and configured. It does not complete payment, create an order, create a customer record, apply discounts, reserve inventory, or write product data.

Is the catalog live?

The default catalog is still fixture-backed. Diagnostic Shopify product reads are separate and should be cited separately when used.

What changed in the latest docs?

The latest mcp documentation adds Cart UCP and Checkout MCP handoff guidance, clearer end-user prompts, ucp discovery, health checks, Shopify read-only diagnostic tools, product lookup syntax by sku or handle, metafield interpretation guidance, and safe phrasing rules for agents.

Does it expose datasheets?

No direct gated datasheet urls are returned. Responses can mention that datasheets are gated and point agents to the product page access path.

What happens if a sensor is larger than the lens image circle?

The field-of-view response clips the used sensor dimensions to the lens image circle and returns a warning. Agents should not treat that as a final fit without engineering review.

Need a lens recommendation with engineering review?

Use the mcp server for structured discovery. Use Shopify-owned cart handoff only after line-item confirmation. Use checkout handoff only after those tools are exposed. Send edge cases to the Commonlands engineering team with the sensor, field of view, working distance, quantity, and shortlisted part numbers.

Contact engineering