Skip to content

docs: add hosted MCP server config generator#4599

Draft
andrelandgraf wants to merge 9 commits intomainfrom
docs/mcp-server-config-generator
Draft

docs: add hosted MCP server config generator#4599
andrelandgraf wants to merge 9 commits intomainfrom
docs/mcp-server-config-generator

Conversation

@andrelandgraf
Copy link
Copy Markdown
Contributor

@andrelandgraf andrelandgraf commented Mar 5, 2026

Summary

  • replace the old MCP setup tabs in neon-mcp-server docs with a new interactive MCP Server Config Generator
  • generate hosted Neon MCP JSON + add-mcp command snippets from auth/transport/access selections
  • preview selected and excluded tools via list-tools, with loading/error/retry states and graceful fallback behavior

Test plan

  • run website locally and verify /docs/ai/neon-mcp-server renders the configurator
  • run local mcp-server-neon and verify /api/list-tools returns 200
  • verify generated output behavior:
    • omit X-Neon-Read-Only when read-only is disabled
    • omit X-Neon-Scopes when none or all categories are selected
    • include expected headers for API key mode and project-scoped mode

@vercel
Copy link
Copy Markdown

vercel Bot commented Mar 5, 2026 •
edited
Loading

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
neon-next Ready Ready Preview, Comment May 3, 2026 4:57am

Request Review

@andrelandgraf andrelandgraf marked this pull request as draft March 6, 2026 01:02
@andrelandgraf
Copy link
Copy Markdown
Contributor Author

andrelandgraf commented Apr 22, 2026

Updated configurator: query-param-based config + UI polish

The hosted Neon MCP server recently moved from X-Neon-* custom headers to URL query params (readonly, projectId, category) on the /mcp endpoint. The configurator has been rewritten against that contract and polished visually.

What changed

  • Generated URL now encodes access controls as query params (e.g. https://mcp.neon.tech/mcp?readonly=true&projectId=proj_123&category=projects,branches,schema,querying) — matches resolveGrantFromSearchParams in mcp-server-neon.
  • Only Authorization header is emitted, and only in API Key mode. The X-Neon-* allow-list / header validation is gone.
  • List-tools preview uses the same query params so the tool diff is always consistent with the generated URL.
  • Dropped the next/dynamic({ ssr: false }) wrapper — Next.js 16 disallows it from Server Components, and the component is already 'use client'.

UI polish

  • Segmented Auth mode control with inline descriptions.
  • Custom read-only switch and compact access card.
  • Tool categories as 2-column cards with descriptions + Select/Clear all toggle.
  • Live Server URL preview with highlighted query params.
  • Tool pills split into enabled (colored) and hidden (struck-through) groups with counts.
  • Responsive classes flipped to match the repo's desktop-first Tailwind variants.

Screenshots (hosted on screenshots/pr-4599 branch; delete that branch after review)

1. Default — OAuth, all scopes enabled

OAuth default

2. API Key mode

API key is plumbed into both the add-mcp command and JSON config headers.Authorization.

API Key mode

3. Fully restricted — read-only + single project + subset of categories

Note the live URL preview with highlighted readonly, projectId, and category query params, and the enabled/hidden tool split (11 enabled · 18 hidden).

Restricted config

4. Dark mode

Dark mode

@andrelandgraf
docs: add hosted MCP config generator to Neon docs
504833f 
Replace legacy MCP setup tabs with an interactive configurator.
It generates valid hosted Neon MCP snippets and previews selected tools.
@andrelandgraf
fix: normalize MCP API URL to list-tools endpoint
605a2a1 
Map NEXT_PUBLIC_MCP_API_URL values like /mcp or /sse to /api/list-tools.
This lets PR previews use preview MCP hosts without touching prod defaults.
@andrelandgraf
fix: simplify MCP list-tools URL configuration
794def7 
Use NEXT_PUBLIC_MCP_API_URL directly when set.
Fallback defaults to the production list-tools endpoint.
@andrelandgraf
fix: show API key in plaintext MCP instructions
5d03156 
Make the API key input visible.
Keep add-mcp Authorization output aligned with the generated JSON config.
@andrelandgraf
refactor: merge performance tools into querying scope
c44db2f 
Update MCP scope selection in docs and configurator.
Use one querying category for SQL querying and optimization tools.
@andrelandgraf
docs: clarify project-scoped excluded MCP tools
d71d72b 
Document that project-scoped mode excludes search and fetch.
Align configurator guidance text with scoped tool behavior.
@andrelandgraf
fix: default MCP configurator to streamable HTTP
7c2c50a 
Remove the SSE selector and always generate Streamable HTTP config and commands.
Fix configurator copy buttons by passing explicit copy text to code blocks.
@andrelandgraf
feat(components): switch MCP configurator to query-param config and p…
63d8cd6 
…olish UI

The hosted Neon MCP server now consumes access controls (readonly,
projectId, category) via URL query params rather than custom
X-Neon-* headers. Update the configurator to match the new contract:

- Generate URLs like https://mcp.neon.tech/mcp?readonly=true&category=...
  instead of emitting custom request headers.
- Drop the header validation and X-Neon-* allowlist; only Authorization
  remains (API key mode).
- Fetch the list-tools preview with the same query params.

UI polish:
- New Configuration / Result section split with accent bars.
- Segmented control for auth mode with descriptions.
- Custom toggle switch for read-only.
- Category picker as 2-column cards with descriptions and a
  Select/Clear all toggle.
- Live Server URL preview card with highlighted query params.
- Tool pills with a colored enabled group and a struck-through hidden
  group, plus enabled/hidden counts.
- Dropped next/dynamic { ssr: false } wrapper which is no longer
  allowed from Server Components in Next.js 16; the component is
  already marked use client.

Responsive classes use the repo's desktop-first tailwind variants.
@andrelandgraf
refactor(mcp-configurator): trim header and remove redundant sections
143415d 
Drop the hosted/streamable HTTP badge, the visible "Configuration"
heading (now sr-only), the OAuth re-authorize warning, and the
Server URL preview block (already shown in the copy-pastable
add-mcp command and JSON config below).
@andrelandgraf andrelandgraf force-pushed the docs/mcp-server-config-generator branch from 1a4cb50 to 143415d Compare May 3, 2026 04:53
andrelandgraf added a commit that referenced this pull request May 3, 2026
@andrelandgraf
chore: refresh PR #4599 screenshots after UI cleanup
2218a42
@andrelandgraf
Copy link
Copy Markdown
Contributor Author

andrelandgraf commented May 3, 2026

Follow-up: further UI trim

The configurator was further simplified in 143415d4. Screenshots in the comment above have been refreshed to match.

Removed

  • HOSTED · STREAMABLE HTTP badge in the header
  • Visible CONFIGURATION section label (kept as sr-only <h4>)
  • OAuth re-authorize warning block
  • Server URL preview block (the URL is already visible in the add-mcp command and JSON config below)

The branch was also rebased onto latest main (linear history, no merge commits).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@danieltprice danieltprice Awaiting requested review from danieltprice danieltprice is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@andrelandgraf