docs-site: "Connect to editor" one-click MCP install buttons (Cursor / VS Code)

[mattpodwysocki]

Note: This tracks a docs-site UI change, filed here for visibility. The implementation lives in the docs-site frontend, not in this repo — the MCP server is only the install target. Transfer/move to the docs-site tracker once one exists.

Summary

Add "Connect to editor" one-click install buttons for the Mapbox Docs MCP server on the docs site, following the Redocly/Sinch pattern (see developers.sinch.com). Clicking a button hands the editor a pre-filled MCP config so users skip hand-editing JSON.

Why this fits us well

• The docs MCP server is token-free and already hosted at https://mcp-docs.mapbox.com/mcp, so the button is a genuine one-click install — no API key paste, no local install.
• Smoother than the reference implementation: Sinch's buttons install a local server; ours points at the hosted endpoint.

Scope

• This is a docs-site frontend change. No change to @mapbox/mcp-docs-server; the server is the target the links point at.

Deliverables

• Cursor button — cursor://anysphere.cursor-deeplink/mcp/install?name=mapbox-docs&config=<base64>
• VS Code button — browser-safe https://insiders.vscode.dev/redirect/mcp/install?name=mapbox-docs&config=<urlencoded> form (config uses type:http for the remote server)
• Claude Code — copyable command, NOT a deep link (no URL scheme exists): claude mcp add mapbox-docs --transport http https://mcp-docs.mapbox.com/mcp
• Manual-setup fallback (raw mcpServers JSON) for editors without MCP-install-URL support

Payloads (production, hosted endpoint)

• Cursor config (raw): {"url":"https://mcp-docs.mapbox.com/mcp"} → base64 eyJ1cmwiOiJodHRwczovL21jcC1kb2NzLm1hcGJveC5jb20vbWNwIn0=
• VS Code config (raw): {"type":"http","url":"https://mcp-docs.mapbox.com/mcp"} → URL-encoded %7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp-docs.mapbox.com%2Fmcp%22%7D
• Server name: mapbox-docs

Caveats

• Custom-scheme links trigger a browser "open external app?" prompt — expected; button copy should set that expectation.
• Requires an editor build with MCP-install-URL support (current Cursor and recent VS Code). Confirm the minimum VS Code version before publishing.
• VS Code Insiders users may need the vscode-insiders: variant, or let the redirect resolve.

QA

• Cursor link opens install prompt and registers mapbox-docs at the hosted URL
• VS Code redirect link works when clicked from a browser
• VS Code Insiders users land in Insiders
• Claude Code command copies cleanly and runs without a token
• Manual-setup fallback reachable for unsupported editors
• Post-install, a docs tool call returns results against mcp-docs.mapbox.com

Reference

Full handoff spec with live buttons, drop-in HTML/markdown snippets, and payload reference prepared separately (artifact). Origin: Slack feedback from Andrew Sepic (2026-07-08).