Skip to content

PRDCT-359: split the MCP section into Diátaxis pages and kill the Management duplicate - #1074

Draft
Iamfle4ka wants to merge 9 commits into
mainfrom
PRDCT-359-mcp-diataxis
Draft

PRDCT-359: split the MCP section into Diátaxis pages and kill the Management duplicate#1074
Iamfle4ka wants to merge 9 commits into
mainfrom
PRDCT-359-mcp-diataxis

Conversation

@Iamfle4ka

@Iamfle4ka Iamfle4ka commented Aug 4, 2026

Copy link
Copy Markdown
Collaborator

What and why

/ai/mcp-server/ was a 564-line frankenstein — explanation, per-client setup, tool reference, access-control headers, local execution and SDK recipes on one page — and management/project/mcp-server/ was an 18-line stub duplicating it in the nav, sending readers back to the AI section. One reader need, one page:

New page Type Carries
/ai/mcp-server/ explanation what MCP is, what an assistant can do, hosting/OAuth/permissions, dev-branch scoping, section map, support
/ai/mcp-server/connect/ how-to server URL → per-client setup (Claude, Claude Code, ChatGPT, Cursor, Windsurf, VS Code, Make, any other) in synced tabs, plus the programmatic recipes
/ai/mcp-server/tools/ reference tool categories, X-Allowed-Tools / X-Disallowed-Tools / X-Read-Only-Mode, filter order, read-only set, examples
/ai/mcp-server/self-hosted/ how-to Docker, uv, Streamable HTTP mode, pointing a client at localhost

The stub is deleted with redirect_from, so /management/project/mcp-server/ 301s onto the hub and the nav carries one MCP entry with three children in reading order. Pages are split by Diátaxis type only — no "for developers" page; the SDK recipes are the same connect task behind an on-page note.

Fixes found while doing it

Two dead facts inherited from the pre-split page (both verified against keboola/mcp-server; evidence recorded inline as VERIFY(owner) comments so they can be challenged):

  • GOOGLE_APPLICATION_CREDENTIALS for BigQuery — the variable exists nowhere in the server, there is no google-cloud/google-auth dependency, and BigQuery workspace queries have gone through the Query Service since AJDA-2801 (2026-05-29). Readers were exporting and mounting a GCP service-account key for nothing. Removed.
  • Credentials in the localhost URL (?storage_token=…&workspace_schema=…) — the server stopped reading config from the query string (KAB-1068) and --accept-secrets-in-url has since been removed. Reproduced live: the documented form returns "Storage API token is not provided." Replaced with env vars / CLI flags / X-Storage-Token headers.

And one blocker of my own making, caught by a live pass: self-hosted told readers to connect to localhost:8000 without ever naming --transport streamable-http — the HTTP half of the page was unreachable from its own instructions. Documented, with the matching -p for Docker.

Live verification against the demo project also corrected the in-platform path (avatar menu → Keboola MCP Server; "Users & Settings" is a URL slug, not a UI label), Claude's Customize → Connectors flow, the Cursor button label, Windsurf/VS Code/Make menus, and made both Python snippets actually compile and carry credentials. Added a Claude Code tab — the platform ships a one-line claude mcp add that the page didn't have.

The stub's screenshot is not carried over: it showed a stale /sse Integration URL from a non-demo project. A re-shoot note sits in connect.mdx.

keboola/mcp-server's README links to help.keboola.com/ai/mcp-server/#remote-server-setup, so the hub keeps an anchor-compatible section that routes onward. Alternative: a one-line PR against that README.

