docs(mcp): document browser login and multi-project scoping - #404
docs(mcp): document browser login and multi-project scoping#404Matovidlo wants to merge 2 commits into
Conversation
Reflects the MCP server's BC auth changes: the login/logout CLI for browser-based sessions, programmatic-token (kbc_at_/kbc_pat_) project selection via get_accessible_projects/set_project_scope, and fixes a stale KBC_API_URL env var name plus a hardcoded read-only tools list that had drifted out of date.
|
@claude review |
There was a problem hiding this comment.
Pull request overview
Updates the Keboola MCP integration documentation to reflect current authentication and project-scoping behavior, replacing stale/duplicated tool listings and correcting environment variable naming.
Changes:
- Replaces the static “read-only tools” list with a reference to the auto-generated
TOOLS.mdinkeboola/mcp-server. - Updates the documented env var and example command to use
KBC_STORAGE_API_URLinstead of the staleKBC_API_URL. - Documents browser-based
login/logoutand the multi-project scoping flow (get_accessible_projects/set_project_scope), includingscope_tokenhandling notes.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| uvx keboola_mcp_server login --api-url https://connection.YOUR_REGION.keboola.com | ||
| ``` | ||
|
|
||
| This saves a stack-wide session to `~/.keboola/mcp/credentials.json` (readable only by you). Afterwards, start the server with only `KBC_STORAGE_API_URL` set — no token required. Which project(s) to work on is then chosen from within the conversation itself (see [Working Across Multiple Projects](#working-across-multiple-projects) below), not at login time. |
| 2. Ask the user whether to operate across all of them or a chosen subset. | ||
| 3. Call `set_project_scope` with the selected `project_ids` (and optionally `read_only=true` to mint a read-only scoped token). | ||
|
|
||
| `set_project_scope` mints a scoped access token narrowed to the chosen projects. Read-only tools then run against every scoped project in a single call; write operations always target the first scoped project only — re-scope first to write elsewhere. Because the server does not keep session state between calls on the stateless HTTP transport, `set_project_scope` and `get_accessible_projects` return a `scope_token` that must be resent as the `scope_token` argument on every subsequent tool call in the conversation (OAuth-authenticated sessions are the exception — the server persists the scope server-side for those, so no resending is needed). |
KBC_STORAGE_TOKEN still works but is being phased out in favor of the browser login flow; flags this at the point of use (uv, Docker) and in the login section itself.
| Instead of setting a static `KBC_STORAGE_TOKEN`, you can sign in once with your browser; the server stores the session and refreshes it automatically: | ||
|
|
||
| ```bash | ||
| uvx keboola_mcp_server login --api-url https://connection.YOUR_REGION.keboola.com |
There was a problem hiding this comment.
This could be refered via env variable as above.
keboola-pr-reviewer-bot
left a comment
keboola-pr-reviewer-bot
left a comment
There was a problem hiding this comment.
Verdict: needs_human (risk 2/5) · profile docs
Needs human: substantive new product-behaviour claims and a cross-repo link that can't be verified from this diff.
Concerns:
integrate/mcp.md: New product-behaviour claims (login flow, scope_token, token prefixes) unverifiable from diffintegrate/mcp.md: Cross-repo link to keboola/mcp-server TOOLS.md not verifiableintegrate/mcp.md: Env-var rename KBC_API_URL to KBC_STORAGE_API_URL unconfirmed against source
Suggested reviewers: @keboola/docs
|
Can you move this to the help docs? We're killing dev docs. |
|
@jordanrburger it should be moved at once I think. Do we have some ETA when its happening? |
|
We're moving it in pieces. MCP was moved already. |
|
Closing this — Jordan confirmed |
Jira issue(s): none (no PROOF ticket — small factual doc correction/addition)
Changes:
login/logoutCLI as the recommended way to authenticate a local server, and the token-based fallback (KBC_STORAGE_TOKEN+KBC_PROJECT_ID/X-KBC-ProjectId) for containers/CI using stack-wide programmatic tokens (kbc_at_/kbc_pat_).get_accessible_projectsandset_project_scope, including thescope_tokenresend requirement on the stateless HTTP transport.KBC_API_URL→KBC_STORAGE_API_URL) that no longer matched the server's actual config.TOOLS.mdin the mcp-server repo.Source: reviewed the current
keboola/mcp-serversource (config.py,scope.py,tools/project.py,clients/auth_bridge.py) and its README, which already reflects these changes, to make sureintegrate/mcp.mdhere is accurate rather than just copying prose.