DEV Community: Positioning Stages

Schema Defaults Can Quietly Rewrite a Freight Quote: Smoke-Testing a Hosted MCP Server

Positioning Stages — Thu, 12 Nov 2026 03:43:12 +0000

A freight-rating tool exposed over MCP looks easy to wire into an agent: point the client at a URL, let it discover the tools, and let the model call quote_shipping_rates. The risk is not that the call fails. The risk is that it succeeds with inputs the model never supplied. This post walks through a shell smoke test of JTLGO's public commerce MCP server and focuses on one detail that matters for any typed tool: optional parameters with defaults, and how to catch them in the response.

The endpoint and the handshake

JTLGO publishes two connector URLs against one server. The public one, https://jtlgo.com/api/mcp, exposes six read-only tools and needs no sign-in. The account URL adds four account-scoped tools behind OAuth, started by the client only when account data is needed. JTLGO's own setup page for the public and account connectors has JSON and TOML config snippets for common clients.

The transport is JSON-RPC over HTTP POST. A plain GET is rejected with 405 on purpose; a GET returning metadata would be a second, undocumented interface. The request needs an Accept header naming both JSON and the event-stream type:

curl -s -X POST https://jtlgo.com/api/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0.1"}}}'

When this was run on 11 November 2026, the server answered with protocol version 2025-06-18 and serverInfo of jtlgo-commerce-mcp version 1.1.0. A tools/list call then returned the six public tools: search_products, quote_shipping_rates, track_shipment, get_product_detail, human_handoff and get_mcp_config, each annotated with readOnlyHint: true.

Read the schema before you trust the tool

tools/list is cheap and usually served from a static schema, so it proves reachability, not correctness. Its real value is the input schema. For quote_shipping_rates, the schema returned on the test date had two required fields, weight (kg, minimum 0.01) and countryCode (ISO alpha-2). Everything else was optional:

length, width, height in cm, described as defaulting to 20, 20 and 15.
goodsType, an enum of general, battery, liquid, powder and sensitive.
description, optional text used to infer goodsType.
limit, the number of top routes to return, 1 to 20, default 3.

That shape is reasonable for a human-facing calculator. For an agent, it creates a trap. A model that only knows "12 kg to the US" can make a valid call with two arguments, and the server will fill the box size in for it. JTLGO's longer article on which tools a freight MCP server should expose and why dimensions matter states the underlying rule: any quote tool that accepts weight without dimensions is guessing, because for almost every mode the billable figure is volumetric.

Two calls that differ only by the box

The test made two calls with the same weight and destination. The first passed real dimensions:

{"jsonrpc":"2.0","id":4,"method":"tools/call",
 "params":{"name":"quote_shipping_rates",
  "arguments":{"weight":12,"countryCode":"US","length":40,"width":30,"height":25,"goodsType":"general"}}}

The second passed only weight and countryCode. Both returned ok: true and a list of routes. The difference was in the echoed request block: the second response showed length: 20, width: 20, height: 15 and goodsType: "general" — values the caller never sent. Each route also carried actualWeight, volumeWeight and chargeableWeight. With the 40 × 30 × 25 cm box the volumetric figure on the routes was 5; with the defaulted box it was 1. At 12 kg actual weight the chargeable weight was 12 in both cases, so the headline result happened not to change.

Swap in a light, bulky product and it would. That is the failure mode: an agent that omits dimensions gets a confident, well-formed answer for a smaller box than the real one. Every response also carried a notice that estimated rates are for reference only and that final pricing depends on actual cargo details and JTLGO's manual confirmation, which matches the company's position that final freight is confirmed after warehouse measurement.

Guardrails worth putting in the client

Three checks are cheap to add on the agent side:

Require what the server defaults. In the tool-use prompt or a wrapper, refuse to call quote_shipping_rates without all three dimensions. If the user has none, ask for packed carton size rather than letting the default stand in.
Diff the echo. Compare the request block in the response with the arguments you sent. Any field present in the echo but absent from your call was defaulted; surface it to the user.
Classify the cargo explicitly. Pass goodsType deliberately. Batteries, liquids and powders are separate classes in the enum, and restricted cargo is exactly where a rating engine may return nothing.

For the last case the server provides human_handoff. JTLGO's guidance is that when confidence is low — restricted commodities, unusual lanes — the correct behaviour is to hand off rather than extrapolate. get_mcp_config returns a support block with email and WhatsApp contacts and a message asking for product links, destination, package weight and dimensions, and delivery deadline. The same engine powers the human-facing Rate & Ship calculator, which is a useful cross-check when an agent result looks odd.

Scope to state in your agent's instructions

JTLGO describes the connector's scope plainly: it quotes China-origin express, air and ocean options with billable weight calculated from the dimensions supplied, and it does not rate domestic truckload movements inside the destination country. track_shipment accepts up to 10 numbers per call. Put both facts in the system prompt so the model does not promise an LTL or FTL quote the tool cannot produce.

Questions about the connector or a specific shipment can go to sales@jtlgo.com.

FAQ

Do I need an API key for the public tools?
No. The public URL needs no sign-in. Account tools use an OAuth flow started by the client.

