MCP server

MCP (Model Context Protocol) is the standard way an AI model uses a service: the client asks the server what tools it has, gets typed schemas back, and calls them. X3D speaks it, which means an agent can price a model, place a print order and read the tracking number without a browser, without scraping this site and without anyone hand-writing tool definitions against our REST API.

POST https://x3dstudios.com/api/mcp

One URL. POST only, because that is what Streamable HTTP is: GET (the old event stream) and DELETE (the old session teardown) both answer 405, and there is no session id to carry. If your client wants to open a GET stream, it is speaking an older transport than this server does.

Add X3D to your client#

Two things go into the config: the URL, and your key as an Authorization header. You can leave the header out entirely and still read the materials and rates, price a weight you already know, check whether a file will print, read the current lead time and look up an order by its code, which is a reasonable way to try the server before signing up for anything.

Claude Code#

One command adds it. The name x3d is yours to choose; it is what the tools are prefixed with in the client.

claude mcp add --transport http x3d https://x3dstudios.com/api/mcp \
  --header "Authorization: Bearer $X3D_API_KEY"

Or put it in a project file, which is the better move for a repo where more than one person wants the server. Both files use the same shape.

{
  "mcpServers": {
    "x3d": {
      "type": "http",
      "url": "https://x3dstudios.com/api/mcp",
      "headers": {
        "Authorization": "Bearer x3d_live_YOUR_KEY_HERE"
      }
    }
  }
}

• Claude Code requires "type": "http" on a remote server. An entry with a url and no type is treated as a configuration error and skipped.
• Cursor identifies a remote server by the url alone and needs no type. The file is .cursor/mcp.json in a project, or ~/.cursor/mcp.json for every project.
• Both files end up holding a live credential. Put them where you would put a .env, not in a public repository.

Claude on the web and in the desktop app#

Authentication#

The key is the same x3d_live_ key the REST print API uses. Generate it at https://x3dstudios.com/profile, under Developer API key, once a card is on file. It is shown exactly once and stored only as a hash, so put it in your secret manager at the moment it is issued.

Authorization: Bearer x3d_live_YOUR_KEY_HERE

• A missing or unrecognised key is not a 401. The request succeeds, the caller is simply anonymous, and only the account tools notice.
• An account tool called without a key returns a normal result with isError set and a sentence pointing at /profile. That is deliberate: as a protocol error the model would see "the connection failed" and give up, and the person would never learn what to do.
• One key per account. Generating a new one at /profile invalidates the old one immediately, which is the fastest kill switch you have if an agent gets loose.
• The key identifies the account whose card is charged and whose orders you can read. There are no scopes and no read-only key.

The tools#

Eleven tools. Five need no key and six take one. Nine of the eleven are free: only two spend anything, and both of them refuse to run without an explicit confirmation. tools/list returns all eleven tools to everybody, keyed or not, so an agent can tell its user what a key would unlock instead of finding out by failing.

Public tools#

list_materials takes no arguments at all. Every tool on this page rejects an argument it does not know rather than ignoring it, so a misspelled field is an error you can see instead of a default you cannot.

Its shipping object carries domestic (standard and express, with rate, transit and freeOver), international (rate, freeOver and the list of countries), handlingDaysBeforeDispatch, and printSpeeds: normal and priority, each with its fee and shipsInBusinessDays. The print speeds describe the website checkout, where Priority print is 10% of the items, at least $10. An order placed through create_print_order cannot buy it and is queued as Normal print, so quote the normal figure, or better, call get_lead_time for the live one.

Account tools#

Every tool in this group needs the Authorization header. list_my_orders takes no arguments; the rest are below.

Worked example: quote a file, then order it#

Two tool calls, with a person in between. Written out as curl so you can see exactly what a client sends; in Claude or Cursor you would just ask.

1. 1
   Quote the file

   quote_print downloads the model, slices it for real, and prices it. Nothing is charged. Note the three Mcp-* headers: Mcp-Name has to equal params.name or the server answers 400.

   bashCopy

   curl -s -X POST https://x3dstudios.com/api/mcp \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -H "Authorization: Bearer $X3D_API_KEY" \
     -H "MCP-Protocol-Version: 2026-07-28" \
     -H "Mcp-Method: tools/call" \
     -H "Mcp-Name: quote_print" \
     -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "quote_print",
         "arguments": {
           "model_url": "https://raw.githubusercontent.com/acme/parts/main/bracket.stl",
           "material": "pla",
           "color": "Black",
           "quality": "standard",
           "quantity": 1,
           "country": "US"
         },
         "_meta": {
           "io.modelcontextprotocol/protocolVersion": "2026-07-28",
           "io.modelcontextprotocol/clientInfo": { "name": "acme-agent", "version": "1.4.0" },
           "io.modelcontextprotocol/clientCapabilities": {}
         }
       }
     }'

