docs(mcp): setup instructions that work for GUI clients - #370
Merged
Conversation
Step 1 opened with a JSON config file, which desktop and web assistant apps do not have. Anyone connecting through a connector screen — the common case — had to infer that the URL buried in the snippet was the only thing they needed. It now leads with that URL and the Settings → Connectors → Add custom connector path, with the config file and the CLI one-liner kept underneath for clients that use them. The endpoint is derived from SITE_URL instead of hardcoded. It printed the production host on every environment, so preprod was handing out setup instructions pointing at a different deployment than the one you were reading them on. Adds the two things that were missing rather than wrong: Step 2 says the permissions are individual checkboxes you can untick, which only became true when the consent screen grew them. Step 3 gives a way to tell a successful connect from a half-scoped one — 13 tools for everything, 7/4/2 per permission, counted from the registry so the numbers cannot drift. Without it both states look identical: a working server with fewer tools. And a callout for the asymmetry that is easy to read as a bug: removing a permission bites on the client's next request, while adding one cannot reach a token already issued, so the client must reconnect. The toast after saving permissions said only "Applies to the client's next request" — true of a removal, false of an addition, and it was the addition case that looked broken. Verified against a production build at desktop and 375px: no content clipped, the config block scrolls internally, and the tool counts render from MCP_TOOL_SUMMARIES.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
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
1 participant
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.
The setup steps were written for someone editing a config file. Anyone connecting through a connector screen — Claude desktop or web, and most assistant apps — had to work out for themselves that the URL buried in the JSON snippet was the only thing they actually needed.
What changed
Step 1 leads with the URL and the GUI path. Settings → Connectors → Add custom connector, paste, connect. The config file and the
claude mcp addone-liner stay underneath for clients that use them, rather than being the only documented route.The endpoint is derived from
SITE_URLinstead of hardcoded in four places. It printed the production host on every environment, so preprod was handing out setup instructions pointing at a different deployment than the one you were reading them on — for GUI setup that URL is the single field you paste, so it has to be the truth for wherever you are.Two things that were missing rather than wrong
Step 2 now says the permissions are individual checkboxes you can untick. That only became true when the consent screen grew them; the copy still described a single approve-all step.
Step 3 is new: a way to tell a successful connect from a half-scoped one. 13 tools if you granted everything, 7 / 4 / 2 per permission — counted from
MCP_TOOL_SUMMARIESso the numbers can't drift from the registry. Without this the two states are indistinguishable: both look like a working server, just with fewer tools, which is exactly the confusion that prompted this.A callout for the asymmetry that reads as a bug. Removing a permission takes effect on the client's next request; adding one cannot reach a token already issued, so the client has to reconnect. Refreshing its tool list just re-asks with the same token.
The toast after saving permissions said only "Applies to the client's next request." That is true of a removal and false of an addition — and the addition case is the one that looks broken, so the UI was actively misleading in the direction that already cost time.
Verification
Built and checked in a browser at desktop and 375px: nothing clipped, the config block scrolls internally rather than blowing out its container (the failure mode from #366), the CLI command wraps inside the viewport, and the tool counts render from the registry.
1027 + 87 tests,
tscclean, build green.Not changed: this is copy and one derived constant, so there is no new test. The counts are the only thing that could silently drift and they are computed, not written down.
🤖 Generated with Claude Code