Verification

  • npm run build clean; node scripts/audit-phase2.mjs: MISSING IMAGES 0, no MCP-related findings (the 45 broken links and 147 total are the repo's pre-existing baseline).
  • No content lost: 23 marker strings from the old page (from mcp-remote and X-Branch-Id to docs_query) all resolve into the new pages.
  • fact-checker (against keboola/mcp-server): read-only tool table matches TOOLS.md 20/20; the PRDCT-580: merge dev MCP page into help MCP (unit 2) #1050 semantic-layer gap is closed; all five stack URLs and all five Cursor deeplinks verified.
  • guide-tester: live pass on the real platform plus a locally run server.

Open questions

  1. VERIFY(Matyáš) — Project Settings tab set. Does a MAKE tab still exist there, and is avatar → Keboola MCP Server the path you want documented?
  2. The two removals above — confirm the BigQuery credentials path is genuinely gone, or tell me to restore it.
  3. Semantic-layer tools stay documented on the reference page (inherited from PRDCT-580 follow-up: semantic-layer tools on the MCP page #1061) even though our guidance says not to document the semantic layer yet — owner's call.

🤖 Generated with Claude Code

Nikita and others added 8 commits August 4, 2026 01:42
Nikita @claude
docs(mcp): make /ai/mcp-server/ an explanation hub
10f81fd 
Diátaxis split, page 1 of 4: the 564-line mixed page keeps only the
explanation layer — what the server is, what an assistant can do, how
hosting/OAuth/permissions work, dev-branch scoping — plus a section map
and a Next chain. Setup, tool reference, and local execution move to
their own pages.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Nikita @claude
docs(mcp): add the Connect a Client how-to
15d9960 
Per-client setup (Claude, ChatGPT, Cursor, Windsurf, VS Code, Make, any
other client) as synced tabs, plus the programmatic recipes (Messages API
connector, OpenAI Agents SDK, LangChain, CrewAI, own client) behind an
on-page note — same task, no separate developer page.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Nikita @claude
docs(mcp): add the tools and access-control reference
46b2f97 
Tool catalogue by category plus the X-Allowed-Tools / X-Disallowed-Tools /
X-Read-Only-Mode headers, filter order, read-only set, and examples.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Nikita @claude
docs(mcp): add the Run It Yourself how-to
f659c56 
Docker and uv recipes, required env vars, BigQuery credentials, and
pointing a client at a localhost instance.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Nikita @claude
docs(mcp): drop the duplicate Management stub and regroup the nav
4de62ef 
The 18-line management/project/mcp-server stub duplicated the AI section
and pushed users off to it; deleted with a redirect_from onto the hub. Nav
now carries one MCP entry with the three sub-pages in reading order. The
stub screenshot is not carried over: it showed a stale /sse Integration
URL from a non-demo project.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Nikita @claude
docs(mcp): stop the hub lede from repeating its own description
018cd82 
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Nikita @claude
docs(mcp): fact-checker pass — drop obsolete local-run setup, tighten…
ca0da1b 
… claims

From the fact-checker run against keboola/mcp-server:

- self-hosted: remove the GOOGLE_APPLICATION_CREDENTIALS prerequisite and
  the BigQuery credential mount (the variable exists nowhere in the server,
  which routes BigQuery workspace queries through the Query Service since
  AJDA-2801), and stop showing ?storage_token=…&workspace_schema= in the
  localhost URL (config is no longer read from the query string). Both are
  inherited from the pre-split page; evidence recorded inline as VERIFY notes.
- self-hosted: KBC_WORKSPACE_SCHEMA is only needed with a custom Storage
  token; restore the mcp_servers.json filename label.
- tools: note that the offered tool set varies (semantic models, branch,
  read-only token).
- hub: keep a #remote-server-setup anchor — the server README links to it;
  match the source on transports and permissions instead of overstating.
- connect: Project Settings → MCP Server tab (the page has a flat tab strip,
  no Users & Settings level); lede no longer claims every route is a paste.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Nikita @claude
docs(mcp): guide-tester pass — make both how-tos executable
5936c81 
Live-verified against demo project 264 plus a locally run server:

connect:
- say how to find your stack (the connection.<stack> host in your browser)
  and that <YOUR_REGION> stands for the whole host, so 'paste the full URL'
  replaces 'replace the region token with a URL'
- fix the in-platform path: avatar menu → Keboola MCP Server (or Project
  Settings → MCP Server tab); 'Users & Settings' is a URL slug, not a label
- Claude: Customize → Connectors, + → Add custom connector, then Connect
- Cursor: the button is 'Add Keboola MCP server to Cursor'
- add a Claude Code tab (one-line claude mcp add), which the platform ships
  and the page lacked
- Windsurf/VS Code/Make: current menus, live Windsurf doc link, Make's
  Keboola preset; drop the unsupported Copilot-plan requirement
- make both Python snippets actually run (async main + credentials) and say
  what happens without them; note the hosted endpoints enforce OAuth
- dev-branch scoping: say that most desktop clients can't set headers
- prerequisites block; mcp-remote fallback points at the Claude tab

self-hosted:
- document Streamable HTTP mode (--transport streamable-http --host --port,
  and -p for Docker). Without it the page told readers to connect to
  localhost:8000 with no way to get a server listening there.
- credentials go in env/CLI or X-Storage-Token / X-Workspace-Schema headers
- KBC_STORAGE_API_URL: how to build it, and it's connection.*, not mcp.*
- the Docker command's result is a stdio server: let the client run it
- prerequisites; Cursor template placeholders must be edited after install

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@linear-code

linear-code Bot commented Aug 4, 2026

Copy link
Copy Markdown

PRDCT-359

@vercel

vercel Bot commented Aug 4, 2026 •
edited
Loading

Copy link
Copy Markdown

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

Project Deployment Actions Updated (UTC)
connection-docs Ready Ready Preview Aug 4, 2026 1:07pm

Request Review

@Iamfle4ka
Iamfle4ka requested a review from jordanrburger August 4, 2026 11:24
Nikita @claude
docs(mcp): real screenshot of the MCP Server settings tab, captured i…
70244b4 
…n demo 264

Replaces the placeholder note with a live capture (production branch,
current /mcp Integration URL) and records what the live UI confirmed: the
avatar menu carries both Project Settings and Keboola MCP Server, and the
MCP tab has a client tab each for Claude.ai, Claude Desktop, Claude Code,
ChatGPT, Cursor, Make, Windsurf and Other — so the Make tab does exist and
the documented path is right. VERIFY note on that question dropped.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@Iamfle4ka Iamfle4ka mentioned this pull request Aug 11, 2026
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jordanrburger jordanrburger Awaiting requested review from jordanrburger

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

@Iamfle4ka