🧠 Connect an AI client to Keboola

Get your AI client talking to your Keboola project. Every route below does the same thing: point the client at your project's MCP server URL, authenticate with your Keboola account, and pick the project — after which the assistant can use the Keboola tools. For what the server is and how permissions work, see the MCP Server overview.

You'll need a Keboola project and an account whose role has the permissions you want the assistant to have — over OAuth it inherits exactly those.

Step 1 — Get your server URL

The MCP Server runs on every multi-tenant stack, and your stack is the host in your Keboola URL: connection.<stack>.keboola.com in the browser means mcp.<stack>.keboola.com for MCP. Copy the whole URL from the row that matches:

| Stack (region) | Server URL | |---|---| | US Virginia AWS (default) | https://mcp.keboola.com/mcp | | US Virginia GCP (us-east4) | https://mcp.us-east4.gcp.keboola.com/mcp | | EU Frankfurt AWS (eu-central-1) | https://mcp.eu-central-1.keboola.com/mcp | | EU Ireland Azure (north-europe) | https://mcp.north-europe.azure.keboola.com/mcp | | EU Frankfurt GCP (europe-west3) | https://mcp.europe-west3.gcp.keboola.com/mcp |

You can also copy it from the platform: open the avatar menu (top right) → Keboola MCP Server — or Project Settings → the MCP Server tab. That page has a Copy URL to clipboard button, plus per-client instructions and an install button for some clients.

Wherever you take it from, paste the full URL. The <YOUR_REGION> placeholder in the snippets below is a stand-in for the whole host: on the default stack the region segment disappears entirely (mcp.keboola.com), and on GCP/Azure it carries the provider (us-east4.gcp, north-europe.azure).

Step 2 — Set up your client

Claude

Note

Custom connectors are available on the Free, Pro, Max, Team, and Enterprise plans; each user adds the connector for themselves (Free is limited to one custom connector) and authenticates separately. Rolling a connector out organization-wide on Team/Enterprise is done by an Organization Owner under Organization settings → Connectors.

1. In Claude, go to Customize → Connectors.
2. Click +, then Add custom connector.
3. Give it a name (Keboola) and paste in the full server URL from step 1.
4. Click Add.
5. Click Connect on the new connector, authenticate with your Keboola account, and select the project you want to connect to.

Fallback — the mcp-remote adapter. For MCP clients that don't yet support native remote (OAuth) connections, bridge to the remote server with mcp-remote. This requires Node.js on your computer.

1. Open the Claude menu on your computer and select Settings…

2. Click Developer in the left-hand bar, then Edit Config.

3. Paste this into the config file and save:

   {
     "mcpServers": {
       "keboola": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://mcp.<YOUR_REGION>.keboola.com/mcp"
         ]
       }
     }
   }

4. Restart Claude Desktop. You'll be prompted to authenticate and select a project.

ChatGPT

Note

Custom connectors (Developer mode / MCP) are available on ChatGPT Plus, Pro, Business, and Enterprise, and are currently in beta.

1. Open settings — log in, click your profile icon in the bottom-left corner, and select Settings.
2. Turn on Developer mode — select the Connectors tab, open Advanced settings, toggle Developer mode on, and acknowledge the warning. Back on the Connectors page, click Create.
3. Configure the connector — in the "New Connector" window, give it a Name ("Keboola") and an optional description, then paste your MCP Server URL (step 1). Authentication is set to OAuth automatically. Tick the box acknowledging the beta, then click Create.
4. Authorize — you're redirected to Keboola; sign in if prompted and select the project. Once authorized you land back in ChatGPT with a "Keboola is now connected" confirmation.
5. Use it in a chat — enable the Keboola connector for the conversation from the message composer's tools/connectors menu (the exact control varies by ChatGPT version), then ask about your data: "What data tables are in my project?" or "Show me the latest job runs."

Cursor

Click the deeplink for your region:

| Stack (region) | Cursor deeplink | |---|---| | US Virginia AWS (default) | | | US Virginia GCP (us-east4) | | | EU Frankfurt AWS (eu-central-1) | | | EU Ireland Azure (north-europe) | | | EU Frankfurt GCP (europe-west3) | |

Alternatively, install it from the platform:

1. Open the avatar menu → Keboola MCP Server (or Project Settings → the MCP Server tab).
2. Open the Cursor tab.
3. Click the Add Keboola MCP server to Cursor button.
4. Log in to your Keboola account and select the project.

Claude Code

One command, using the full server URL from step 1:

claude mcp add --transport http keboola https://mcp.<YOUR_REGION>.keboola.com/mcp

Then run /mcp in Claude Code and authenticate with your Keboola account to select the project.

Windsurf

Windsurf supports MCP through its native integration with Cascade. Add the server with a manual configuration:

1. Open the MCPs panel in Cascade (in current builds: Settings → Cascade → MCP Servers).

2. Add a custom server, or edit mcp_config.json directly (~/.codeium/windsurf/mcp_config.json).

3. Add the Keboola MCP Server configuration:

   {
     "mcpServers": {
       "keboola": {
         "serverUrl": "https://mcp.<YOUR_REGION>.keboola.com/mcp"
       }
     }
   }

