Connect Threekit to Claude: Configure Product Attributes and Options

If you need to give an AI agent read and write access to your 3D product configurations, you need a Model Context Protocol (MCP) server. This infrastructure layer acts as the bridge between Claude's LLM tool-calling capabilities and Threekit's visual commerce APIs. If your team uses ChatGPT, check out our guide on connecting Threekit to ChatGPT or explore our broader architectural overview on connecting Threekit to AI Agents.

Giving a Large Language Model (LLM) the ability to parse complex 3D asset trees, modify material attributes, and orchestrate rendering pipelines is an integration challenge. Threekit's data models are deeply nested, requiring sequential API calls to fully hydrate a single product configuration. You can build and maintain a custom translation layer to handle this, or you can use a managed platform like Truto to dynamically generate a secure, authenticated MCP server URL based on real-time integration schemas.

This guide breaks down exactly how to use Truto to generate a managed MCP server for Threekit, connect it natively to Claude, and execute visual configuration workflows using natural language.

The Engineering Reality of the Threekit API

Building a custom MCP server requires writing and maintaining JSON schemas that map perfectly to the underlying vendor's endpoints. With Threekit, this becomes exceptionally difficult due to the platform's advanced configuration models and asynchronous architecture. What makes the Threekit API specifically tricky?

Discriminated Unions in Payload Structures Threekit relies heavily on polymorphic data models, specifically when dealing with attributes. When creating a local attribute or attaching a global one to an asset, the API expects a discriminated union keyed by a type field (e.g., String, Number, Boolean, Color, Asset, Array). If an LLM attempts to hallucinate a payload to create a Color attribute but includes properties specific to a Number attribute (like min or max), the API will reject the request. A managed MCP server provides strictly typed, enhanced JSON schemas derived directly from the API documentation, forcing the LLM to output valid payloads for the specified type.

Asynchronous Render and Export Jobs Visual processing is not instantaneous. Operations like rendering a VRay image or exporting a 3D model run as background tasks. The API returns an initial HTTP 202 with a jobId, not the final image file. To expose this to an AI agent, you must orchestrate a polling pattern where the agent triggers the job, captures the jobId, and periodically checks the job's schedulerState via a separate endpoint until it reports success. Exposing these as separate, distinct MCP tools allows Claude to independently manage the lifecycle of long-running tasks.

Complex Reference Trees An individual catalog item in Threekit is rarely self-contained. A master "Product" asset references "Material" assets, which in turn reference "Texture" assets. Updating a variant configuration requires resolving these UUIDs correctly. If you just dump raw API schemas into an LLM context, it will struggle to understand how asset_id, attribute_id, and option_id relate to one another. Truto handles this by normalizing query and body schemas into a single flat input namespace per tool, with explicit descriptions guiding the model on where to pass specific UUIDs.

sequenceDiagram
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant Upstream as Threekit API

    Claude->>MCP: Call tool (create_a_threekit_asset_attribute)
    Note over MCP: Validates flat input namespace<br>against enhanced JSON schema
    MCP->>Upstream: POST /api/assets/{id}/attributes
    Upstream-->>MCP: Returns 200 OK (New Attribute UUID)
    MCP-->>Claude: JSON-RPC Result (Attribute Metadata)

Generating a Threekit MCP Server

Rather than hand-coding tool definitions, Truto generates them dynamically by merging your configured integration resources with documentation records. You can spin up an MCP server for Threekit using either the Truto Dashboard or the REST API.

Method 1: Via the Truto UI

This is the fastest path for administrators configuring internal environments.

1. Navigate to the integrated account page for your Threekit connection in the Truto Dashboard.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Define your configuration options (give it a name, select allowed HTTP methods, apply tool tags, or set an expiration date).
5. Click Create and securely copy the generated MCP server URL. (e.g., https://api.truto.one/mcp/abc123def456...)

Method 2: Via the API

For engineering teams building multi-tenant AI applications, you can programmatically generate unique MCP servers per customer environment.

Make a POST request to /integrated-account/:id/mcp:

curl -X POST "https://api.truto.one/integrated-account/tk_acc_98765/mcp" \
  -H "Authorization: Bearer YOUR_TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Threekit Catalog Manager Agent",
    "config": {
      "methods": ["read", "write", "custom"],
      "tags": ["catalog", "attributes"]
    }
  }'

