Hello 3D

Hello3D Remote MCP

Connect Hello3D MCP to ChatGPT and Codex

Create 3D models from text, public HTTPS images, or attachments in compatible clients; check status and fetch signed GLB links via ChatGPT OAuth or Codex CLI API keys.

MCPhttps://hello3d.ai/api/mcp
Create API Key
How it works in 3 tool callsInspect real generated GLB samples
01 · PROMPTcreate_model

"@Hello3D create a cute round cartoon fox 3D model"

Text-to-3D (10–20 credits) or public HTTPS image URL (20–30 credits)

02 · POLL STATUSget_model_task

status: "queued" → "success" (100%)

Tracks generation progress; failed tasks auto-refund credits

03 · DOWNLOAD GLBget_model_download

fox.glb · signed URL (300s TTL)

Download textured GLB or open Studio for STL / 3MF / FBX

Connection Options

Client / ModeAuthenticationCredit CostNotes & Status
ChatGPT WebOAuth 2.1 (CIMD)Text: 20 credits / Image: 30 creditsNo API key required; mention @Hello3D in chat (verified in production)
Codex CLIBearer API KeyText: 20 credits / Image: 30 creditsUses HELLO3D_API_KEY env var (tool discovery & lookup verified; pilot stage)

Both clients connect to the same remote MCP endpoint and spend credits from your own Hello3D account according to Hello3D's live pricing.

Model generation is asynchronous. Submitting create_model returns a task.id; poll get_model_task until status is "success", then call get_model_download for a 5-minute signed GLB download URL.

Hello3D is not yet listed in the public OpenAI plugin directory. This guide covers a manual connection for early testers. ChatGPT custom MCP availability depends on your account, workspace permissions, and OpenAI's current rollout.

