feat(mcp): add no-OAuth docs-only endpoint at ?category=docs#230
Open
andrelandgraf wants to merge 2 commits intomainfrom
Open
feat(mcp): add no-OAuth docs-only endpoint at ?category=docs#230andrelandgraf wants to merge 2 commits intomainfrom
andrelandgraf wants to merge 2 commits intomainfrom
Conversation
Strict docs-only mode (?category=docs with no other category and no projectId) bypasses withMcpAuth entirely so the documentation tools (list_docs_resources, get_doc_resource) can be embedded anonymously without an OAuth flow. These handlers only fetch from neon.com and never touch the Neon API client, so anonymous access is safe. Any other category combination, or the presence of a projectId, keeps today's authenticated flow.
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
|
🚀 Deployed to https://preview-mcp.neon.tech This PR now owns the preview environment. OAuth flow is available for testing. |
Keep anonymous docs mode independent from the authenticated tool handler map by sharing small docs fetch helpers and registering the two docs callbacks directly.
3 tasks
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
?category=docswith no other category and noprojectId) that bypasses OAuth entirely on/api/mcpand/api/sse, exposing onlylist_docs_resourcesandget_doc_resource.mcp.neon.tech/mcp?category=docs) with no account, no OAuth flow, and noWWW-Authenticate401 challenge.projectId, keeps the existing authenticated flow unchanged.Why it's safe
The two docs handlers (
landing/mcp-src/tools/tools.ts) only callfetch(NEON_DOCS_INDEX_URL)/fetch(\${NEON_DOCS_BASE_URL}/${slug}`)and never touchneonClientorextra.account.validateDocSlug` already blocks path traversal and absolute URLs.Implementation
isDocsOnlyRequest(params)helper inlanding/mcp-src/utils/grant-context.ts.createDocsOnlyMcpHandler()inlanding/app/api/[transport]/route.ts. It builds amcp-handlerinstance withoutwithMcpAuth, registers only docs-scoped tools, and overridestools/listto surface only that subset. Telemetry uses a fixedanonymous-docsanonymousId.handleRequestbranches to the lazily-initialized docs-only handler before falling through toauthHandler.getAvailableTools/grant-filterfor docs-only so the always-availablesearch/fetchtools (which need API auth) are not surfaced anonymously.Test plan
pnpm run lintpnpm run typecheckpnpm run fmt:checkpnpm run knippnpm run test:unit(135/135 pass, includes 9 new cases forisDocsOnlyRequest)pnpm run test:e2e:web(22/22 pass, includes 5 new cases ine2e/docs-only-mcp.spec.tscovering: initialize without auth,tools/listreturns only docs tools,tools/call list_docs_resourcessucceeds, mixed categories still 401, andcategory=docs+projectIdstill 401)curl -X POST 'https://preview-mcp.neon.tech/mcp?category=docs' -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{},\"clientInfo\":{\"name\":\"smoke\",\"version\":\"1.0.0\"}}}'→ expect 200 with noWWW-Authenticateheader.?category=docsstill returns 401 with OAuth challenge.Risk / follow-ups
neon.com. If abuse is a concern, add a per-IP rate limit (out of scope here)./.well-known/oauth-protected-resourcekeeps advertising OAuth; clients only act on it after a 401, which we no longer return for docs-only requests, so this is a no-op for them.