MCP

The Model Context Protocol (MCP) lets Agent studios such as Cursor and Claude Desktop call Aholo through a standard protocol. The official package @manycore/aholo-sdk-mcp runs locally over stdio and wraps the @manycore/aholo-sdk-* npm SDKs.

Obtain an API key in Quick Start and read Authentication before use.

MCP vs Skill vs SDK

Approach	Best for	Typical use
MCP (this page)	Cursor / Claude users	Upload local files, submit jobs, check progress
Skills	Same, with workflow guidance	Complex 3DGS flows, SkillHub one-line install
SDK	Application developers	Backend services, scripts, production integration

MCP and Skills complement each other: MCP exposes tools; Skills guide how agents should use them.

Prerequisites

• Node.js ≥ 18
• Aholo API key
  • International: labs.aholo3d.com/api-keys
  • China: labs.aholo3d.cn/api-keys

Install

Cursor

Edit ~/.cursor/mcp.json (project-level: .cursor/mcp.json):

{
  "mcpServers": {
    "aholo-sdk-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@manycore/aholo-sdk-mcp"],
      "env": {
        "AHOLO_API_KEY": "your_api_key_here",
        "AHOLO_REGION": "com"
      }
    }
  }
}

Claude Desktop

Edit the config file (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "aholo-sdk-mcp": {
      "command": "npx",
      "args": ["-y", "@manycore/aholo-sdk-mcp"],
      "env": {
        "AHOLO_API_KEY": "your_api_key_here",
        "AHOLO_REGION": "com"
      }
    }
  }
}

Restart your agent / studio after saving. In Cursor, check Settings → MCP for connection status.

Verify

AHOLO_API_KEY=your_key npx -y @manycore/aholo-sdk-mcp

Exiting with an AHOLO_API_KEY is required message when the key is missing is expected.

Environment variables

Variable	Required	Description
AHOLO_API_KEY	Yes	Aholo API key
AHOLO_REGION	No	com (international) or cn (China); can also be set per tool call

Security

Do not commit API keys to public repositories. Prefer env in mcp.json or local environment variables.

Usage notes

File upload

Pass local paths via localPath. The SDK reads files from disk and uploads to CDN — binaries are not sent through MCP.

World reconstruction (scene)

Scenario	Recommended tool
Single object / product / figurine	world_reconstruct_object_from_files or world_reconstruct_object
Indoor / room capture	world_reconstruct_space_from_files or world_reconstruct_space

• Image reconstruction requires ≥ 20 images (.jpg/.jpeg/.png/.webp); standard video resourceType=video (.mp4/.mov); Insta360 panoramic resourceType=insv (.insv)
• useMask=true enables matting (subject segmentation)
• taskQuality defaults to normal; use low for quick preview, high for professional quality

World generation (Spatial Gen)

world_generate creates an AI-generated world (not multi-image reconstruction):

• Text only: prompt only
• Single reference image: localPath only (uploads via upload_asset internally)
• Text + image: prompt + localPath (at most one image)

Reference images must use local localPath — external URLs are not accepted. For multi-image/video input, use world_reconstruct_*.

Long-running tasks

Submit tools default to wait=false and return worldId / taskId immediately:

1. Check progress (recommended): world_get / lux3d_get_task
2. Wait until done: world_wait_for / lux3d_wait_for_task (blocking)

Available tools

Recommended (scene fixed in tool name):

Tool	Description
world_inspect_local_media	Read-only: inspect local image/video
world_reconstruct_object_from_files	Local files → object (model) reconstruction
world_reconstruct_space_from_files	Local files → indoor (space) reconstruction
world_reconstruct_object	URLs → object (model) reconstruction
world_reconstruct_space	URLs → indoor (space) reconstruction

General:

Tool	Description
upload_asset	Upload local file, return CDN URL
world_generate	3DGS world generation: text only / local image / text+image (one image via localPath)
world_get / world_wait_for / world_list	Query and poll worlds

Lux3D

version is required for image/text generation: G1 or G1-Turbo. faceCount ranges from 10000 to 300000; outputFormat supports zip / glb / ply; aiPredictSize controls size prediction. Image generation requires exactly one single- or multi-view input.

Tool	Description
lux3d_image_to_four_view	Generate four standard views from one image URL
lux3d_img_to_3d_from_file / lux3d_img_to_3d / lux3d_text_to_3d	Lux3D image/text to 3D (G1 / G1-Turbo)
lux3d_material_transfer	Transfer reference materials onto a GLB model
lux3d_multi_format_export	Export a Lux3D ZIP/GLB to USDZ/OBJ/FBX
lux3d_list_tasks	List Lux3D task history with pagination, status, and time filters
lux3d_get_task / lux3d_wait_for_task	Query and poll Lux3D tasks

Current npm package: @manycore/aholo-sdk-mcp@1.6.0 (depends on @manycore/aholo-sdk-lux3d@^1.6.0; 21 tools total). Task status adds 6 (canceled), and task details include bizId.

See the npm README for the full tool list.

Related docs

• TypeScript SDK
• Aholo World Skill
• Lux3D Skill
• API Reference