How to Give Your AI Agent Geometry Awareness

Your AI agent can read documents, write code, and call APIs. But what happens when someone drops an STL file into the conversation? Or when your pipeline receives a glTF asset that needs quality checks?

Without geometry awareness, the agent is stuck. It can’t parse binary mesh formats, and bundling geometry libraries (trimesh, Open3D, CGAL) adds heavyweight dependencies and C++ build complexity.

Caliper gives your agent geometry awareness through a single MCP endpoint. This tutorial walks through the integration end-to-end.

The architecture

User or pipeline
    ↓ (sends 3D file URL)
Your AI agent
    ↓ (MCP tool call)
Caliper (caliper.fit/mcp/)
    ↓ (structured JSON)
Your AI agent
    ↓ (reasons about geometry)
Decision or report

Your agent doesn’t download or parse the file. It calls Caliper, gets metadata as JSON, and reasons about it like any other structured data.

Step 1: Register Caliper as an MCP tool source

Point your agent’s MCP client at:

https://caliper.fit/mcp/

This exposes 9 tools to your agent. The agent can discover them via the manifest at https://caliper.fit/mcp/manifest.

Claude Desktop

{
  "mcpServers": {
    "caliper": {
      "url": "https://caliper.fit/mcp/"
    }
  }
}

Python (using an MCP client library)

from your_mcp_client import MCPClient

client = MCPClient()
client.add_server("caliper", "https://caliper.fit/mcp/")

# List available tools
tools = client.list_tools("caliper")
for tool in tools:
    print(f"{tool.name}: {tool.description}")

Programmatic agents (LangChain, CrewAI, etc.)

Most agent frameworks support MCP or custom tool definitions. Wrap Caliper’s REST endpoints as tools if your framework doesn’t have native MCP support:

import requests

def caliper_auto_stats(file_url: str) -> dict:
    """Analyze a 3D geometry file and return structured metadata.

    Returns vertex counts, face counts, bounding boxes, surface area,
    volume, manifold/watertight status, and format-specific details.
    """
    response = requests.post(
        "https://caliper.fit/tools/caliper_auto_stats",
        json={"file_url": file_url}
    )
    # Handle x402 payment flow here if needed
    return response.json()

Register this function as a tool in your framework of choice.

Step 2: Build a file triage workflow

Here’s a practical pattern — an agent that receives 3D file URLs and triages them:

TRIAGE_PROMPT = """You have access to the Caliper geometry analysis tools.

When given a 3D file URL:
1. Use caliper_detect_format to identify the file type
2. Use caliper_auto_stats to get full metadata
3. Report:
   - File format and size
   - Geometry complexity (vertex/face count)
   - Spatial extents (bounding box)
   - Quality status (manifold? watertight?)
   - Any concerns for downstream processing

Flag files that are:
- Over 1M triangles (may need decimation)
- Not manifold (will fail 3D printing)
- Not watertight (volume calculations unreliable)
- Have a bounding box larger than 1000mm in any axis (check units)
"""

The agent uses Caliper tools just like any other tool — no geometry code, no file parsing, no special dependencies.

Step 3: Handle multiple file formats

Caliper handles format detection automatically with caliper_auto_stats, but your agent can use format-specific tools when it needs to:

ScenarioTool to use
Unknown file, just analyze itcaliper_auto_stats
Known STL, want STL-specific fieldscaliper_stl_stats
Batch of mixed filescaliper_batch_stats
Quick format check before analysiscaliper_detect_format (free)

The format-specific tools return the same core fields plus format-specific extras (e.g., glTF scene hierarchy, LAS classification distribution).

Step 4: Batch processing for pipelines

For asset pipelines that process many files, use caliper_batch_stats:

def triage_asset_batch(file_urls: list[str]) -> list[dict]:
    """Analyze up to 10 files in a single API call."""
    response = requests.post(
        "https://caliper.fit/tools/caliper_batch_stats",
        json={"files": [{"file_url": url} for url in file_urls]}
    )
    return response.json()

One payment covers the entire batch — more efficient than individual calls.

Example: Manufacturing QA agent

A practical example — an agent that checks STL files before they’re sent to a 3D printer:

QA_PROMPT = """You are a manufacturing QA agent. For each STL file submitted:

1. Analyze with caliper_auto_stats
2. Check these quality gates:
   - Is the mesh watertight? (required for slicing)
   - Is the mesh manifold? (required for reliable slicing)
   - Is the bounding box within printer limits? (300mm x 300mm x 400mm)
   - Is the triangle count under 500K? (larger files slow down slicing)
3. Return PASS or FAIL with reasons

If FAIL, suggest next steps (repair tools, decimation, rescaling).
"""

The agent doesn’t need to understand mesh topology — Caliper computes is_manifold and is_watertight and the agent reasons about the boolean.

What your agent gets back

Every caliper_auto_stats response includes:

  • format — detected file type (e.g., stl_binary, obj, gltf)
  • vertices / triangles / faces — geometry complexity
  • bounding_box — {min: [x,y,z], max: [x,y,z]}
  • surface_area / volume — for watertight meshes
  • is_manifold / is_watertight — topology quality flags
  • Format-specific fields (point count for PCD/LAS, scene structure for glTF, etc.)

All values are structured JSON. Your agent can compare, filter, and reason about them directly.

Next steps