MCP Tools Integration Guide

This document explains how to integrate Hitem3D 3D generation capabilities into common MCP clients that support the Streamable HTTP protocol (such as Cursor and Claude Desktop).

1. Scenarios and Overview

• Typical scenarios:
  • In MCP clients like Cursor and Claude Desktop, use natural language to call Hitem3D and complete “image-to-3D” tasks.
  • Let an Agent automatically poll task status and, after completion, obtain the 3D model download URL and cover image URL.
• Integration method:
  • Integrate via the MCP Streamable HTTP protocol.

2. Basic Configuration

2.1 MCP Service Endpoint

The production service endpoint is:

https://mcp.hitem3d.ai/mcp

In MCP clients such as Cursor and Claude Desktop, set the server endpoint / url to the address above.

2.2 Authentication

The Hitem3D MCP server calls the Hitem3D OpenAPI under the hood, so you need to configure Basic Auth in your MCP client:

• In your MCP client configuration (for example, Cursor’s .cursor/mcp.json file), configure the following request header for https://mcp.hitem3d.ai/mcp:
  • Authorization: Basic base64(client_id:client_secret)
• Here, base64(client_id:client_secret) is the Base64 encoding of the literal client_id:client_secret string.

A complete Cursor configuration example (located at ~/.cursor/mcp.json) looks like this:

{
  "mcpServers": {
    "hitem3d-mcp-server": {
      "url": "https://mcp.hitem3d.ai/mcp",
      "headers": {
        "Authorization": "Basic base64(client_id:client_secret)"
      }
    }
  }
}

Notes:

• Currently only Basic authentication is supported.
• Keep your client_id and client_secret safe and never expose them to untrusted environments.

3. Tool Behavior Overview

The Hitem3D MCP server automatically exposes available tools (such as submitting tasks and querying task status) to the client via the MCP protocol.
Most MCP clients (including Cursor and Claude Desktop) will automatically list these tools after a successful connection, and Agents can choose appropriate tool combinations based on their descriptions.

4. Example: Generating 3D in MCP Clients

After you have completed the following configuration in your MCP client:

• MCP server endpoint: https://mcp.hitem3d.ai/mcp
• Configure an Authorization header (Bearer or Basic) for this server in the client

you can generate 3D content directly via natural language in a conversation. For example:

• In Cursor:

  • Open the MCP panel and confirm the hitem3d server is connected (the name depends on your configuration).

  • In the conversation, you might say:

    Please generate a 3D model from this image at the highest quality resolution, and when it’s done, return the 3D model download URL and cover image URL. The image_url is: https://example.com/my-model.png

• In Claude Desktop:

  • Under “Tools / MCP”, make sure https://mcp.hitem3d.ai/mcp has been added and enabled.

  • In the conversation, you might say:

    I have a character image at image_url https://example.com/character.jpg. Please use Hitem3D to generate a textured 3D model, keep me updated on progress, and once it’s complete, return the model download URL and cover image URL.

With these prompts, the client will automatically select appropriate Hitem3D MCP tools (such as “submit generation task” and “poll task status”) and complete the full flow from 2D image to 3D model.

5. Best Practices and Recommendations

• Security management:
  • Prefer setting Authorization: Basic base64(client_id:client_secret) in a shared MCP client configuration, and avoid exposing credentials directly in conversations.
  • Avoid showing the full Basic credential in public contexts (such as shared recordings or screenshots).
• Prompting tips:
  • Clearly describe your needs in natural language—for example, provide the image URL, desired model quality or resolution, and whether textures are required—then let the Agent choose suitable tool combinations.
  • For long-running tasks, you can ask for “periodic progress updates” or “return the download URL only after the task is complete.”
• Error handling:
  • When generation fails, check the textual information returned by MCP (such as image download failure or authentication errors), then fix the image URL or reconfigure credentials according to the message before retrying.