feat(mcp): one-click installs, per-client pages, PAT bridge, JSON-RPC hints - #17
Merged
Conversation
… hints
8-point UX pass to make MCP onboarding a single click for end users.
1. One-click install buttons (Cursor + VS Code deep links) on /connect and
/docs/mcp via a new <InstallButtons /> component — hands off to the
editor with the server already configured, no JSON editing.
2. Per-client landing pages at /connect/{claude,claude-code,cursor,vscode,
codex,lovable,hermes,openclaw} — focused single-card flow with copy
button, install steps, verification prompt and PAT escape hatch.
3. Personal Access Token route (/account/tokens) is now surfaced as the
primary fallback path on every connect page and in the unauthorized
hint payload — useful for clients with flaky OAuth (Hermes, OpenClaw,
n8n, Grok).
4. "Test" button on /account/connections — server-side checks for a
live, unexpired access token per client and reports back inline,
so users can tell at a glance whether a connection still works.
5. 401s from /api/mcp now return a proper JSON-RPC error with
data.hint, data.authorization_url, data.tokens_url and
data.connect_url. Clients that surface error.data inline can render
the recovery action directly in chat.
6. MCP `instructions` updated with a welcome paragraph that points users
at /connect/{client} on first call and mentions the PAT path.
7. CLI single-binary build: cli/package.json adds @yao-pkg/pkg + bun
compile scripts; .github/workflows/cli-release.yml builds binaries
for linux/macos/macos-arm64/windows-x64 on cli-v* tags so users
without Node can curl|install.
8. Stdio bridge (npx -y super-agent mcp) is now called out on per-client
pages as the escape hatch for runtimes where remote OAuth is unreliable.
https://claude.ai/code/session_019gMoupKKTVydpNwiiACQRd
criptogus
marked this pull request as ready for review
May 21, 2026 17:12
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
8-point UX pass to make MCP onboarding a single click for end users.
What's in
<InstallButtons />renders Cursor + VS Code deep links that hand off to the editor with the server already configured. Used on/connectand/docs/mcp./connect/{claude,claude-code,cursor,vscode,codex,lovable,hermes,openclaw}with one focused card each (deep link, CLI, config, manual), endpoint copy button, verification prompt, and PAT fallback./account/connections— Server-side checks for a live, unexpired access token per client and reports back inline (✓ live / ✗ reason).data.hint—/api/mcpunauthorized()now returns a proper JSON-RPC error withdata.hint,data.authorization_url,data.tokens_url,data.connect_url. Clients that rendererror.datainline can show the recovery action directly in chat.instructionswelcome paragraph — Points users at/connect/{client}on first call and mentions the PAT path. (Realnotifications/messagewould need library changes inmcp-tanstack-start.)cli/package.jsonadds@yao-pkg/pkg+buncompile scripts;.github/workflows/cli-release.ymlbuilds binaries for linux/macos/macos-arm64/windows-x64 oncli-v*tags so users without Node cancurl … | install.npx -y super-agent mcpis called out on per-client pages as the escape hatch for runtimes where remote OAuth is unreliable.Files
src/components/site/InstallButtons.tsx(new)src/routes/connect.$client.tsx(new)src/routes/api/mcp.ts— JSON-RPC error + welcome instructionsrc/lib/oauth/connections.functions.ts—testOauthConnectionsrc/routes/account.connections.tsx— Test buttonsrc/routes/connect.tsx,src/routes/docs.mcp.tsx— install buttonscli/package.json— build scripts.github/workflows/cli-release.yml(new)Test plan
/connect— Cursor opens with the server pre-filled./connect/cursor,/connect/claude,/connect/vscode,/connect/codex,/connect/lovable,/connect/hermes,/connect/openclaw— each renders a focused page./account/connections, click Test on an existing OAuth connection → ✓ live; revoke and re-test → ✗ no_live_token.upload_packages) without auth → response is JSON-RPC{ error: { code: -32001, data: { hint, authorization_url, tokens_url, connect_url } } }.cli-v0.3.0and confirm the workflow produces 4 binaries./account/tokens+ pasted as Bearer header in n8n works end-to-end.https://claude.ai/code/session_019gMoupKKTVydpNwiiACQRd
Generated by Claude Code