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.
https://hello3d.ai/api/mcpcreate_model"@Hello3D create a cute round cartoon fox 3D model"
Text-to-3D (10–20 credits) or public HTTPS image URL (20–30 credits)
get_model_taskstatus: "queued" → "success" (100%)
Tracks generation progress; failed tasks auto-refund credits
get_model_downloadfox.glb · signed URL (300s TTL)
Download textured GLB or open Studio for STL / 3MF / FBX
Connection Options
| Client / Mode | Authentication | Credit Cost | Notes & Status |
|---|---|---|---|
ChatGPT Web | OAuth 2.1 (CIMD) | Text: 20 credits / Image: 30 credits | No API key required; mention @Hello3D in chat (verified in production) |
Codex CLI | Bearer API Key | Text: 20 credits / Image: 30 credits | Uses 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
- 1Sign in or register at Hello3D (https://hello3d.ai/) and make sure you have enough credits.
- 2Have a ChatGPT or Codex account and a supported device. Model creation is a real action that consumes credits.
- 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.
ChatGPT: connect with OAuth
Add Hello3D as a custom MCP server in ChatGPT on the web using OAuth—no API key required.
| Field | Value | Description |
|---|---|---|
| Name | Hello3D | Invoke in chat by typing @Hello3D |
| Server URL | https://hello3d.ai/api/mcp | Connect using the remote Streamable HTTP server URL |
| Authentication | OAuth | Redirects to Hello3D to sign in and authorize your own account |
| Client Registration | CIMD | Select CIMD if prompted; do not choose No Auth and do not enter an API key |
- 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).
- 2Name it Hello3D, enter https://hello3d.ai/api/mcp as the server URL, and select OAuth authentication.
- 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.
- 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.
- 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.
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.
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
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 listAfter 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.
$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 listThese 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.
create_model— Generate a 3D modelCreate 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| request_id | string (uuid) | Required | Unique UUID for this generation; reuse with the same inputs when retrying |
| prompt | string | Optional* | Text description (up to 2000 chars; provide prompt, image_url, or both) |
| image_url | string (https) | Optional* | Public HTTPS image URL (PNG, JPEG, or WebP) |
| image_file | object | Optional* | Image attachment supplied by a compatible client; do not use with image_url |
| is_public | boolean | Optional | Defaults to true; private generation requires an eligible paid account |
get_model_task— Check a 3D model taskPoll your Hello3D task status by ID. Reconciles provider status and refunds credits automatically if a task fails.
| Parameter | Type | Required | Description |
|---|---|---|---|
| task_id | string | Required | The task.id returned by create_model |
get_model_download— Get a model download linkIssues a 5-minute (300s) signed download URL for a completed model. Call again anytime if the link expires.
| Parameter | Type | Required | Description |
|---|---|---|---|
| task_id | string | Required | Completed 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.