Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Matovidlo wants to merge 2 commits into from
Closed

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

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5753037
docs(mcp): document browser login and multi-project scoping
Matovidlo Aug 3, 2026
3d9fc05
docs(mcp): add deprecation notice for static storage token
Matovidlo Aug 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 44 additions & 17 deletions integrate/mcp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,19 +126,7 @@ Empty headers are treated as no restriction/exclusion (backward compatible behav

### Read-Only Tools

The following 15 tools are classified as read-only (they do not modify data):

| Category | Tools |
|----------|-------|
| Components | `get_configs`, `get_components`, `get_config_examples` |
| Flows | `get_flows`, `get_flow_examples`, `get_flow_schema` |
| Storage | `get_buckets`, `get_tables` |
| SQL | `query_data` |
| Data Apps | `get_data_apps` |
| Jobs | `get_jobs` |
| Search | `search`, `find_component_id` |
| Project | `get_project_info` |
| Documentation | `docs_query` |
Read-only tools are those annotated with `readOnlyHint=True` — they only retrieve information and never modify your Keboola project. The set of read-only tools changes as tools are added, so rather than duplicating the list here, see the auto-generated [TOOLS.md](https://github.com/keboola/mcp-server/blob/main/TOOLS.md) file in the repository (look for `**Annotations**: read-only` under each tool).

### Use Cases

Expand Down Expand Up @@ -171,6 +159,10 @@ For a consistent and isolated environment, running the Keboola MCP Server via [D

Before proceeding, ensure you have Docker installed on your system. You can find installation guides on the [official Docker website](https://docs.docker.com/engine/install/).

<div class="clearfix"></div><div class="alert alert-warning">
<b>Deprecation notice:</b> The <code>KBC_STORAGE_TOKEN</code> examples below still work, but static-token configuration is deprecated — see <a href="#authenticating-without-a-static-storage-token-browser-login">Authenticating Without a Static Storage Token</a>.
</div>

1. **Pull the latest image:**
```bash
docker pull keboola/mcp-server:latest
Expand Down Expand Up @@ -242,9 +234,9 @@ The primary way to run the server locally is by using `uv` or `uvx` to execute t

1. **Set up environment variables:**
Before running the server, you need to configure the following environment variables:
* `KBC_STORAGE_TOKEN`: Your Keboola Storage API token.
* `KBC_STORAGE_TOKEN`: Your Keboola Storage API token. **Deprecated** — see [Authenticating Without a Static Storage Token](#authenticating-without-a-static-storage-token-browser-login) below for the recommended browser login flow.
* `KBC_WORKSPACE_SCHEMA`: Your Keboola project's workspace schema (for SQL queries).
* `KBC_API_URL`: Your Keboola instance API URL (e.g., `https://connection.keboola.com` or `https://connection.YOUR_REGION.keboola.com`).
* `KBC_STORAGE_API_URL`: Your Keboola instance API URL (e.g., `https://connection.keboola.com` or `https://connection.YOUR_REGION.keboola.com`).

Refer to the [Keboola Tokens](https://help.keboola.com/management/project/tokens/) and [Keboola workspace manipulation](https://help.keboola.com/tutorial/manipulate/workspace/) for detailed instructions on obtaining these values.

Expand All @@ -257,10 +249,45 @@ The primary way to run the server locally is by using `uv` or `uvx` to execute t
2. **Run the server:**

```bash
uvx keboola_mcp_server --api-url $KBC_API_URL
uvx keboola_mcp_server --api-url $KBC_STORAGE_API_URL
```

The `KBC_API_URL` was set as an environment variable but can also be provided manually. The command starts the server communicating via `stdio`. To run the server in `Streamable HTTP` mode (listening on a network host/port such as `localhost:8000`), pass the appropriate flags to `keboola_mcp_server`. For day-to-day use with clients like Claude or Cursor you usually do not need to run this command manually, as they handle the server lifecycle.
The `KBC_STORAGE_API_URL` was set as an environment variable but can also be provided manually. The command starts the server communicating via `stdio`. To run the server in `Streamable HTTP` mode (listening on a network host/port such as `localhost:8000`), pass the appropriate flags to `keboola_mcp_server`. For day-to-day use with clients like Claude or Cursor you usually do not need to run this command manually, as they handle the server lifecycle.

### Authenticating Without a Static Storage Token (Browser Login)

<div class="clearfix"></div><div class="alert alert-warning">
<b>Deprecation notice:</b> Configuring the MCP server with a static <code>KBC_STORAGE_TOKEN</code> is deprecated in favor of the browser login flow below. It still works today — there is a deprecation period while existing setups migrate — but support for it will be removed in a future release. Please switch to <code>login</code>/<code>logout</code> now if you're setting up a new integration.
</div>

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

@Matovidlo Matovidlo Aug 3, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This could be refered via env variable as above.

```

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.

| Command | What it does |
|---------|--------------|
| `login --api-url <url>` | Sign in to a stack |
| `login --force` | Sign in again / switch account |
| `login --show-token` | Print the current session token (debugging) |
| `logout [--api-url <url>] [--all]` | Remove the stored session for a stack (or all stacks) |

Starting the server over `stdio` in an interactive terminal with no stored session runs this browser login automatically. MCP clients (Claude, Cursor, ...) launch the server in the background where a browser can't open, so run `login` once yourself first.

For containers or CI where a browser login isn't possible, supply a Keboola [access or personal access token](https://help.keboola.com/management/project/tokens/) directly via `KBC_STORAGE_TOKEN` (or the `X-StorageAPI-Token` header), together with `KBC_PROJECT_ID` (or the `X-KBC-ProjectId` header) to select the project. These stack-wide programmatic tokens are prefixed `kbc_at_` (access token) or `kbc_pat_` (personal access token); a legacy project-bound Storage token does not need `KBC_PROJECT_ID`, since the project is already encoded in the token itself.

### Working Across Multiple Projects

A stack-wide programmatic token (`kbc_at_`/`kbc_pat_`, obtained via browser login or issued directly) can access more than one Keboola project. In that case the assistant should:

1. Call `get_accessible_projects` to list every project the token can reach.
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).

### Connecting a Client to a Localhost Instance

Expand Down
Loading