PRDCT-580: merge dev MCP page into help MCP (unit 2) by Iamfle4ka · Pull Request #1050 · keboola/connection-docs

Iamfle4ka · 2026-07-28T13:20:42Z

What & why

Unit 2 of the 2026-07-27 nav pivot (unit 1 = Extending Keboola, #1046). Jordan's model per unit: merge the dev page into its help peer, then delete the dev page — MCP was his worked example ("we can't have two pages called MCP Server; combine it and remove it from developers").

The dev page (developers.keboola.com/integrate/mcp) and the help page (/ai/mcp-server) were duplicates: help = UI-first, dev = the developer layer. The help page deferred to dev via 3 external links — this PR closes them by folding dev's unique content in. Self-contained off main, independent of the #1027 stack.

Supersedes #1049 (auto-closed by a branch rename during Linear-id cleanup — identical content; this PR is on the correctly-named PRDCT-580-mcp-merge branch).

Folded in (net-new to help)

Running the MCP Server Locally — Docker (Snowflake + BigQuery incl. creds volume), uv/uvx, connecting a local client, local Cursor config
Programmatic Integration — Claude Messages API connector (Beta), OpenAI Agents SDK, LangChain, Crew AI, build-your-own-client
MCP Server Capabilities matrix
Restricting Tool Access expanded to the full authorization spec — header examples, filter precedence, read-only tool table, worked/combined examples
On-page :::note dev signal before the developer sections (the pivot's page-level "this part is for developers", not a nav flag)
redirect_from: /integrate/mcp/ (feeds the PRDCT-572 dev→help redirect contract)

Kept help's UI-friendly client walkthroughs; did not duplicate the overlapping remote-setup / mcp-remote / Cursor-deeplink sections.

Fact-check

Ran the fact-checker against the dev source + the keboola/mcp-server repo. The merge itself was drift-free. It surfaced 3 bugs inherited from the dev docs, fixed here:

Fix	Was	Now
OpenAI Agents SDK import (would `ModuleNotFoundError`)	`openai_agents_python`	`agents` / `agents.mcp`
Local server env var	`KBC_API_URL`	`KBC_STORAGE_API_URL` (server's actual name)
Read-only tool list	hard "15 tools" (stale)	softened + pointer to repo `TOOLS.md`

Worth an upstream fix in keboola/developers-docs too (pre-existing there).

Owner-verify (Jordan, as offered on the 07-27 call) — platform facts carried verbatim from the dev docs, not confirmable from public sources:

BigQuery Docker creds mount path / GOOGLE_APPLICATION_CREDENTIALS handling against the current image
Capabilities matrix rows Prompts/Resources/Sampling/Roots
SSE deprecation date 01.04.2026 (pre-existing help content)

Verification

npm run build clean — 256 pages.
node scripts/audit-phase2.mjs: 0 missing images, 0 new broken internal links; the 3 formerly-external developers.keboola.com/integrate/mcp deferrals are now in-page anchors.

Follow-up

Delete-from-dev: remove integrate/mcp.md from keboola/developers-docs (redirect-stub) — opened after this merges.

🤖 Generated with Claude Code

Unit 2 of the 2026-07-27 nav pivot: fold the developer-docs MCP page (developers.keboola.com/integrate/mcp) into its help peer at /ai/mcp-server, then the dev page gets deleted in a follow-up PR. The two pages were duplicates — help was UI-first, dev was the developer layer. Help deferred to dev via 3 external links; those are now closed by folding dev's unique content in: - New "Running the MCP Server Locally" — Docker (Snowflake + BigQuery) and uv/uvx, env vars, connecting a local client, local Cursor config - New "Programmatic Integration" — Claude Messages API connector, OpenAI Agents SDK, LangChain, Crew AI, build-your-own-client - New "MCP Server Capabilities" matrix - Expanded "Restricting Tool Access" with the full authorization spec: header examples, filter precedence, read-only tool table, worked examples - On-page dev signal (`:::note`) before the developer sections — the pivot's page-level "this part is for developers" instead of a nav flag - redirect_from /integrate/mcp/ (feeds the dev->help redirect contract) - Jekyll HTML callouts -> Starlight admonitions; help.keboola.com absolute links -> internal; kept help's UI walkthroughs (no duplicate remote setup) Fact-checked against devdocs source + keboola/mcp-server repo: merge itself was drift-free; fixed 3 inherited dev-docs bugs in the process — - OpenAI Agents SDK import (openai_agents_python -> agents) — would crash - env var KBC_API_URL -> KBC_STORAGE_API_URL (server's actual name) - dropped the stale hard "15 tools" count, pointed at the repo TOOLS.md Build clean (256 pages); audit 0 new broken links / 0 missing images; the 3 formerly-external deferrals are now in-page anchors. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

linear-code · 2026-07-28T13:20:46Z

PRDCT-580

vercel · 2026-07-28T13:20:48Z

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

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

The status-emoji table styling used `display: inline-block` on the <td>, which pulls the cell out of the table grid — it collapsed to a content-width pill while the column border/background still drew at grid width, producing a misaligned pill + stray vertical line (visible on the new MCP "Server Capabilities" matrix, the first live status table). Drop the pill styling (inline-block / border-radius / padding / margin); keep the semantic green/red/orange tint and center the emoji. The cell stays a normal table-cell (inherits the general td padding + border), so the grid stays aligned. Verified in a production build (astro build && preview). No other page currently uses status-emoji tables, so blast radius is nil. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

jordanrburger · 2026-07-28T16:09:22Z

This section can be fully removed:
https://connection-docs-git-prdct-580-mcp-merge-keboola-engineering.vercel.app/ai/mcp-server/#mcp-server-capabilities

jordanrburger · 2026-07-28T16:10:38Z

I think the Claude messages API stuff is deprecated: https://connection-docs-git-prdct-580-mcp-merge-keboola-engineering.vercel.app/ai/mcp-server/#claude-messages-api-with-mcp-connector-beta

Look into what they have these days and update accordingly.

Addresses Jordan's review comments + a full line-by-line fact-check against keboola/mcp-server + the Anthropic MCP-connector docs. Jordan's asks: - Remove the SSE deprecation banner — verified stale: the server exposes only stdio / streamable-http / http-compat (no SSE). Also dropped the "deprecated SSE" mention in the intro. - Remove the "MCP Server Capabilities" section — done; fixed the now-dead #mcp-server-capabilities anchor in "Building your own MCP client". - Claude Messages API connector: NOT deprecated — it's current, still beta (mcp-client-2025-11-20; only the old -2025-04-04 is deprecated). Kept the section, updated the links to platform.claude.com. Fact-check fixes: - CRITICAL: OpenAI Agents SDK snippet used agent.run() (no such method) → from agents import Agent, Runner + Runner.run(agent, ...). - Read-only tool table: added run_sync_action (Components) per TOOLS.md. - Available Tools: added Flows and Data Apps categories. - Windsurf: dropped the phantom "Plugin store"/"Option 1" (only manual config exists). - LangChain: fixed the malformed deployed-instance URL to the /mcp form. - VS Code: dropped the unverifiable "128 tools per request" figure. Build clean (256 pp); audit 0 missing images, no new broken links. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Full vendor-by-vendor deprecation check + mined keboola/mcp-server for Keboola-relevant gaps. Currency fixes (each verified against the vendor's current docs): - Claude Desktop: "Integrations" → "Connectors"; fixed plan/owner gating (individual Free/Pro/Max add their own, Free = 1 connector; only Team/ Enterprise org-wide needs an Owner); demoted mcp-remote from "free-tier method" to a fallback for clients without native remote/OAuth. - ChatGPT: settings path → Connectors → Advanced settings → Developer mode; added Business/Enterprise; softened the unverifiable in-chat click sequence. - VS Code: replaced the npx mcp-remote config with native remote MCP (`"type": "http"` + `"url"`). - LangChain: replaced the "no built-in connector / hand-map tools" text with the official `langchain-mcp-adapters` MultiServerMCPClient pattern. - CrewAI: point to native `MCPServerAdapter` (crewai-tools[mcp]). - MAKE: reworded to "enter the server URL" (the documented flow) instead of a non-existent "select Keboola" dropdown. - Claude Messages API connector: confirmed CURRENT (not deprecated) — added the current beta header `mcp-client-2025-11-20` + noted the old one is deprecated. Keboola-value additions (from keboola/mcp-server README/TOOLS.md): - New "Development Branches" section — X-Branch-Id header (remote) / KBC_BRANCH_ID env var (local) to scope an agent off production. - Available Tools: Data Apps now create/deploy/manage; added Search & Discovery, Project & OAuth; Flows note conditional flows. Guardrail: semantic-layer tools intentionally omitted. Owner-verify (in PR): ChatGPT exact in-chat UI, mcp-server release dates. Build clean (256 pp), audit 0 missing images. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Iamfle4ka · 2026-07-29T23:59:15Z

@jordanrburger both points handled — and the second one turned into a full vendor sweep.

1. "MCP Server Capabilities" — removed (your comment)

Section deleted in 6ea52348, and the now-dead #mcp-server-capabilities anchor it left behind is cleaned up too. While in there I also dropped the stale SSE deprecation banner: keboola/mcp-server exposes only stdio / streamable-http / http-compat, so there is no SSE transport left to deprecate.

2. Claude Messages API — checked, and it is NOT deprecated (your comment)

The MCP connector in the Messages API is current. What is deprecated is only the older beta header mcp-client-2025-04-04. So I kept the section and updated it to the current header mcp-client-2025-11-20, with links moved to platform.claude.com. If you would rather not document the API path at all, say so and I will cut it — but as written it is accurate today.

Your second point sent me through every vendor on the page (893af8d6), each verified against that vendor's current docs:

Claude Desktop — "Integrations" → "Connectors"; plan/owner gating fixed (individual Free/Pro/Max add their own, Free = 1 connector; only Team/Enterprise org-wide needs an Owner); mcp-remote demoted from "free-tier method" to a fallback for clients without native remote/OAuth
ChatGPT — settings path is Connectors → Advanced settings → Developer mode; Business/Enterprise added
VS Code — native remote MCP ("type": "http" + "url") instead of the npx mcp-remote config
LangChain — the official langchain-mcp-adapters / MultiServerMCPClient pattern instead of "no built-in connector, hand-map the tools"
CrewAI — native MCPServerAdapter (crewai-tools[mcp])
MAKE — "enter the server URL" (the documented flow); the "select Keboola" dropdown we described does not exist

Also caught by fact-checking the page against keboola/mcp-server (6ea52348): the OpenAI Agents SDK snippet called a non-existent agent.run() → Runner.run(agent, …) (it would have crashed for anyone who copied it); run_sync_action added to the read-only tool table; Flows and Data Apps added to Available Tools; a phantom Windsurf "Plugin store / Option 1" removed; a malformed LangChain URL fixed; an unverifiable "128 tools per request" VS Code figure dropped.

Two things added from the repo while I was in there: a Development Branches section (X-Branch-Id header for remote, KBC_BRANCH_ID env var for local — so an agent can be scoped off production), and the fuller tool inventory (Data Apps now create/deploy/manage, plus Search & Discovery and Project & OAuth; Flows notes conditional flows). Semantic-layer tools deliberately left out per the guardrail.

Build clean (256 pages), audit 0 missing images and no new broken links. Re-requesting your review. Still owner-verify and flagged in the PR body: the exact ChatGPT in-chat click path, and the mcp-server release dates.

The MCP content was merged into help.keboola.com/ai/mcp-server/ in keboola/connection-docs#1050 (merged 2026-08-03). This is the second half of that unit: the dev page stops serving its own copy and redirects to the canonical one, so the two cannot drift apart. Uses jekyll-redirect-from's redirect_to, already a dependency, so the /integrate/mcp/ URL keeps working for existing inbound links. Also drops the now-dead nav entry. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

vercel Bot deployed to Preview July 28, 2026 13:21 View deployment

Iamfle4ka added the dev-docs-migration developers.keboola.com → help.keboola.com migration label Jul 28, 2026

vercel Bot deployed to Preview July 28, 2026 14:42 View deployment

vercel Bot deployed to Preview July 29, 2026 15:31 View deployment

vercel Bot deployed to Preview July 29, 2026 22:58 View deployment

Iamfle4ka requested a review from jordanrburger July 29, 2026 23:59

jordanrburger approved these changes Jul 30, 2026

View reviewed changes

This was referenced Aug 3, 2026

docs(mcp): document browser login and multi-project scoping keboola/developers-docs#404

Closed

docs(mcp): update project selection and storage-token deprecation #1059

Closed

PRDCT-580 followup: deferred project selection + storage-token deprecation #1060

Merged

Merge branch 'main' into PRDCT-580-mcp-merge

3a2c34a

vercel Bot deployed to Preview August 3, 2026 12:07 View deployment

Iamfle4ka merged commit c922a3f into main Aug 3, 2026
3 checks passed

Iamfle4ka deleted the PRDCT-580-mcp-merge branch August 3, 2026 12:09

This was referenced Aug 3, 2026

PRDCT-580 follow-up: semantic-layer tools on the MCP page #1061

Merged

docs(mcp): retire the dev MCP page, redirect to help (PRDCT-580) keboola/developers-docs#405

Merged

This was referenced Aug 3, 2026

PRDCT-583: redirect /integrate/mcp/ to help (dev-side delete for #1050) keboola/developers-docs#407

Closed

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

Draft

Navigation Menu

PRDCT-580: merge dev MCP page into help MCP (unit 2) - #1050

PRDCT-580: merge dev MCP page into help MCP (unit 2)#1050
Iamfle4ka merged 5 commits into
mainfrom
PRDCT-580-mcp-merge

Iamfle4ka commented Jul 28, 2026

Uh oh!

linear-code Bot commented Jul 28, 2026

Uh oh!

vercel Bot commented Jul 28, 2026 •

edited

Loading

Uh oh!

jordanrburger commented Jul 28, 2026

Uh oh!

jordanrburger commented Jul 28, 2026

Uh oh!

Iamfle4ka commented Jul 29, 2026

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Iamfle4ka commented Jul 28, 2026

What & why

Folded in (net-new to help)

Fact-check

Verification

Follow-up

Uh oh!

linear-code Bot commented Jul 28, 2026

Uh oh!

vercel Bot commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jordanrburger commented Jul 28, 2026

Uh oh!

jordanrburger commented Jul 28, 2026

Uh oh!

Iamfle4ka commented Jul 29, 2026

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vercel Bot commented Jul 28, 2026 •

edited

Loading