Skip to main content

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​

ApproachBest forTypical use
MCP (this page)Cursor / Claude usersUpload local files, submit jobs, check progress
SkillsSame, with workflow guidanceComplex 3DGS flows, SkillHub one-line install
SDKApplication developersBackend services, scripts, production integration

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

Prerequisites​

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​

VariableRequiredDescription
AHOLO_API_KEYYesAholo API key
AHOLO_REGIONNocom (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)​

ScenarioRecommended tool
Single object / product / figurineworld_reconstruct_object_from_files or world_reconstruct_object
Indoor / room captureworld_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

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):

ToolDescription
world_inspect_local_mediaRead-only: inspect local image/video
world_reconstruct_object_from_filesLocal files → object (model) reconstruction
world_reconstruct_space_from_filesLocal files → indoor (space) reconstruction
world_reconstruct_objectURLs → object (model) reconstruction
world_reconstruct_spaceURLs → indoor (space) reconstruction

General:

ToolDescription
upload_assetUpload local file, return CDN URL
world_generateText-to-3D world generation
world_get / world_wait_for / world_listQuery and poll worlds

Lux3D​

Default v3.0-standard (omit version to use). On v3.0 success, outputs[0..4] are zip / glb / usdz / obj zip / fbx zip; slots not requested via needUsdz / needObj / needFbx return NOT_REQUESTED. faceCount applies to v2.0-preview and v3.0-standard (10000–500000, default 60000); v1.0-pro ignores it.

ToolDescription
lux3d_img_to_3d_from_file / lux3d_img_to_3d / lux3d_text_to_3dLux3D image/text to 3D (supports version / faceCount / need*)
lux3d_get_task / lux3d_wait_for_taskQuery and poll Lux3D tasks

Current npm package: @manycore/aholo-sdk-mcp@1.2.1 (depends on @manycore/aholo-sdk-lux3d@^1.3.0).

See the npm README for the full tool list.