--- title: Connect Claude Desktop description: Connect Claude Desktop to a ggui server over MCP with OAuth and render generative UI inline. --- `mcp.ggui.ai` speaks the [MCP Apps](/api/mcp-apps/) protocol, so any MCP-Apps-aware host renders ggui-generated UIs inline. Claude Desktop is the most polished client today; this page walks install and first use end to end. The same procedure works for **claude.ai**, **Goose**, and **VS Code Copilot** — anywhere you can add a remote MCP server and the host implements OAuth 2.1 + Dynamic Client Registration. See [Other clients](#other-clients). ## Available now: connect your own server The hosted `mcp.ggui.ai` endpoint is part of the managed cloud (Preview — coming soon). The identical "Add custom connector" flow already works against a self-hosted server today: 1. Run your server with OAuth enabled, on a URL Claude's browser can reach: ```bash ggui serve --oauth --public-base-url https:// ``` 2. In Claude Desktop, **Settings → Connectors → Add custom connector**, paste `https:///mcp`. 3. On first use the consent page asks you to paste a locally-minted `ggui_user_*` key — that key becomes the OAuth access token. See [CLI: serve](/cli/serve/) for the flags and [Pairing](/self-hosted/pairing/) for minting keys. ## Step 1: Add the server In Claude Desktop, open **Settings → Connectors → Add custom connector** and paste: ``` https://mcp.ggui.ai ``` Leave authentication blank — the server drives Claude through the OAuth ceremony on first use. Save. ## Step 2: Approve the connection The first time Claude calls a ggui tool (or you click **Connect** on the connector card), Claude pops a browser window to `console.ggui.ai/oauth/consent`. 1. Sign in to ggui (email + password — same account that holds your connector keys). 2. Click **Approve** on the consent card. The console mints a fresh `ggui_user_*` API key labelled `Claude Desktop` and hands it to the client through the OAuth flow. 3. The browser closes. Claude shows the connector as connected. Under the hood, no manual `client_id` to copy: - Auth-server discovery via [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) (`/.well-known/oauth-protected-resource`) and [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414). - Client registration via [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) Dynamic Client Registration. - [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1) + [PKCE](https://datatracker.ietf.org/doc/html/rfc7636); the `ggui_user_*` key becomes the access token. Full protocol details: [OAuth on mcp.ggui.ai](/api/oauth/). ## Step 3: Generate a UI In a new chat, ask Claude to do something concrete enough to need a form: > Help me triage 12 incoming product-support tickets. Show me a sortable table with severity, age, and a "draft reply" action per row. Claude calls the `ggui_render` tool with that intent. The MCP Apps capability advertised by `mcp.ggui.ai` tells Claude Desktop to render the result inline — the table appears directly in the chat, not as an external link. Submit a row and the data flows back to Claude as if you'd typed it. The first such call also seeds a blueprint cache: subsequent matching requests skip the generation step and return the cached gadget instantly. ## Tool-call budget and credits Each `ggui_render` burns a small amount of credit (LLM time + render storage). New accounts get **\$5 free credit** out of the gate; top up at [`console.ggui.ai/credits`](https://console.ggui.ai/credits) when you run low. Prefer your own model account? Paste a provider key into [`console.ggui.ai/keys/providers`](https://console.ggui.ai/keys/providers) (BYOK — Anthropic, OpenAI, Google, OpenRouter). When a BYOK key is on file for the model the request would have used, ggui calls the model on your tab and only charges for orchestration. ## Revoke the connection Two surfaces, both authoritative: - **Claude Desktop** — Settings → Connectors → ggui → **Disconnect**. Drops the cached token locally; the underlying API key on the ggui side is unaffected. - **console.ggui.ai** — on the home page, find the key labelled `Claude Desktop` (or whatever the client called itself) and click **Revoke**. The next request from any client holding that token returns `401`. The keys table at [`console.ggui.ai/keys/connector`](https://console.ggui.ai/keys/connector) is the authoritative revocation surface — every MCP-Apps client lands as one row, labelled with its DCR `client_name`. (A dedicated **Connected apps** view at `/connections` is a placeholder today; the keys table is what to use.) ## Other clients The same `mcp.ggui.ai` URL works in any host that ships MCP Apps + OAuth-DCR: - **claude.ai (web)** — Settings → Connectors → Add custom connector. Same flow, browser-only. - **Goose** — `goose configure`, then add a remote MCP server pointing at `https://mcp.ggui.ai`. - **VS Code Copilot** — drop into `.vscode/mcp.json`: `{ "servers": { "ggui": { "type": "http", "url": "https://mcp.ggui.ai" } } }`. Copilot triggers OAuth on first tool call. - **Anything that speaks RFC 7591 + RFC 9728** — drop the URL in; the server's discovery metadata bootstraps the rest. Hosts that don't speak MCP Apps yet (most CLI agents at time of writing) can still hit the endpoint with a static `Authorization: Bearer ggui_user_*` header. They lose inline rendering — `ggui_render` still works and returns the render as a `ui://ggui/render/` resource, but without MCP-Apps support there's nothing to mount it (the agent receives no URL to open). ## Troubleshooting **"Failed to connect" after approving** — stale token cache. Disconnect from Claude Desktop's connector panel and reconnect; OAuth re-runs and mints a fresh key. **OAuth browser window never opens, or closes with an error** — most often a popup blocker on `console.ggui.ai`, or you were already signed into a different ggui account in that browser profile. Allow popups for `console.ggui.ai`, sign out of the wrong account, and click **Connect** on the connector card again to restart the ceremony. To inspect what was minted, open [`console.ggui.ai/keys/connector`](https://console.ggui.ai/keys/connector) — a successful ceremony shows up as a new row labelled with the client name. **"This MCP server has not been activated"** — your account has zero credits and no BYOK key on file. Top up at [`console.ggui.ai/credits`](https://console.ggui.ai/credits) or paste a provider key into [`console.ggui.ai/keys/providers`](https://console.ggui.ai/keys/providers). **No inline rendering, only a link** — the host doesn't advertise MCP Apps capability. Upgrade to a current Claude Desktop build (MCP Apps support shipped late 2025) or open the link manually; the underlying session works either way. **Anything else** — see [Troubleshooting](/troubleshooting/).