2. 2
   Read the price out of the result

   content[0].text is the sentence to show a person. structuredContent is the same answer in fields: quote_id, expires_at, the measurement and the price breakdown. price.total is the whole thing including postage to price.ships_to, which is the country you asked for or US if you did not. Ordering to anywhere else needs a fresh quote, so if you do not have the address yet, get it before you quote. A .gcode.3mf whose plate uses five or more filaments also carries price.second_ams_fee, 25, once per order and already inside price.total. Postage is always the standard service: the MCP server does not sell express shipping or Priority print.

   jsonCopy

   {
     "quote_id": "q_7f3c1a9e42",
     "expires_at": "2026-09-30T18:22:41.000Z",
     "model": { "file_name": "bracket.stl", "dimensions_mm": [62, 41, 18], "volume_cm3": 21.7 },
     "measurement": { "source": "slicer", "grams": 27.4, "print_hours": 1.31, "layers": 91 },
     "options": { "material": "pla", "color": "Black", "quality": "standard", "quantity": 1, "infill": 20 },
     "price": {
       "currency": "USD",
       "ships_to": "US",
       "print": 3.36,
       "shipping": 7,
       "total": 10.36,
       "billed_grams": 28,
       "note": "This total includes postage to US. create_print_order will only ship to US against this quote."
     }
   }

3. 3
   Show it to the person and wait

   This is the only confirmation step that exists. Show the total, the material, the colour and the full delivery address as it will be printed, and wait for a yes. Nothing downstream asks again, and there is no cancel call.

4. 4
   Place the order

   The price, the file and every print option come from the quote, so none of them is repeated. confirm: true is the record that somebody agreed. This charges the card on file. Here ada@example.com is the main contact and sam@example.com gets a copy of every email about the order. Leave notify_emails out when only one person needs them.

   bashCopy

   curl -s -X POST https://x3dstudios.com/api/mcp \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -H "Authorization: Bearer $X3D_API_KEY" \
     -H "MCP-Protocol-Version: 2026-07-28" \
     -H "Mcp-Method: tools/call" \
     -H "Mcp-Name: create_print_order" \
     -d '{
       "jsonrpc": "2.0",
       "id": 2,
       "method": "tools/call",
       "params": {
         "name": "create_print_order",
         "arguments": {
           "quote_id": "q_7f3c1a9e42",
           "confirm": true,
           "recipient_name": "Ada Lovelace",
           "email": "ada@example.com",
           "notify_emails": ["sam@example.com"],
           "street1": "1 Main St",
           "city": "Austin",
           "state": "TX",
           "zip": "78750",
           "country": "US"
         },
         "_meta": {
           "io.modelcontextprotocol/protocolVersion": "2026-07-28",
           "io.modelcontextprotocol/clientInfo": { "name": "acme-agent", "version": "1.4.0" },
           "io.modelcontextprotocol/clientCapabilities": {}
         }
       }
     }'

5. 5
   Store the order code

   The result carries order_code, paid, amount, charged, status, status_url and notify_emails, the addresses copied on the order emails. Write the code down before doing anything else, and give the person the status URL. Read paid before you tell anyone the order went through: a declined card is a successful call and not an error, because the order row is real and waiting. On that result paid is false, charged is null, amount is what the order is for, and charge_outcome says what is known about the money. When it is "not-charged" the card was provably not charged, and payment_url is where the person pays or updates the card. When it is "unknown" the charge may have gone through with only its confirmation lost: payment_url is null, and you check status_url or get_order before saying anything about the money. Either way, do not call create_print_order again and do not quote again. The print is already ordered, and re-ordering would buy it twice.

   jsonCopy

   {
     "order_code": "X3D-K7M2QP",
     "paid": true,
     "charged": 10.36,
     "amount": 10.36,
     "currency": "USD",
     "status": "RECEIVED",
     "status_url": "https://x3dstudios.com/print/order/X3D-K7M2QP",
     "payment_url": null,
     "quoted_total": 10.36,
     "notify_emails": ["sam@example.com"]
   }

Rate limits#

Every tool call is counted against an hourly allowance for the caller. A keyed caller is counted on their account, so one key's allowance follows it across machines; an anonymous caller is counted on the address we saw, which is the one thing in the request they cannot choose. The allowance is set by what the call costs us to serve, not by which tool it is.

Writing your own client#

Skip this section if you are using Claude or Cursor, which handle all of it. It matters if you are talking to the endpoint directly.

The current MCP revision, 2026-07-28, is stateless. There is no initialize call, no session id and no stream: protocol version, client info and client capabilities ride in params._meta on every request, and server/discover replaces the handshake. Most clients in the field still send initialize instead, so this server answers both and decides which era a request belongs to from the request itself.

Supported versions: 2026-07-28, the stateless one, plus the handshake revisions 2025-11-25, 2025-06-18 and 2025-03-26. A request that states no version anywhere is treated as 2025-03-26 rather than refused, because the revisions up to 2025-06-18 made the header optional. A version outside that list is a 400 with code -32022 and a data object listing what we do speak.

Each tool also carries our own facts in _meta on its tools/list entry: com.x3dstudios/cost is free, credits or money, and com.x3dstudios/auth is public or apiKey. MCP has no field for what a call costs, and a consent prompt is exactly where that belongs. Every modern result carries _meta["io.modelcontextprotocol/serverInfo"] as well, because with no handshake there is otherwise no request in which a stateless client learns who answered it.

How long a call gets depends on the work it does, not on its name. A tool that only reads, and generate_model, each get 25 seconds. create_print_order gets 45 seconds, because it is the one call where giving up early is worse than waiting: the expensive half has already committed. check_printability and quote_print get 90 seconds, because they pull a file off the internet and slice it for real, and the download alone is allowed 60. The route itself is allowed 120, so there is always room to send you a real answer instead of your own client timing out with nothing to show. One caveat for a caller coming through our public name: Cloudflare gives up at about 100 seconds, so a worst case slice answers only on the direct service host.