Connect Claude Desktop

read as .md

mcp.ggui.ai speaks the 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.

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:

Run your server with OAuth enabled, on a URL Claude’s browser can reach:
Terminal window
```
ggui serve --oauth --public-base-url https://<your-tunnel>
```
In Claude Desktop, Settings → Connectors → Add custom connector, paste https://<your-tunnel>/mcp.
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 for the flags and 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.

Sign in to ggui (email + password — same account that holds your connector keys).
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.
The browser closes. Claude shows the connector as connected.

Under the hood, no manual client_id to copy:

Auth-server discovery via RFC 9728 (/.well-known/oauth-protected-resource) and RFC 8414.
Client registration via RFC 7591 Dynamic Client Registration.
OAuth 2.1 + PKCE; the ggui_user_* key becomes the access token.

Full protocol details: OAuth on mcp.ggui.ai.

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 when you run low.

Prefer your own model account? Paste a provider key into 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 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/<id> 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 — 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 or paste a provider key into 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.