From fb6e0c58d3c70343e5ef49c86facd9a65aebf992 Mon Sep 17 00:00:00 2001 From: Nikita Date: Tue, 28 Jul 2026 14:49:25 +0200 Subject: [PATCH] PRDCT-544: merge dev MCP page into help MCP (unit 2) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- src/content/docs/ai/mcp-server/index.md | 290 +++++++++++++++++++++++- 1 file changed, 280 insertions(+), 10 deletions(-) diff --git a/src/content/docs/ai/mcp-server/index.md b/src/content/docs/ai/mcp-server/index.md index 447dd286c..61ff66ef1 100644 --- a/src/content/docs/ai/mcp-server/index.md +++ b/src/content/docs/ai/mcp-server/index.md @@ -3,6 +3,7 @@ title: Keboola Model Context Protocol (MCP) Server slug: 'ai/mcp-server' redirect_from: - /external-integrations/mcp-server/ + - /integrate/mcp/ --- :::caution @@ -61,7 +62,9 @@ In case your AI assistant supports remote connection, you can connect to Keboola 2. Copy the server URL and paste it into your AI assistant's settings. 3. Once you save the settings and refresh your AI assistant, you will be prompted to authenticate with your Keboola account and select the project you want to connect to. -For other options of local deployments see the [Developers Documentation](https://developers.keboola.com/integrate/mcp/#running-keboola-mcp-server-locally-using-uv-command). +:::note +When using the remote server with OAuth, you get the permissions that match your role in Keboola. If you wish to control permissions more granularly, run the server locally and specify your own **Storage Token** and **Workspace Schema** — see [Running the MCP Server Locally](#running-the-mcp-server-locally). +::: ### Using with Claude Desktop @@ -81,7 +84,7 @@ These steps must be done by a Claude organization owner or primary owner, or on If you don't have a paid version you can still use the [`mcp-remote`](https://github.com/geelen/mcp-remote) adapter to connect Claude Desktop to Keboola's MCP Server. -> NOTE: This method requires you to have Node.js installed on your computer. For more information refer to the [Developers Documentation](https://developers.keboola.com/integrate/mcp) +> NOTE: This method requires you to have Node.js installed on your computer. 1. Open the Claude menu on your computer and select **"Settings…"** 2. Click on **"Developer"** in the left-hand bar of the Settings pane, and then click on **"Edit Config"** @@ -274,19 +277,286 @@ When using the remote MCP server, you may want to limit which tools are availabl - **Compliance and Security**: Enforcing data governance policies by restricting write operations - **Customer-Specific Access**: Creating tailored access profiles for different use cases -The MCP server supports three HTTP headers for tool authorization: +When connecting via the Streamable HTTP transport, you control which tools are available to clients using HTTP headers. + +:::note +Tool authorization headers only apply to HTTP-based transports. They are not available when using the `stdio` transport for local execution. +::: + +### Authorization Headers + +The following HTTP headers control tool access: -| Header | Purpose | -|--------|---------| -| `X-Allowed-Tools` | Only allow specific tools (comma-separated list) | -| `X-Disallowed-Tools` | Block specific tools (comma-separated list) | -| `X-Read-Only-Mode` | Restrict to read-only tools only (`true`/`1`/`yes`) | +| Header | Description | Example Value | +|--------|-------------|---------------| +| `X-Allowed-Tools` | Comma-separated list of tool names to allow. Only these tools will be available. | `get_configs,get_buckets,query_data` | +| `X-Disallowed-Tools` | Comma-separated list of tool names to exclude. These tools will be removed from the available set. | `create_config,run_job` | +| `X-Read-Only-Mode` | When set to `true`, `1`, or `yes`, restricts access to read-only tools only. | `true` | These headers are set by the client (e.g., your AI agent integration or custom MCP client) when making HTTP requests to the MCP server. Refer to your MCP client's documentation for how to configure custom HTTP headers. -For example, setting `X-Read-Only-Mode: true` allows agents to query and explore data but prevents them from creating or modifying configurations. +### Filter Behavior + +When multiple headers are present, filters are applied in the following order: + +1. **Allowed tools filter**: If `X-Allowed-Tools` is specified, only those tools are initially available. +2. **Read-only intersection**: If `X-Read-Only-Mode` is enabled, the available tools are intersected with the read-only tools set. +3. **Disallowed exclusion**: Tools listed in `X-Disallowed-Tools` are removed from the final set. + +Empty headers are treated as no restriction/exclusion (backward compatible behavior). + +### Read-Only Tools + +The following tools are classified as read-only (they do not modify data). The live set may grow over time — see [`TOOLS.md`](https://github.com/keboola/mcp-server/blob/main/TOOLS.md) in the server repo for the current annotations: + +| 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` | + +### Examples + +**AI Agent Restrictions**: When integrating AI agents (like Devin, Cursor, or custom agents) with your Keboola project, you may want to limit their capabilities. For example, allowing an agent to query and explore data but preventing it from creating or modifying configurations: + +``` +X-Read-Only-Mode: true +``` + +**Compliance and Security**: For environments with strict data governance requirements, you can create customer-specific access profiles. For example, allowing only specific tools while explicitly blocking others: + +``` +X-Allowed-Tools: get_buckets,get_tables,query_data,search +X-Disallowed-Tools: run_job +``` + +**Combined Restrictions**: You can combine all three headers for fine-grained control. For example, to allow only a subset of read-only tools: + +``` +X-Allowed-Tools: get_configs,get_buckets,get_tables,query_data,create_config +X-Read-Only-Mode: true +X-Disallowed-Tools: query_data +``` + +This configuration would result in only `get_configs`, `get_buckets`, and `get_tables` being available (the intersection of allowed and read-only, minus the disallowed). + +:::note[The rest of this page is for developers] +The sections below cover running the server locally and integrating it programmatically. If you just want to connect an AI client, you're already done above — skip ahead, or hand these to your AI agent to set up for you. +::: + +## MCP Server Capabilities + +The Keboola MCP Server supports several core concepts of the Model Context Protocol. Here's a summary: + +| Concept | Supported | Notes | +|-------------|-----------|--------------------------------------------------------------------------------------------------------| +| Transports | ✅ | Supports `stdio` and `Streamable HTTP` (recommended) for client communication. | +| Prompts | ✅ | Processes natural language prompts from MCP clients to interact with Keboola. | +| Tools | ✅ | Provides a rich set of tools for storage operations, component management, SQL execution, job control. | +| Resources | ❌ | Exposing Keboola project entities (data, configurations, etc.) as formal MCP Resources is not currently supported. | +| Sampling | ❌ | Advanced sampling techniques are not explicitly supported by the server itself. | +| Roots | ❌ | The concept of 'Roots' as defined in general MCP is not a specific feature of the Keboola MCP server. | + +## Running the MCP Server Locally + +While MCP clients like Cursor or Claude typically manage the MCP server automatically, you might want to run the Keboola MCP Server locally for development, testing, or when using a custom client. You can run it via Docker or via the `uv`/`uvx` command. + +### Using Docker (recommended) + +For a consistent and isolated environment, running the Keboola MCP Server via [Docker](https://docker.com/get-started/) is often the recommended approach for local execution, especially if you don't want to manage Python environments directly or are integrating with clients that can manage Docker containers. + +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/). + +1. **Pull the latest image:** + ```bash + docker pull keboola/mcp-server:latest + ``` +2. **Run the Docker container:** + + * **For Snowflake users:** + ```bash + docker run -it --rm \ + -e KBC_STORAGE_TOKEN="YOUR_KEBOOLA_STORAGE_TOKEN" \ + -e KBC_WORKSPACE_SCHEMA="YOUR_WORKSPACE_SCHEMA" \ + keboola/mcp-server:latest \ + --api-url https://connection.YOUR_REGION.keboola.com + ``` + Replace `YOUR_KEBOOLA_STORAGE_TOKEN`, `YOUR_WORKSPACE_SCHEMA`, and `https://connection.YOUR_REGION.keboola.com` with your actual values. + + * **For BigQuery users (requires volume mount for credentials):** + ```bash + # Ensure your Google Cloud credentials JSON file is accessible + docker run -it --rm \ + -e KBC_STORAGE_TOKEN="YOUR_KEBOOLA_STORAGE_TOKEN" \ + -e KBC_WORKSPACE_SCHEMA="YOUR_WORKSPACE_SCHEMA" \ + -e GOOGLE_APPLICATION_CREDENTIALS="/creds/credentials.json" \ + -v /local/path/to/your/credentials.json:/creds/credentials.json \ + keboola/mcp-server:latest \ + --api-url https://connection.YOUR_REGION.keboola.com + ``` + Replace placeholders and ensure `/local/path/to/your/credentials.json` points to your actual credentials file on your host machine. + + The `--rm` flag ensures the container is removed when it stops. The server inside Docker will typically listen on `stdio` by default, which is suitable for clients that can invoke and manage Docker commands. + +**Example: Configuring Cursor IDE to use Docker for Keboola MCP Server:** + +If your MCP client (like Cursor) supports defining a Docker command for an MCP server, the configuration might look like this: + +```json +{ + "mcpServers": { + "keboola": { + "command": "docker", + "args": [ + "run", + "-it", + "--rm", + "-e", "KBC_STORAGE_TOKEN", + "-e", "KBC_WORKSPACE_SCHEMA", + "keboola/mcp-server:latest", + "--api-url", "https://connection.YOUR_REGION.keboola.com" + ], + "env": { + "KBC_STORAGE_TOKEN": "YOUR_KEBOOLA_STORAGE_TOKEN", + "KBC_WORKSPACE_SCHEMA": "YOUR_WORKSPACE_SCHEMA" + } + } + } +} +``` + +**Note:** +* Ensure Docker is running on your system. +* Replace placeholders like `YOUR_KEBOOLA_STORAGE_TOKEN`, `YOUR_WORKSPACE_SCHEMA`, and the Keboola API URL. +* The client (Cursor) passes the `KBC_STORAGE_TOKEN` and `KBC_WORKSPACE_SCHEMA` from its `env` block to the `docker run` command through the `-e` flags. The `--api-url` is passed directly as an argument to the `keboola/mcp-server` entrypoint. + +### Using the uv command + +The primary way to run the server locally without Docker is by using `uv` or `uvx` to execute the `keboola_mcp_server` package. More information about the server is available in its [Keboola MCP Server GitHub repository](https://github.com/keboola/mcp-server). Make sure you have Python 3.10+ and `uv` installed. + +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_WORKSPACE_SCHEMA`: Your Keboola project's workspace schema (for SQL queries). + * `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](/management/project/tokens/) and [Keboola workspace manipulation](/tutorial/manipulate/workspace/) for detailed instructions on obtaining these values. + + **1.1. Additional Setup for BigQuery Users** + If your Keboola project uses BigQuery as its backend, you will also need to set up the `GOOGLE_APPLICATION_CREDENTIALS` environment variable. This variable should point to the JSON file containing your Google Cloud service account key that has the necessary permissions to access your BigQuery data. + + Example: + `GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"` + +2. **Run the server:** + +```bash +uvx keboola_mcp_server --api-url $KBC_STORAGE_API_URL +``` + +The `KBC_STORAGE_API_URL` was set as an environment variable but can also be provided manually via the `--api-url` flag. 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. + +### Connecting a client to a localhost instance + +When you run the Keboola MCP Server manually, it will typically listen on `stdio` or on a specific HTTP port if configured for `Streamable HTTP`. + +* **`stdio`-based clients:** Configure the client application to launch the local `keboola_mcp_server` executable and communicate over standard input/output. +* **`Streamable HTTP`-based clients:** If you start the server in HTTP mode, your client should connect to the specified host and port (e.g., `http://localhost:8000/mcp?storage_token=XXX&workspace_schema=YYY`). + +**Example: connecting Cursor IDE to a local `uvx` instance** + +If you are running the Keboola MCP Server locally using `uvx`, you can configure Cursor IDE to connect to this local instance. This is useful for development or testing with a custom server build. + +1. Open Cursor settings. +2. Navigate to the MCP section within settings. +3. Add or configure your Keboola project. Provide your `KBC_STORAGE_TOKEN`, `KBC_WORKSPACE_SCHEMA` and the API URL. + +Example `mcp_servers.json` snippet: + +```json +{ + "mcpServers": { + "keboola": { + "command": "uvx", + "args": [ + "keboola_mcp_server", + "--api-url", "https://connection.YOUR_REGION.keboola.com" + ], + "env": { + "KBC_STORAGE_TOKEN": "your_keboola_storage_token", + "KBC_WORKSPACE_SCHEMA": "your_workspace_schema" + } + } + } +} +``` + +> You can use this link to get the above configuration template into your Cursor: [![Install MCP Server using uvx](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=keboola&config=eyJjb21tYW5kIjoidXZ4IGtlYm9vbGFfbWNwX3NlcnZlciAtLWFwaS11cmwgaHR0cHM6Ly9jb25uZWN0aW9uLllPVVJfUkVHSU9OLmtlYm9vbGEuY29tIiwiZW52Ijp7IktCQ19TVE9SQUdFX1RPS0VOIjoieW91cl9rZWJvb2xhX3N0b3JhZ2VfdG9rZW4iLCJLQkNfV09SS1NQQUNFX1NDSEVNQSI6InlvdXJfd29ya3NwYWNlX3NjaGVtYSJ9fQ%3D%3D) + +## Programmatic Integration + +Beyond ready-made clients, you can integrate the Keboola MCP Server directly into your own code and AI agent frameworks. This unlocks fully automated data workflows driven by natural-language instructions. + +### Claude Messages API with MCP Connector (Beta) + +Anthropic offers a beta feature, the [MCP connector](https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector), which enables you to connect to remote MCP servers (such as the Keboola MCP Server) directly through Claude's Messages API. This method bypasses the need for a separate, standalone MCP client if you are already using the Claude Messages API. + +**Key features of this integration:** + +* **Direct API Calls**: You configure connections to MCP servers by including the `mcp_servers` parameter in your API requests to Claude. +* **Tool Calling**: The primary MCP functionality currently supported through this connector is tool usage. +* **Accessibility**: The target MCP server needs to be publicly accessible over HTTP. + +This approach can simplify your architecture if you're building applications that programmatically interact with Claude and need to leverage MCP-enabled tools without managing an additional client layer. + +For complete details, API examples, and configuration options, please consult the [official Anthropic MCP connector documentation](https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector). + +### OpenAI Agents SDK (Python) + +The [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/mcp/) ships with first-class MCP support. Simply start the Keboola MCP Server (locally via `uvx` or remotely over Streamable HTTP) and register it with the SDK: + +```python +from agents import Agent +from agents.mcp import MCPServerStdio + +async with MCPServerStdio( + params={"command": "uvx", "args": ["keboola_mcp_server"]} +) as mcp: + agent = Agent( + name="Assistant", + instructions="Use the Keboola tools to achieve the task", + mcp_servers=[mcp], + ) + await agent.run("Load yesterday's CSV into Snowflake") +``` + +The SDK automatically calls `list_tools()` on the server, making every Keboola operation available to the model. + +### LangChain + +[LangChain](https://python.langchain.com/docs/) does not yet include a built-in MCP connector, but you can integrate by: + +1. Running the Keboola MCP Server, or attaching to our deployed instance `https://mcp.REGION.keboola.com`. +2. Mapping each entry from `list_tools()` to a `Tool` in LangChain. +3. Adding those tools to an `AgentExecutor`. + +Because the server returns standard JSON schemas, the mapping is straightforward and can be handled with a lightweight wrapper. Native MCP support is already under discussion in the LangChain community. + +### Other frameworks + +* **[Crew AI](https://crewai.com)** – Provide crew members with Keboola tool definitions and route tool invocations through the MCP server. + +### Building your own MCP client + +If you are developing your own MCP client or integrating MCP capabilities into a custom application, you can connect to the Keboola MCP Server. The server supports standard MCP communication protocols. -For detailed technical documentation including the full list of read-only tools and header combination behavior, see the [Developer Documentation](https://developers.keboola.com/integrate/mcp/#tool-authorization-and-access-control). +For detailed instructions and SDKs for building your own MCP client, refer to the official [Model Context Protocol documentation for client developers](https://modelcontextprotocol.io/quickstart/client). Supported transports (`stdio`, `Streamable HTTP`) are listed in [MCP Server Capabilities](#mcp-server-capabilities) above. For more details on the Keboola MCP server, including how it can be run and configured for custom client integration, refer to its [GitHub repository](https://github.com/keboola/mcp-server). ## Advanced Setup Options These methods are for developers or specific use cases (e.g., testing, contributing to the MCP server).