Before you start

  1. 1Sign in or register at Hello3D (https://hello3d.ai/) and make sure you have enough credits.
  2. 2Have a ChatGPT or Codex account and a supported device. Model creation is a real action that consumes credits.
  3. 3In ChatGPT on the web, try attaching a PNG, JPEG, or WebP image directly, or use a public HTTPS image URL. Attachment support depends on the client. Codex desktop direct upload is still being tested and is not yet released.
OAUTH

ChatGPT: connect with OAuth

Add Hello3D as a custom MCP server in ChatGPT on the web using OAuth—no API key required.

FieldValueDescription
NameHello3DInvoke in chat by typing @Hello3D
Server URLhttps://hello3d.ai/api/mcpConnect using the remote Streamable HTTP server URL
AuthenticationOAuthRedirects to Hello3D to sign in and authorize your own account
Client RegistrationCIMDSelect CIMD if prompted; do not choose No Auth and do not enter an API key
  1. 1Sign in to ChatGPT in a browser and open Plugins. Select the plus button or Add, then Add custom MCP server (labels may vary by version).
  2. 2Name it Hello3D, enter https://hello3d.ai/api/mcp as the server URL, and select OAuth authentication.
  3. 3If asked for a client registration method, choose CIMD. You do not need a Hello3D API key for this connection. If there is no registration-method choice, continue with the OAuth flow shown.
  4. 4Review the on-screen notice and create the plugin. Continue to connect Hello3D, sign in to your own Hello3D account, review the permissions, and authorize. Do not paste passwords or API keys into a chat.
  5. 5Find and install Hello3D in your personal plugins. Start a new chat and type @Hello3D to select it. If the entry is unavailable, check your account and workspace permissions.
Try in ChatGPT

Use Hello3D to create a cute round cartoon fox 3D model. Tell me before submitting that this uses Hello3D credits; check the task and provide a download link when it is ready.

For an attached image, upload it in ChatGPT and ask: Use Hello3D to create a 3D model from the image I just attached, then provide a download link. Attachment support depends on the client; otherwise use a public HTTPS image URL. Free-account models may enter public review. Download links expire after 5 minutes and can be requested again; keep them private.

CLI

Codex CLI: connect with a Hello3D API key

For command-line users. The server supports API-key authentication using Codex CLI's remote MCP and environment-variable configuration.

Pilot status: A separate Codex CLI session connected to the production server with an API key, discovered all three tools, and looked up an existing task, but direct generation and download have not yet been tested end to end; use this guide for a limited pilot first.

1. Create your own API key

Sign in to Hello3D API Keys settings, select Create API Key, and enter a name such as Codex. Copy or save the full key shown in the dialog before closing it; the list displays only its prefix. Each person must use their own key—do not share it in chats, screenshots, or repositories.

Open Hello3D API Keys settings →

2. Configure a terminal

macOS (zsh / bash) & Linux (bash)
printf 'Paste your Hello3D API key (input is hidden): '
read -rs HELLO3D_API_KEY
printf '\n'
export HELLO3D_API_KEY
codex mcp add hello3d_remote \
  --url https://hello3d.ai/api/mcp \
  --bearer-token-env-var HELLO3D_API_KEY
codex mcp list

After the second line, paste the key and press Enter; the input is hidden. codex mcp list should list hello3d_remote. If the name already exists, inspect it with codex mcp get hello3d_remote or replace it with codex mcp remove hello3d_remote before adding it again.

Windows (PowerShell 7)
$env:HELLO3D_API_KEY = Read-Host 'Paste your Hello3D API key' -MaskInput
codex mcp add hello3d_remote `
  --url https://hello3d.ai/api/mcp `
  --bearer-token-env-var HELLO3D_API_KEY
codex mcp list

These commands store the environment variable name (HELLO3D_API_KEY), not the key itself, in the MCP configuration. The key is available only to the current terminal and its child processes. After closing the terminal, repeat the key input and environment-variable steps before starting codex from that same terminal.

The Codex desktop app launched from its icon typically will not inherit the variable from your terminal, so start with Codex CLI from the same terminal. Do not assume that the ChatGPT OAuth flow works in Codex; that path has not yet been verified.

3. Generate and download

Run codex from the same terminal, start a new session, and ask:

Use hello3d_remote to create a cute cartoon fox 3D model. Check the task when it is ready and download it to fox.glb in the current working directory. Tell me before submitting that generation uses Hello3D credits.

Follow Codex's permission prompts. Download completion depends on the environment's network and file permissions; you can instead request a temporary link and download it in your browser.

MCP Tools Reference (3 Tools)

Once connected, clients discover three tools. create_model requires a UUID request_id for idempotency so network retries do not double-charge.

POSTcreate_model— Generate a 3D model

Create a Hello3D v3.1 model from text, a public HTTPS image URL, or a compatible client attachment. Use a new UUID request_id for each intended model and reuse it when retrying.

ParameterTypeRequiredDescription
request_idstring (uuid)RequiredUnique UUID for this generation; reuse with the same inputs when retrying
promptstringOptional*Text description (up to 2000 chars; provide prompt, image_url, or both)
image_urlstring (https)Optional*Public HTTPS image URL (PNG, JPEG, or WebP)
image_fileobjectOptional*Image attachment supplied by a compatible client; do not use with image_url
is_publicbooleanOptionalDefaults to true; private generation requires an eligible paid account
GETget_model_task— Check a 3D model task

Poll your Hello3D task status by ID. Reconciles provider status and refunds credits automatically if a task fails.

ParameterTypeRequiredDescription
task_idstringRequiredThe task.id returned by create_model
GETget_model_download— Get a model download link

Issues a 5-minute (300s) signed download URL for a completed model. Call again anytime if the link expires.

ParameterTypeRequiredDescription
task_idstringRequiredCompleted task ID with status "success"

Troubleshooting

No custom MCP option

Check that you are using ChatGPT on the web and that your account, plan, and workspace administrator permit custom plugins.

ChatGPT authorization fails

Check the complete server URL (https://hello3d.ai/api/mcp) and OAuth setting; select CIMD if offered. Start a fresh connection from the plugin page and confirm that you can sign in to Hello3D.

Codex reports unauthorized or cannot find tools

Start a new Codex session from the terminal where HELLO3D_API_KEY is set. Check that the key has not been deleted and that your account is active. codex mcp list confirms the entry exists, not that authentication succeeds.

Insufficient credits or failed task

Check your balance and task status in Hello3D. Refunds depend on the site's actual task result. Check an existing task before submitting again; a new submission may incur another charge.

Expired download link

Download links expire after 5 minutes. Ask the client to call get_model_download again to issue a fresh link.

Privacy and credentials

An API key is an account credential. If you no longer need it or suspect exposure, delete it in API Keys settings and create a replacement. Public visibility and private generation depend on account eligibility and site rules; free-account models may be submitted for public review.