--- title: "Install the MCP Server" description: "Connect the HTML to Image MCP server to Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Antigravity, Gemini CLI and Codex. Exact config for each client." url: "https://html2img.com/docs/mcp/installation/" --- # Install and setup Connect the HTML to Image MCP server to your AI client. The server is the same for every client: - **URL:** `https://app.html2img.com/mcp` - **Transport:** Streamable HTTP - **Auth:** the header `Authorization: Bearer YOUR_API_KEY` > **Important** > > You need a paid plan and an API key. Create one on the [API keys page](https://app.html2img.com/api-keys) (keys look like `htim_...`). Treat the snippets below like passwords - they contain your key. ## Compatibility | Client | Remote HTTP + header | Method | |--------|----------------------|--------| | Claude Code | Native | `claude mcp add` | | Cursor | Native | `url` + `headers` | | VS Code (Copilot) | Native | `type: "http"` + `headers` | | Windsurf | Native | `serverUrl` + `headers` | | Google Antigravity | Native | `serverUrl` + `headers` | | Gemini CLI | Native | `httpUrl` + `headers` | | OpenAI Codex CLI | Native | `url` + bearer token | | Claude Desktop | Via bridge | `mcp-remote` | | ChatGPT | Not supported | OAuth-only connectors | ## Claude Code ```bash claude mcp add --transport http html2img https://app.html2img.com/mcp \ --header "Authorization: Bearer YOUR_API_KEY" ``` Add `--scope user` to make it available in every project. Manage it with `claude mcp list`, `claude mcp get html2img` and `claude mcp remove html2img`. ## Cursor Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project). A server is "remote" simply by having a `url`: ```json { "mcpServers": { "html2img": { "url": "https://app.html2img.com/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` ## VS Code (GitHub Copilot) Create `.vscode/mcp.json` in your workspace (or run **MCP: Open User Configuration** from the command palette). The top-level key is `servers` and remote servers use `"type": "http"`: ```json { "servers": { "html2img": { "type": "http", "url": "https://app.html2img.com/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` To keep the key out of the file, prompt for it once with an input: ```json { "inputs": [ { "type": "promptString", "id": "html2img-key", "description": "HTML to Image API key", "password": true } ], "servers": { "html2img": { "type": "http", "url": "https://app.html2img.com/mcp", "headers": { "Authorization": "Bearer ${input:html2img-key}" } } } } ``` ## Windsurf Edit `~/.codeium/windsurf/mcp_config.json` (or use Settings -> Cascade -> MCP Servers -> "View raw config"). Remote servers use `serverUrl`: ```json { "mcpServers": { "html2img": { "serverUrl": "https://app.html2img.com/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` After saving, click "Refresh" in the MCP panel. ## Google Antigravity In Antigravity, open Settings -> Customizations -> **Add MCP**, then use **Open MCP Config** to edit the raw file. It uses the same `serverUrl` + `headers` shape as Windsurf: ```json { "mcpServers": { "html2img": { "serverUrl": "https://app.html2img.com/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` > **Note** > > Antigravity is new and its config path has moved between early builds. Use the in-app "Open MCP Config" button so you land on the exact file your install reads. ## Gemini CLI Edit `~/.gemini/settings.json` (user) or `.gemini/settings.json` (project). Use `httpUrl` for Streamable HTTP (the `url` key means SSE in Gemini CLI): ```json { "mcpServers": { "html2img": { "httpUrl": "https://app.html2img.com/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` ## OpenAI Codex CLI Edit `~/.codex/config.toml`. In Codex, `url` means Streamable HTTP. Let Codex build the auth header from an environment variable (set the variable to the raw key, with no `Bearer` prefix): ```toml [mcp_servers.html2img] url = "https://app.html2img.com/mcp" bearer_token_env_var = "HTML2IMG_TOKEN" ``` ```bash export HTML2IMG_TOKEN="YOUR_API_KEY" ``` Remote HTTP support depends on a recent Codex build. If a remote `url` server errors with a missing `command` field, upgrade Codex, or use the `mcp-remote` bridge shown below. ## Claude Desktop Claude Desktop's config file launches local (stdio) servers, and its "Connectors" UI only offers OAuth, so a static API key needs the [`mcp-remote`](https://github.com/geelen/mcp-remote) bridge. Open **Settings -> Developer -> Edit Config** to edit `claude_desktop_config.json`: ```json { "mcpServers": { "html2img": { "command": "npx", "args": [ "mcp-remote", "https://app.html2img.com/mcp", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer YOUR_API_KEY" } } } } ``` Requires Node.js 18+ on your PATH. Quit and reopen Claude Desktop fully after saving. > **Tip** > > The header value is passed through `env` (`AUTH_HEADER`) and referenced with no space after the colon (`Authorization:${AUTH_HEADER}`). This is deliberate: `mcp-remote` mishandles a `--header` value that contains a space, and this pattern avoids the bug. ## ChatGPT ChatGPT's custom connectors (Developer Mode) support remote MCP servers, but the connector UI only offers **OAuth** or **no authentication** - there is no field for a static `Authorization: Bearer` header. Because the HTML to Image server authenticates with an API key, **it cannot currently be connected through ChatGPT.** Use one of the clients above instead. ## Troubleshooting - **"Unsupported protocol version".** Update your client to the latest version. The server supports current MCP protocol revisions; very old or pre-release clients may negotiate a version it does not accept. - **401 Unauthorized.** The bearer token is missing or wrong. Re-copy your key from the [API keys page](https://app.html2img.com/api-keys). Fastest diagnostic: `curl https://app.html2img.com/api/me -H 'X-API-Key: YOUR_KEY'` - a 200 proves the key is good and the problem is the MCP header format; a 401 proves the key itself is bad. See [account status](https://html2img.com/docs/account/). - **403 / not subscribed.** MCP is paid-plans only. Check your plan on the [pricing page](https://html2img.com/pricing/). - **"No credits left".** Your monthly credits are used up. They reset on renewal, or you can upgrade. - **Images look broken.** Remote images are not loaded - embed them as base64 data URIs. See the [tools reference](https://html2img.com/docs/mcp/tools/). Signed-in users can also grab a pre-filled config from [app.html2img.com/mcp-setup](https://app.html2img.com/mcp-setup).