The API provisions the server, securely hashes the credentials, and returns the endpoint payload:

{
  "id": "mcp_svr_555",
  "name": "Threekit Catalog Manager Agent",
  "config": {
    "methods": ["read", "write", "custom"],
    "tags": ["catalog", "attributes"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/abc123def456..."
}

Connecting the MCP Server to Claude

Once you possess the generated Truto MCP URL, you must register it with your AI client. The URL itself encodes the integration environment context - no additional authentication configuration is needed on the client side unless you explicitly enable secondary token validation.

Method 1: Via the Claude UI

If you are using an Enterprise or Team plan with Claude, or configuring ChatGPT Custom Connectors:

1. Open your client settings (e.g., in Claude: Settings -> Integrations -> Add MCP Server).
2. Provide a recognizable name (e.g., "Threekit Production").
3. Paste your Truto MCP URL into the endpoint field.
4. Click Add. The client will automatically send an initialize JSON-RPC handshake to discover the available tools.

Method 2: Via Manual Configuration File

For Claude Desktop users handling local agent development, you update your claude_desktop_config.json file. Because Truto's MCP runs remotely over HTTP, you will use the official @modelcontextprotocol/server-sse proxy to map local standard I/O to the remote Server-Sent Events endpoint.

{
  "mcpServers": {
    "threekit-production": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/abc123def456..."
      ]
    }
  }
}

Restart Claude Desktop. The application will connect, validate the schemas, and expose the Threekit operations as native tools.

Threekit Hero Tools for Claude

Truto exposes dozens of proxy endpoints for Threekit. We have selected six high-leverage hero tools that demonstrate the power of LLM-driven visual commerce.

get_single_threekit_catalog_by_id

Retrieves a complete Threekit asset by its UUID or customId. This returns the deeply nested structure containing all current attributes, tags, metadata, and dependencies necessary to understand how the product is built.

Contextual Usage Notes: Always call this tool first before attempting to update or patch an asset. The LLM needs the current attribute schema and existing IDs to formulate valid modification requests.

"Fetch the catalog asset with the ID 'tk-chair-001' and list out all of its current material attributes."

update_a_threekit_catalog_by_id

Overwrites or patches an existing catalog asset. Depending on the endpoint's strictness, you can modify its name, description, tags, or core attributes.

Contextual Usage Notes: Be precise with IDs. If you only want to change specific fields, instruct the LLM to preserve the existing nested structures returned by previous reads.

"Update the asset 'tk-chair-001'. Change its description to 'Ergonomic office chair with lumbar support' and add the tag 'bestseller'."

create_a_threekit_asset_attribute

Creates a local attribute or adds a global attribute reference to a specific asset. This leverages the discriminated union payload structure depending on the attribute type (String, Number, Color, Asset, Array).

Contextual Usage Notes: You must instruct the agent on the data type it is creating so it populates the correct schema fields. For example, a Number type requires min, max, and step values.

"Add a new Number attribute named 'Seat Height' to asset 'tk-chair-001'. Set the minimum value to 16, the maximum to 22, the step to 1, and the default value to 18."

threekit_catalog_variants_generate

Automatically calculates and generates all possible variants for a Threekit catalog item based on its assigned attributes and options.

Contextual Usage Notes: This is a destructive action that overwrites any invalid pre-existing variants. Use it only after finalizing all attribute and option configurations on a master item.

"Generate all catalog variants for item ID 'tk-sofa-999'. Let me know the total number of variants created."

threekit_asset_jobs_render_vray

Initiates a high-fidelity VRay rendering job for a specific asset. It allows for stage and configuration overrides.

Contextual Usage Notes: This tool returns a jobId, not an image. The agent must understand that this is an asynchronous trigger.

"Start a VRay render job for asset 'tk-table-05' using the default stage configuration. Give me the resulting Job ID."

get_single_threekit_catalog_job_by_id

Retrieves the current status and output results of a Threekit background job (like a render or export task).

Contextual Usage Notes: Instruct the agent to check the schedulerState (e.g., Pending, Running, Success, Failed). If successful, the output will contain the file references for the rendered images.

"Check the status of job 'job-888-abc'. If it is completed, provide the file output references. If it is still running, tell me to wait."

