docs(mcp): Document headless / remote OAuth flow (#383)#7
Merged
Conversation
Adds a "Headless / Remote setup" section to guide/mcp.md covering the out-of-band OAuth flow for users running Claude Code on SSH / remote hosts where the browser-based localhost callback can't reach the CLI. Includes a POSIX-compatible bash recipe that registers a client, drives PKCE, prints the OOB authorize URL, exchanges the pasted code for a bearer token, and emits the exact `claude mcp add --header` command. Also cross-links from the Claude Code section and adds a troubleshooting row for the localhost-callback failure mode.
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.
Summary
guide/mcp.mdcovering the out-of-band OAuth flow for users running Claude Code (or similar HTTP-MCP clients) on SSH / remote hosts where the localhost-callback OAuth handshake can't completeclaude mcp add --header "Authorization: Bearer <token>"commandWhy
Issue veg/datamonkey-js-server#383: users running Claude Code on a remote box hit
Safari Can't Connect to the Server(or equivalent) because the OAuth flow redirects tohttp://localhost:<port>on the wrong machine. The MCP server already supports OOB (urn:ietf:wg:oauth:2.0:oob) per veg/datamonkey-js-server#385; this PR is the user-facing documentation for that capability.Test plan
npm run devindatamonkey-docs/) and confirm the new H2 renders, the>callout in Claude Code links to the right anchor, and the troubleshooting row's link resolveshttps://mcp.datamonkey.org/mcpend-to-end (smoke-tested by the issue reporter / by us before this PR)