Connect Puni

Connect the client you already use to your Puni library. It can create a scene, land an edit as a revision and ask Puni for a picture. Your scenes stay in Puni, where you can open and edit them yourself.

Open in Puni↗ to choose a client and its access.

Copy this MCP address when your client asks for a server or connection URL:

https://puni.design/api/mcp

#Choose your client

These are custom connection instructions. A working custom connection does not mean Puni is listed in a client's public directory. Public listings are not confirmed in this guide. Plugins and skills explains the difference.

#ChatGPT

These steps are for a normal ChatGPT conversation. ChatGPT Work's browser tools are a separate route. Select GPT 6 Pro if your account offers it with the connected tools.

1. Enable developer mode in Settings → Security and login. Availability depends on your account and workspace policy.
2. Open Plugins, choose +, and create Puni with the MCP URL as its Connection. Review the discovered tools.
3. Connect, sign in to Puni, choose access, and select Allow. Start a new conversation and add Puni from its tools menu.

ChatGPT setup guide↗

#Claude web

1. Open Customize → Connectors → + → Add custom connector. Enter Puni and the MCP URL. A team owner may need to add it in organization settings first.
2. Connect, sign in to Puni, choose access, and select Allow.
3. In a conversation, open + → Connectors and enable Puni.

Claude web setup guide↗

#Claude Desktop

1. Add Puni on Claude.ai through Customize → Connectors using the remote MCP URL, then open Claude Desktop with the same account.
2. Connect and complete Puni’s sign-in and consent. Remote connectors follow the account across Claude.ai and Desktop.

Claude Desktop setup guide↗

#Cursor

Open Cursor's Customize page to manage MCP servers. Add the following entry to .cursor/mcp.json for one project, or ~/.cursor/mcp.json for all projects. Keep other servers already in the file.

{
  "mcpServers": {
    "puni": {
      "url": "https://puni.design/api/mcp"
    }
  }
}

Enable Puni, complete its sign-in when prompted, and check Available Tools. If your setup uses a bearer token, use the coding client configuration below. Cursor documents both remote OAuth and token headers; this guide's Puni client check is still pending. Cursor MCP setup↗.

#Grok

1. Open Grok's connectors↗.
2. Choose New Connector → Custom.
3. Enter Puni's MCP address and complete authentication.
4. Start a conversation and ask Grok to list your Puni scenes.

Business and Enterprise accounts may need an administrator to provision the connector first. The client supports custom MCP; Puni's complete workflow still needs a Grok client check. Grok connector setup↗.

#Grok Bot

Grok Bot has a separate connection surface. Open Settings → Plugins, browse for a connector, choose Add, and authenticate. Type @ in a task to attach an installed connector. Grok Bot app setup↗.

A Puni listing or custom MCP install control has not yet been confirmed there. Grok's New Connector → Custom instructions do not establish a Grok Bot installation. If Puni is absent, use one of the confirmed custom setup paths above. You can also open Puni↗ in the Bot's browser; that is a browser workflow, and does not supply Puni MCP tools.

#Sign in and choose access

Use the browser profile signed in to the Puni account whose library you want. Review the account and client on the consent page before choosing Allow. A connection can reach only that account's scenes, within the access you grant.

Choose Read, write and render for the first scene and PNG exercise below. Read only can inspect scenes; Read and write can save edits. Sharing needs Read, write and share. Puni offers only access requested by the client. Read Scopes and tokens for the full table.

A connected badge is the beginning of the check. Ask the client to list your scenes, then run the exercise below. Settings → Agents → Connected → Disconnect revokes the connection and its refresh grant.

#Make your first scene

To check that the connection reaches your account, ask for your scenes:

puni project list --base-url https://puni.design --json

{
  "tool": "list_projects",
  "arguments": { "cursor": null, "limit": 20 }
}

Paste this into a conversation with Puni enabled:

Use Puni to create a new scene called "My first Puni scene" with one
blue rounded box. Read Puni's scene contract first. Save the scene,
change the box to coral, and save that edit as a new revision.
Render a 256 × 256 PNG of the saved revision and show me the picture.
Reopen the saved scene, confirm its revision and coral object,
and give me its Puni link.

The client should return a saved scene link, the latest revision and an actual PNG. Open the link in Puni to check the object. If you only get a written description of the picture, the visual step has not completed.

The loop is inspect_scene, then apply_scene_commands onto the revision it read. puni_render_view makes the PNG, before the send with commandsJson or after it; inspect_objects checks the saved objects afterward. Read the MCP tools reference for arguments and results.

#Pictures and exports

Remote MCP can return a PNG of a saved revision when rendering is available and the connection has render access. A scene description or evaluate_frame result is not a picture. The server advertises puni_render_film even when hosted films are disabled. Tool discovery does not establish service availability. A call returning FILM_SERVICE_UNCONFIGURED means this deployment has not enabled films; use the command line and local renderer for films in that case. Cycles uses the local renderer. Read Rendering.

A picture made elsewhere in a conversation reaches Puni only when the client supplies an input that Puni can actually import. Do not invent a file URL or treat an attachment name as uploaded bytes. Check the available import tool and its result before asking for a sculpt.

#Render a film

With render access, call puni_render_film with a saved scene id and a unique requestId. A returned job handle confirms that the deployment accepted the film request. Optionally supply revision, fps, width, start and duration. It returns a job handle immediately. Repeat the same scene and request ID with recoverOnly: true to poll. After a timeout, recover that ID before starting another.

The film is a silent H.264 MP4. Limits are 60 fps, 30 seconds, even dimensions up to 1280, 1800 frames and two billion pixels. The backend preserves the saved revision even if you edit the scene afterward. Oversized requests are refused.

A completed job supplies an asset URI and an authenticated download descriptor. Download its chunks in index order with the same account, then check the returned byte count and SHA-256. Retain the MP4 within 24 hours. Polling does not start or charge another render. Failed or cancelled films refund their hosted-render charge. FILM_SERVICE_UNCONFIGURED means this deployment has not enabled films.

#If the connection stalls

• No Puni tools: enable or attach Puni in this conversation and check the client's available tools. A skill or installed package alone may not connect a server.
• Old tools or branding: refresh the connection's metadata and begin a new conversation. In ChatGPT, open the connection in Plugins and choose Refresh. ChatGPT refresh instructions↗.
• The wrong library: disconnect, switch to the intended browser profile and Puni account, then reconnect. Listing scenes is the account check.
• A compatibility or authorization error: keep the exact message and client name. A failure before consent is not proof of a wrong password. Do not keep creating tokens to fix a client discovery error.
• Edits work but pictures fail: check render access, then try the saved revision again. A hosted render failure does not undo the save.

#Coding clients and tokens

Claude Code, Codex and clients that accept a bearer header can use a token from Settings → Agents. Choose the client and access level, create the token, and copy its configuration. The token is shown once; keep it in an environment variable and out of checked-in files.

claude mcp add --transport http puni https://puni.design/api/mcp \
  --header "Authorization: Bearer ${PUNI_AUTH_TOKEN}"

# ~/.codex/config.toml
[mcp_servers.puni]
url = "https://puni.design/api/mcp"
bearer_token_env_var = "PUNI_AUTH_TOKEN"

{
  "mcpServers": {
    "puni": {
      "url": "https://puni.design/api/mcp",
      "headers": { "Authorization": "Bearer ${env:PUNI_AUTH_TOKEN}" }
    }
  }
}

Reload the client after saving. For the terminal, run puni auth login --base-url https://puni.design, type its code in Puni and approve it; add --scope share if it should publish share links. The command line saves its token in ~/.config/puni/credentials.json, readable only by you.

Read Prompts for another scene to make, or Devices to manage a signed-in machine.