# 3D AI Studio MCP connector: setup instructions for AI agents

You are an AI agent (for example Claude Code, Codex, Cursor, VS Code Copilot or OpenCode) and the user asked you to connect the 3D AI Studio MCP server. Follow these steps exactly.

Human readable version of this page: https://docs.3daistudio.com/mcp/agent-setup

## Connection details

| Setting | Value |
| --- | --- |
| Server name | `3daistudio` |
| URL | `https://mcp.3daistudio.com/mcp` |
| Transport | Remote MCP server over Streamable HTTP |
| Authentication | OAuth sign in through the user's browser |
| API key, headers, environment variables | None. Do not add any |

Rules:

- Use the URL exactly as written. `https://www.3daistudio.com`, URLs ending in `/sse`, and the bare domain without `/mcp` do not work.
- Never write tokens, passwords or other secrets into any config file. The client stores the sign in itself.
- The user must complete the browser sign in themselves. You cannot sign in or click Authorize for them.
- The user needs a paid 3D AI Studio plan. If the sign in page says a paid plan is required, tell the user and stop.
- MCP clients change their commands and config formats often. The connection details above are authoritative; the per-client steps below are examples that may be out of date. If a command or config key below does not work in your version, use your client's current way to add a remote MCP server with these details instead of giving up.

## Step 1: Add the server for your client

Use the section that matches the client you are running in. If you are unsure, ask the user.

### Claude Code

Run:

```bash
claude mcp add --transport http --scope user 3daistudio https://mcp.3daistudio.com/mcp
```

`--scope user` makes the server available in every project. Omit it to add it to the current project only.

### Codex (CLI, IDE extension and app share the same configuration)

Run:

```bash
codex mcp add 3daistudio --url https://mcp.3daistudio.com/mcp
```

Equivalent entry in `~/.codex/config.toml`, if you prefer to edit the file:

```toml
[mcp_servers.3daistudio]
url = "https://mcp.3daistudio.com/mcp"
```

If the client is an older Codex version that does not support remote servers, ask the user to update Codex first.

### Cursor

Add this entry to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` in the project root (this project only). Merge it into the existing `mcpServers` object if the file already exists; do not remove other servers.

```json
{
  "mcpServers": {
    "3daistudio": {
      "url": "https://mcp.3daistudio.com/mcp"
    }
  }
}
```

### VS Code with GitHub Copilot

Add this entry to `.vscode/mcp.json` in the workspace (or to the user level MCP configuration). Merge it into the existing `servers` object if the file already exists.

```json
{
  "servers": {
    "3daistudio": {
      "type": "http",
      "url": "https://mcp.3daistudio.com/mcp"
    }
  }
}
```

### OpenCode

Add this entry to `opencode.json` (project) or the global OpenCode config. Merge it into the existing `mcp` object if present.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "3daistudio": {
      "type": "remote",
      "url": "https://mcp.3daistudio.com/mcp",
      "enabled": true
    }
  }
}
```

### Any other MCP client

Add a remote MCP server named `3daistudio` with the URL `https://mcp.3daistudio.com/mcp`, transport Streamable HTTP (sometimes called "http" or "streamable-http"), and OAuth authentication. Do not configure an API key or bearer token.

### Chat apps (Claude, ChatGPT)

You cannot change these apps' settings yourself. Tell the user to open the app's connector settings and add a custom connector with the URL above:

- Claude (web or desktop): Settings → Connectors → Add custom connector
- ChatGPT: Settings → Connectors → Create

## Step 2: Start the sign in

| Client | How to start the sign in |
| --- | --- |
| Claude Code | Ask the user to run `/mcp` inside Claude Code, select `3daistudio`, and choose Authenticate |
| Codex | Usually opens automatically after `codex mcp add`. Otherwise run `codex mcp login 3daistudio` |
| Cursor | Cursor shows the server in its MCP settings with a login or connect action. Ask the user to click it |
| VS Code | Start the server (MCP: List Servers → 3daistudio → Start) and accept the authentication prompt |
| OpenCode | Run `opencode mcp auth 3daistudio` |
| Other clients | Most clients open the browser automatically on first use |

A 3D AI Studio page opens in the browser. Tell the user to:

1. Sign in with their 3D AI Studio account.
2. Review the permissions and choose which credits to use (Personal or a team).
3. Click Authorize.

Wait until the user confirms they are done. Some clients need a restart or a reload of their MCP servers after the sign in.

## Step 3: Verify

Call the `get_credit_balance` tool (or `list_available_models`). If it returns a credit balance or a model list, setup is complete. Tell the user it worked and suggest a first prompt, for example "make a low poly fox for my game".

If the tools are not visible, reload or restart the client's MCP servers and try again. If a tool returns an error, check the table below.

## Common problems

| What you see | What to do |
| --- | --- |
| "requires an active paid subscription" or "A paid plan is required" | The account has no active paid plan. Tell the user to upgrade at https://www.3daistudio.com/Pricing, then reconnect |
| The sign in page never opened | Start it manually with the command for your client in Step 2 |
| Signed out later, or the server shows as needing authentication | Run the sign in again (Step 2). For Codex: `codex mcp login 3daistudio`. For OpenCode: `opencode mcp auth 3daistudio`. For Claude Code: `/mcp` then Authenticate |
| 404, connection refused, or "not an MCP server" | Check the URL is exactly `https://mcp.3daistudio.com/mcp` |
| "Rate limit reached" | Wait the number of seconds in the message, then retry once |
| "Not enough credits" | Tell the user their balance is too low and link https://www.3daistudio.com/Pricing |

More help: https://docs.3daistudio.com/mcp/troubleshooting

## After setup: how to use the tools well

- Use `list_available_models` to compare models and credit costs. Prism 3.1 is the recommended default for 3D. Nano Banana 2.1 is the recommended default for image generation and GPT Image 2 for image edits.
- If the user attached an image in the chat, call `upload_image` once and wait for the user to upload it. Chat attachments are not visible to the other tools, and images must never be re-encoded as base64 from what you see.
- Generations return a task. Call `get_generation` repeatedly until it reports completed (3D models take 1 to 5 minutes), then call `show_generation` once to display the result.
- Every result is saved to the user's 3D AI Studio dashboard automatically.

Full tool reference for humans: https://docs.3daistudio.com/mcp/capabilities