Skip to content

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

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
Iamfle4ka wants to merge 1 commit into from
Closed

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
290 changes: 280 additions & 10 deletions src/content/docs/ai/mcp-server/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ title: Keboola Model Context Protocol (MCP) Server
slug: 'ai/mcp-server'
redirect_from:
- /external-integrations/mcp-server/
- /integrate/mcp/
---

:::caution
Expand Down Expand Up @@ -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
Expand All @@ -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"**
Expand Down Expand Up @@ -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).
Expand Down
Loading