4. Put the full server URL from step 1 in serverUrl.

5. Refresh the server list.

6. Authenticate with your Keboola account and select the project.

For detailed instructions and troubleshooting, see the Windsurf MCP documentation.

VS Code

VS Code reaches MCP servers through GitHub Copilot's agent mode. You need VS Code with the GitHub Copilot extension enabled.

1. Make sure the GitHub Copilot extension is up to date.

2. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run MCP: Add Server.

3. This creates or opens your MCP configuration file (mcp.json).

4. Add the configuration — VS Code connects to remote servers natively over Streamable HTTP, no adapter needed:

   {
     "servers": {
       "keboola": {
         "type": "http",
         "url": "https://mcp.<YOUR_REGION>.keboola.com/mcp"
       }
     }
   }

5. Put the full server URL from step 1 in url, and save.

6. Restart VS Code, or check the server from the Command Palette with MCP: List Servers.

7. Authenticate with your Keboola account and select the project.

Using the tools: open the Chat view, enable agent mode, and click Tools to see the available Keboola tools. Type # in the chat to reference a specific tool or resource.

For detailed setup and troubleshooting, see the VS Code MCP documentation.

Make

1. Create your scenario in Make.
2. Search for and add the MCP Client module.
3. Select Keboola from the module's dropdown.
4. Paste the server URL from step 1 (the platform's Make tab has a copy button) and save. Make loads the available Keboola tools automatically.

Any other client

Any AI assistant that supports a remote Streamable HTTP connection with OAuth can use the server:

1. Take the server URL for your stack from step 1.
2. Paste it into your assistant's settings.
3. Save and refresh the assistant. You'll be prompted to authenticate with your Keboola account and select the project you want to connect to.

If your client can't do remote OAuth yet, bridge to it with the mcp-remote adapter — open the Claude tab above for the config — or run the server locally.

Result: the assistant lists Keboola tools and works in the project with the permissions your Keboola role has. Ask it "What tables are in my project?" to confirm the connection.

Scope the connection to a development branch

To keep an agent's changes off production, send the X-Branch-Id HTTP header with your development branch ID. Whether you can set a custom header at all depends on the client — check its documentation; the desktop clients above generally can't, so the reliable route is running the server yourself with KBC_BRANCH_ID set. Without either, the server works on production.

Connect from your own code

The rest of this page is more technical

The recipes below are for building MCP into your own application or agent framework. If you just wanted to connect an AI client, you're done — skip these, or hand them to your coding agent.

Claude Messages API with MCP connector (beta)

Anthropic's MCP connector connects remote MCP servers directly through Claude's Messages API, so you don't need a standalone MCP client if you're already calling the API.

• Direct API calls — configure servers with the mcp_servers parameter in your request, and enable tools via an mcp_toolset in the tools array.
• Beta header — send anthropic-beta: mcp-client-2025-11-20 (the earlier mcp-client-2025-04-04 version is deprecated).
• Tool calling is the MCP functionality currently supported through the connector.
• Accessibility — the target MCP server has to be publicly reachable over HTTP, which the hosted Keboola server is.

For API examples and configuration options, see the official MCP connector documentation.

OpenAI Agents SDK (Python)

The OpenAI Agents SDK ships with first-class MCP support. Start the Keboola MCP Server (locally via uvx, or remotely over Streamable HTTP) and register it:

import asyncio

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async def main():
    async with MCPServerStdio(
        params={
            "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",
            },
        }
    ) as mcp:
        agent = Agent(
            name="Assistant",
            instructions="Use the Keboola tools to achieve the task",
            mcp_servers=[mcp],
        )
        result = await Runner.run(agent, "Load yesterday's CSV into Snowflake")
        print(result.final_output)

asyncio.run(main())

The SDK calls list_tools() on the server automatically, making every Keboola operation available to the model. The server needs credentials of its own — without KBC_STORAGE_TOKEN every tool call comes back with "Storage API token is not provided." See Run the server yourself for what those values are.

LangChain

LangChain has an official MCP adapter, langchain-mcp-adapters. Point its MultiServerMCPClient at the server and load the tools into your agent:

import asyncio

from langchain_mcp_adapters.client import MultiServerMCPClient

async def main():
    client = MultiServerMCPClient(
        {
            "keboola": {
                "transport": "streamable_http",
                "url": "https://mcp.<YOUR_REGION>.keboola.com/mcp",
                "headers": {"Authorization": "Bearer YOUR_OAUTH_ACCESS_TOKEN"},
            }
        }
    )
    tools = await client.get_tools()
    # pass `tools` to your LangChain / LangGraph agent

asyncio.run(main())

The hosted endpoints enforce OAuth — an unauthenticated call returns 401. Either carry an access token as shown, or point the client at a server you run yourself, which authenticates with a Storage token instead.

Other frameworks

• CrewAI — use the native MCP support via MCPServerAdapter from crewai-tools[mcp] to expose the Keboola tools to your crew.

Building your own MCP client

If you're writing your own client, the server speaks the standard MCP protocols over stdio and Streamable HTTP. Start from the Model Context Protocol documentation for client developers; for how the Keboola server itself can be run and configured, see its GitHub repository and Run the server yourself.

Next: Tools reference →