Why does my GET request fail?
The endpoint accepts JSON-RPC over POST only; GET is rejected with 405 by design.

How do I know if a dimension was defaulted?
Compare the request object in the response with the arguments you sent.

Does the server quote US domestic LTL?
No. It covers China-origin export routes, not domestic truckload rating in the destination country.

The Motorized Positioning Stage RFQ Checklist: What to Send for an Accurate Quote

Positioning Stages — Tue, 03 Nov 2026 08:47:37 +0000

The quality of a quotation depends on the quality of the request. A request that says "XY stage, 25 mm, high accuracy" gets either a guess or a round of questions. A request that states motion, load, orientation, precision basis and supply scope gets a firm answer faster. This checklist follows the structure of the positioningstages.com request-a-quote form, so you can prepare everything before you start.

Complete multi-axis assemblies are one of the supply-scope options in the inquiry form. Photo: positioningstages.com.

Gather the basics first

1. Contact and context

Name, work email, company or institution and country are required. Phone or WhatsApp is optional. If you already know a model or series, add it; if you found a candidate with the stage selector, quote its part number exactly, because part numbers encode table, screw, travel and motor frame.

2. Application and motion

Pick the application: imaging or microscopy, optical alignment or photonics, inspection or metrology, assembly or dispensing, research or laboratory, or other. Then the motion: one linear axis, XY, XYZ, rotation, tilt, vertical lift, XY plus rotation, or a custom arrangement. Say what moves (sample, camera, optics, tool or a complete fixture) and the motion sequence: move-settle-measure, continuous scanning, repeated point-to-point or a coordinated path. "Not yet defined" is a valid answer for each and invites guidance.

Define motion, load and precision

3. Travel and angle per axis

State the total travel for every axis and the angle for every rotary or tilt axis. Avoid Â± notation unless you mean it, and say so; positioningstages.com converts half-range catalogue figures to totals precisely because the two are easy to confuse. Add the approach and clearance margin you need at each end.

Reference the drawing revision in your RFQ. Drawing: positioningstages.com.

4. Load and orientation

Give the total moving load in kg, g or lb, including fixtures and adapter plates. Describe the centre of mass position if it is off-centre. Choose an orientation: horizontal, vertical with the load travelling up and down, inverted, or several. The catalogue's payload values are presumed horizontal and centred, so orientation is the field that most often changes the recommendation.

5. Precision target with its basis

Enter the number and say which quantity it is: repeatability, positioning accuracy or step size, with a unit from Âµm, mm, degrees, arc-minutes or arc-seconds. If reversals matter, ask for bidirectional repeatability and backlash, since the catalogue does not publish them. If you have an acceptance method, describe it; no measurement standard or test temperature is cited in the catalogue, so your method becomes the reference.

Environment, control and supply scope

6. Environment and quantity

Choose indoor laboratory, factory floor, cleanroom, vacuum or other, and add pressure, cleanliness or temperature limits in the details. Give the quantity, since a single prototype and a repeat OEM requirement are quoted differently.

Drive, controller and cables must be named in the supply scope. Image: positioningstages.com.

7. Control and supply scope

Preferred control can be PC, PLC or machine integration, an existing controller, a standalone controller or a recommendation. Supply scope can be stage only, stage and controller, a complete multi-axis assembly, an upgrade or replacement, or a recommended configuration. Each product page lists drive, controller, cable set, CAD and mounting hardware as Not stated, so name each item you expect. The site's guide on comparing quotations by included components and options helps when you have several offers.

8. Attachments

Attach up to three drawings or photos. A photo of the part and a rough fixture sketch are often more useful than a long description. Send native CAD after engineering replies, which keeps unscanned executable files out of the first exchange. Label each file so the engineer can match it to the axis or fixture it describes.

What happens next

Engineering checks travel, load, accuracy, speed and orientation together, asks before pricing if a requirement is unclear or a standard model cannot meet it, then issues a quote that states inclusions, options and known exclusions. Read the specification basis guide and the editorial on writing a positioning stage RFQ for more detail.

Common gaps in RFQs

The requests that need the most follow-up usually miss one of four things: orientation, the precision basis, the moving mass of fixtures, or the electronics. A two-line note covering those saves a round of email. If the project is a prototype that may move to OEM volume later, say so at the start; the requirements package tends to grow, and early notes on datums, limits and drawings make the later hand-over easier.

Frequently asked questions

Do I need a drawing to ask for a quote?

No. Drawings are optional. The form lets you pick "Not yet defined" for most fields and ask for guidance.

What files can I attach?

Up to three PDF, JPEG, PNG, WebP or TIFF files, 10 MB each and 25 MB combined. Native CAD is sent after engineering replies.

Does submitting create an order?

No. The site states that submitting is not an order, there is no charge and the form creates no purchasing commitment.

What happens after I submit?

Engineering reviews travel, load, accuracy, speed and orientation together, asks about missing details, then defines the supply scope with inclusions, options and known exclusions.

Contact

Ready to ask for a quote? Send whatever parts of this checklist you know; unknowns are fine and engineering will ask about the rest. Email sales@deyivision.com or visit the positioningstages.com contact page.