For the complete inventory of available proxy tools, authentication parameters, and normalized schemas, review the Threekit integration page.

Workflows in Action

How do these tools combine in the real world? Here are two multi-step scenarios showing AI agents handling tedious 3D configuration tasks.

Scenario 1: Configuring a New Material Attribute

A 3D Technical Artist needs to add a new fabric option to an existing couch model and ensure the backend variants reflect the change.

"Get the catalog details for the 'Modern Sofa' (ID: tk-sofa-01). Add a new Global Attribute for 'Fabric Material' using the global attribute ID 'attr-global-fabrics'. Once that is attached, generate the updated variants for the item."

Agent Execution Flow:

1. Calls get_single_threekit_catalog_by_id with id: "tk-sofa-01" to confirm the asset exists and check its current state.
2. Calls create_a_threekit_asset_attribute passing asset_id: "tk-sofa-01", name: "Fabric Material", and setting the payload type to reference the global attribute attr-global-fabrics.
3. Calls threekit_catalog_variants_generate with item_id: "tk-sofa-01" to rebuild the SKU list based on the new material matrix.

Outcome: The agent returns a confirmation that the attribute was successfully attached and reports the new total variant count generated by the system, eliminating manual clicks in the Threekit admin panel.

Scenario 2: Auditing Variants and Triggering Renders

An E-Commerce Manager is preparing for a new product launch and needs to ensure all price configurations are set before generating marketing renders.

"List the variants for catalog item 'tk-desk-300'. Find the variant corresponding to the 'Oak Finish' and update its USD price to 499.00. Then, start a VRay render job for that specific variant configuration and give me the Job ID so I can track it."

Agent Execution Flow:

1. Calls list_all_threekit_catalog_variants with item_id: "tk-desk-300" and filters the response to locate the ID for the "Oak Finish" configuration.
2. Calls threekit_variant_prices_upsert providing the item_id, variant_id, price_id: "USD", and amount: 499.00.
3. Calls threekit_asset_jobs_render_vray using the base asset ID and passing the specific configuration parameters for the "Oak Finish".

Outcome: The agent successfully updates the variant pricing in the database, initiates the heavy rendering pipeline, and hands the background jobId back to the manager for later tracking.

Security and Access Control

Exposing an enterprise visual commerce engine to an LLM requires strict boundary controls. Truto enforces security at the MCP token level:

• Method Filtering: Limit your MCP server to read-only operations by setting config.methods = ["read"]. This prevents Claude from accidentally deleting catalog assets or triggering expensive bulk render jobs.
• Tag Filtering: Group tools by functional area using config.tags. You can restrict an agent to only access tools tagged with "analytics" or "catalog", preventing it from interacting with billing or organization settings.
• Secondary Authentication: By enabling require_api_token_auth: true, possession of the MCP URL is no longer sufficient. The connecting client must also pass a valid Truto API token in the Authorization header, preventing leaked URLs from becoming security incidents.
• Ephemeral Expiration: Set an expires_at ISO datetime when generating the server. Once the timestamp passes, the routing infrastructure automatically destroys the token, making it ideal for temporary contractor access or limited-time audit agents.

A Note on Rate Limits

Visual configuration and variant generation can be incredibly resource-intensive. Threekit protects its infrastructure using strict rate limiting.

It is vital to understand that Truto does not absorb, throttle, or quietly retry rate limit errors. If an AI agent attempts to generate too many variants concurrently or spams the render endpoint, the Threekit API will return an HTTP 429 response.

Truto acts as a transparent proxy, passing that HTTP 429 directly back to the caller. We normalize the upstream rate limit information into standardized HTTP headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The connecting LLM client or agent framework is entirely responsible for reading these headers, implementing exponential backoff, and pacing subsequent tool calls.

Final Thoughts on Visual Commerce Orchestration

Connecting Claude to Threekit via a managed MCP server unlocks programmatic, conversational control over your 3D assets. Instead of writing custom API middleware to handle deeply nested JSON schemas and async job polling, you can rely on dynamic, documentation-driven tool generation. By offloading the authentication, tool parsing, and schema validation to Truto, your engineering team can focus on what actually matters: building agentic workflows that automate visual configuration and scale your digital catalog.