Keboola

Servidor MCP da Keboola

Conecte seus agentes de IA, clientes MCP (Cursor, Claude, Windsurf, VS Code ...) e outros assistentes de IA à Keboola. Disponibilize dados, transformações, consultas SQL e acionadores de jobs — sem precisar de código de integração. Entregue os dados certos aos agentes, quando e onde eles precisarem.

Visão geral

O servidor MCP da Keboola é uma ponte de código aberto entre seu projeto Keboola e as ferramentas modernas de IA. Ele transforma recursos da Keboola — como acesso ao armazenamento, transformações SQL e acionadores de jobs — em ferramentas que podem ser chamadas pelo Claude, Cursor, CrewAI, LangChain, Amazon Q e outros.

• Início rápido
• Configuração local

Recursos

Com o Agente de IA e o servidor MCP, você pode:

• Armazenamento: consultar tabelas diretamente e gerenciar descrições de tabelas ou buckets
• Componentes: criar, listar e inspecionar extratores, gravadores, aplicativos de dados e configurações de transformações
• SQL: criar transformações SQL usando linguagem natural
• Jobs: executar componentes e transformações e recuperar detalhes da execução dos jobs
• Fluxos: criar e gerenciar pipelines de fluxo de trabalho usando Conditional Flows e Orchestrator Flows.
• Aplicativos de dados: criar, implantar e gerenciar aplicativos de dados da Keboola que exibem suas consultas sobre dados de armazenamento — aplicativos python-js em um repositório gerenciado pela Keboola ou em um repositório GitHub do cliente (clonado por meio da conexão GitHub da organização, sem credenciais armazenadas) e aplicativos Streamlit.
• Metadados: pesquisar, ler e atualizar a documentação do projeto e os metadados dos objetos usando linguagem natural
• Branches de desenvolvimento: trabalhar com segurança em branches de desenvolvimento fora da produção, onde todas as operações são limitadas ao branch selecionado.

---

🚀 Início rápido: servidor MCP remoto (maneira mais fácil)

A maneira mais fácil de usar o servidor MCP da Keboola é por meio do nosso servidor MCP remoto. Essa solução hospedada elimina a necessidade de configuração, instalação ou preparação local.

O que é o servidor MCP remoto?

Nosso servidor remoto está hospedado em cada stack multi-tenant da Keboola e oferece suporte à autenticação OAuth. Você pode se conectar a ele usando qualquer assistente de IA compatível com conexões remotas Streamable HTTP e autenticação OAuth.

Como se conectar

1. Obtenha a URL do servidor remoto: acesse Configurações do projeto Keboola → guia MCP Server
2. Copie a URL do servidor: ela terá este formato: https://mcp.<YOUR_REGION>.keboola.com/mcp
3. Configure seu assistente de IA: cole a URL nas configurações MCP do seu assistente de IA
4. Autentique-se: será solicitado que você entre com sua conta Keboola. A escolha do(s) projeto(s) em que trabalhar será feita depois, durante a conversa (por exemplo, "liste meus projetos Keboola" / "use o projeto X")

Clientes compatíveis

• Cursor: use o botão "Install In Cursor" nas configurações do servidor MCP do seu projeto ou clique neste botão
• Claude Desktop: adicione a integração em Configurações → Integrações
• Claude Code: instale usando claude mcp add --transport http keboola <URL> (veja os detalhes abaixo)
• Windsurf: configure com a URL do servidor remoto
• Make: configure com a URL do servidor remoto
• Outros clientes MCP: configure com a URL do servidor remoto

Configuração do Claude Code

O Claude Code é uma ferramenta de interface de linha de comando que permite interagir com o Claude usando seu terminal. Você pode instalar a integração do servidor MCP da Keboola com um comando simples.

Instalação:

Execute o seguinte comando no terminal, substituindo <YOUR_REGION> pela sua região da Keboola:

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

Comandos específicos por região:

Região	Comando de instalação
US Virginia AWS	claude mcp add --transport http keboola https://mcp.keboola.com/mcp
US Virginia GCP	claude mcp add --transport http keboola https://mcp.us-east4.gcp.keboola.com/mcp
EU Frankfurt AWS	claude mcp add --transport http keboola https://mcp.eu-central-1.keboola.com/mcp
EU Ireland Azure	claude mcp add --transport http keboola https://mcp.north-europe.azure.keboola.com/mcp
EU Frankfurt GCP	claude mcp add --transport http keboola https://mcp.europe-west3.gcp.keboola.com/mcp

Uso:

Após a instalação, você pode usar o servidor MCP da Keboola no Claude Code digitando /mcp na conversa e selecionando as ferramentas da Keboola que deseja usar.

Autenticação:

Na primeira vez que usar o servidor MCP da Keboola no Claude Code, uma janela do navegador será aberta solicitando que você:

1. Entre com sua conta Keboola
2. Autorize a conexão

Após a autenticação, você poderá começar a usar as ferramentas da Keboola diretamente no Claude Code. A seleção do projeto acontece depois, durante a conversa — basta perguntar ao Claude qual(is) projeto(s) Keboola usar.

Para instruções detalhadas de configuração e URLs específicas por região, consulte nossa documentação de configuração do servidor remoto.

Uso de branches de desenvolvimento

Você pode trabalhar com segurança em branches de desenvolvimento da Keboola sem afetar seus dados de produção. Os servidores MCP hospedados remotamente respeitam o parâmetro KBC_BRANCH_ID e limitam todas as operações ao branch especificado. Você pode encontrar o ID do branch de desenvolvimento na URL ao navegar até ele na interface, por exemplo: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard. O ID do branch deve ser incluído em cada solicitação usando o cabeçalho X-Branch-Id: <branchId>; caso contrário, o servidor MCP usará o branch de produção como padrão. Isso deve ser gerenciado pelo cliente de IA ou pelo ambiente que controla a conexão com o servidor.

Autorização de ferramentas e controle de acesso

Ao usar transportes baseados em HTTP (Streamable HTTP), você pode controlar quais ferramentas ficam disponíveis para os clientes usando cabeçalhos HTTP. Isso é útil para restringir os recursos dos agentes de IA ou aplicar políticas de conformidade.

Cabeçalhos de autorização

Cabeçalho	Descrição	Exemplo
X-Allowed-Tools	Lista de ferramentas permitidas, separadas por vírgulas	get_configs,get_buckets,query_data
X-Disallowed-Tools	Lista de ferramentas a excluir, separadas por vírgulas	create_config,run_job
X-Read-Only-Mode	Restringe o acesso apenas a ferramentas somente leitura	true, 1 ou yes

Comportamento dos filtros

Os filtros são aplicados nesta ordem: permitidas → interseção com somente leitura → exclusão das não permitidas. Cabeçalhos vazios = sem restrições.

Ferramentas somente leitura

Ferramentas somente leitura são aquelas anotadas com readOnlyHint=True. Essas ferramentas apenas recuperam informações, sem fazer alterações no seu projeto Keboola. Para ver a lista atual de ferramentas somente leitura, consulte o arquivo TOOLS.md, que é uma captura gerada automaticamente do conjunto real de ferramentas.

Exemplo: acesso somente leitura

X-Read-Only-Mode: true

Carregamento adiado de ferramentas

Cabeçalho	Descrição	Exemplo
X-Deferred-Tools	Lista de ferramentas a exibir com _meta["anthropic/alwaysLoad"] = false	run_sync_action,get_flow_schema

Os clientes Claude Code / Claude Agent SDK que registram o servidor com alwaysLoad: true mantêm essas ferramentas adiadas, disponíveis por meio da busca de ferramentas, em vez de carregar suas definições antecipadamente. O cabeçalho altera apenas os metadados de tools/list — ele não oculta nem autoriza ferramentas. Cabeçalho vazio ou nomes de ferramentas desconhecidos = nenhuma alteração.

Para obter documentação detalhada, consulte developers.keboola.com/integrate/mcp/#tool-authorization-and-access-control.

Segurança em nível de linha e de coluna

As políticas em nível de linha e de coluna são objetos do Keboola Metastore (rls-policy, cls-policy), gravados por meio da API do Metastore (os comandos kbagent rls / kbagent cls ainda não estão disponíveis em nenhuma versão do kbagent). Este servidor não as lê nem as aplica. Em um projeto que tenha o recurso row-level-security, ele cria seu workspace (a configuração mcp-workspace-<hex> do componente keboola.mcp-server-tool) com o tipo de login Connection governed. Um workspace governado não tem credenciais: somente o Query Service pode lê-lo, e o Query Service filtra cada resultado de query_data de acordo com as políticas do projeto. Este servidor não reescreve nada e não oferece alternativa: o que o Query Service recusar, query_data retorna como erro.

• O que o ativa. O recurso do projeto é verificado apenas por este servidor; a Connection não precisa de recurso nem de função para criar um workspace governado (Snowflake ou BigQuery, sem chave pública). A Connection da stack precisa aceitar o tipo de login governed para o backend do projeto: uma stack que não o aceite recusa a criação, e então todas as ferramentas que precisam do workspace falham (não há fallback para um workspace comum). A aplicação das políticas no BigQuery não foi verificada de ponta a ponta em uma stack de produção. Um workspace MCP comum mais antigo não é excluído: ele é ignorado assim que o recurso é ativado. Com o recurso ativado, um pin workspace_schema ou X-Workspace-Id só é aceito para um workspace governado (um comum permitiria contornar as políticas), então um pin para o workspace antigo, ou para o próprio workspace comum de um data app, é recusado; exclua o antigo.
• Negar por padrão. Uma tabela que não seja coberta por um rls-policy nem por um cls-policy é recusada para um administrador (o agente vê Row-level security does not allow this query) e retorna zero linhas para um leitor comum, como um usuário final de data app (uma regra "*" abre uma tabela para todos os leitores identificados). Um cls-policy sozinho abre sua tabela: todas as linhas, apenas suas colunas, para os leitores que ele nomeia; qualquer outro leitor é recusado. Uma instrução que não lê nenhuma tabela (SELECT 1) é executada.
• Instruções recusadas. Uma instrução governada é recusada (403, o mesmo texto genérico para todos os motivos) quando usa IDENTIFIER(), TABLE() fora de FROM, uma função de IA (AI_*, BigQuery AI.*), TO_FILE, READ_CSV / READ_PARQUET, SECRET, uma função de contexto de sessão (CURRENT_USER, CURRENT_ROLE, CURRENT_STATEMENT, ...), NEXTVAL, $x ou @@x, um caractere de controle ou um nome sem aspas com caractere não ASCII ou $$, ou quando excede 32 KiB, 200 CTEs ou 300 referências a tabelas. CURRENT_DATE, CURRENT_TIME e CURRENT_TIMESTAMP continuam permitidos (a partir do Query Service 1.25 e do mecanismo de políticas 0.1.8). Um erro 503 Row-level security could not be applied to this workspace significa que nada foi executado porque não foi possível aplicar as políticas; pode ser transitório. Uma instrução governada com falha retorna The statement failed. Its error text is not shown for a workspace with row-level security.
• Quem é o leitor. O Query Service resolve o leitor a partir do próprio token do administrador no projeto: o token programático encaminhado por este servidor (kbc_at_ / kbc_pat_, incluindo o PAT filho de um escopo de vários projetos, enviado com X-KBC-ProjectId) ou o próprio token mestre de Storage do administrador. Qualquer outro token (de uma integração, de um data app, do Kai) não identifica nenhum usuário final, não tem identidade verificada e não lê nada de uma tabela governada. O subject do administrador é keboola|<adminId> e a identidade não carrega grupos, portanto as regras de grupo nunca correspondem.
• Vínculos. Sem um vínculo, um workspace recebe todas as políticas do projeto, e este servidor nunca cria um. Para dar a um workspace apenas algumas políticas, vincule-as ao KID dele: KID:<stack-id>:project-<project-id>:workspace-<workspace-id> (um workspace da branch padrão; um workspace de branch também tem branch-<branch-id> antes de project). O ID da stack é aquele com o qual o Query Service está configurado (QUERY_RLS_STACK_ID, por exemplo, dev-keboola-aws-eu-west-1), o ID do workspace está na saída de get_project_info, e um objeto Metastore policy-binding com esse KID grava o vínculo (ainda não foi lançado nenhum comando do kbagent para isso). Um vínculo é uma lista de permissões: mantém apenas as políticas que lista, então pode omitir qualquer política, inclusive uma de escopo organizacional, e afrouxar o acesso. Um vínculo que não lista nenhum rls-policy remove todas as políticas de linhas, então uma tabela coberta por um cls-policy mantido é aberta com todas as linhas. Um vínculo se aplica à próxima consulta e não acompanha a sessão para outro workspace: uma sessão de branch, ou um workspace recriado, tem um novo KID e começa novamente com todas as políticas.
• Limites. O ID do workspace do servidor também é o que um data app recebe como WORKSPACE_ID quando nenhum workspace separado é provisionado para ele; o app consulta com seu próprio token, não tem identidade verificada e não lê nada de tabelas governadas.
• Metadados. As ferramentas de metadados mostram apenas o que o Query Service permite que o leitor leia. get_tables e search (que então não usa a busca global, pois as contagens incluem as tabelas ocultas) omitem uma tabela que o leitor não pode ler, e get_tables informa que uma tabela solicitada por ID não foi encontrada; uma tabela com uma política de colunas mostra apenas as colunas da política (também na chave primária e no que search corresponde). Uma tabela legível é exibida sem o número de linhas e seu tamanho, que contam as linhas ocultadas por uma política de linhas. get_buckets ainda lista todos os buckets, mas sem o número de tabelas e o tamanho, que contam as tabelas ocultas. Isso requer o endpoint do Query Service POST /api/v1/branches/{branch}/workspaces/{workspace}/rls/scope e falha de forma segura: quando o Query Service não consegue determinar, uma ferramenta de um projeto governado retorna um erro com uma mensagem curta e nenhuma tabela. Um projeto sem o recurso não é afetado e não faz chamadas adicionais.

---

Configuração do servidor MCP local (modo personalizado ou de desenvolvimento)

Execute o servidor MCP na sua própria máquina para ter controle total e facilitar o desenvolvimento. Escolha esta opção quando quiser personalizar ferramentas, depurar localmente ou iterar rapidamente. Você instalará o servidor, fará a autenticação (um login único pelo navegador — sem precisar colar um token) e o iniciará. Essa abordagem oferece flexibilidade máxima (ferramentas personalizadas, registros locais, iteração offline), mas exige configuração manual, e você mesmo gerencia as atualizações e os segredos.

O servidor oferece suporte a várias opções de transporte, que podem ser selecionadas fornecendo o argumento --transport <transport> ao iniciar o servidor:

• stdio - Padrão quando --transport não é especificado. Entrada/saída padrão, normalmente usado para implantação local com um único cliente.
• streamable-http - Executa o servidor remotamente por HTTP com um canal de streaming bidirecional, permitindo que o cliente e o servidor troquem mensagens continuamente. Conecte-se via /mcp (por exemplo, http://localhost:8000/mcp).
• http-compat - Um alias para streamable-http, mantido para compatibilidade com versões anteriores.

Para trabalhar com seu projeto Keboola, o servidor precisa de duas coisas: sua região Keboola (KBC_STORAGE_API_URL) e uma forma de autenticação. A forma recomendada é um login único pelo navegador — você nunca cria, copia ou cola um token. Opcionalmente, defina KBC_BRANCH_ID para trabalhar em uma branch de desenvolvimento.

Algumas variáveis não são obtidas dos cabeçalhos da solicitação:

• KBC_STORAGE_API_URL: um servidor iniciado com sua própria URL da Storage API (o parâmetro --api-url ou a variável de ambiente KBC_STORAGE_API_URL) atende apenas àquela stack Keboola. Um cabeçalho X-Storage-Api-Url que solicite outro host é ignorado (um aviso é registrado) — o servidor mantém sua própria URL para a solicitação. Inicie o servidor sem uma URL própria da Storage API se quiser que cada solicitação escolha sua stack.
• KBC_KUBERNETES_TOKEN_PATH (somente servidores implantados, consulte docs/kubernetes-sa-auth.md): lido apenas do ambiente, nunca de um cabeçalho.
• KBC_WORKSPACE_ID / KBC_WORKSPACE_SCHEMA: mesma ideia da URL da Storage API acima — um servidor iniciado com seu próprio pin de workspace (por qualquer uma das variáveis ou por --workspace-id) mantém esse pin para todas as solicitações; um cabeçalho X-Workspace-Id ou X-Workspace-Schema que solicite outro workspace é ignorado (um aviso é registrado). Um servidor sem pin próprio (o caso compartilhado de vários usuários) continua recebendo o pin da solicitação, por solicitação, conforme descrito abaixo.

Fazendo login

Entre uma vez pelo navegador; o servidor armazena a sessão e a atualiza automaticamente, então não há tokens para gerenciar:

uvx keboola_mcp_server login --api-url https://connection.YOUR_REGION.keboola.com

Isso abre o navegador para você entrar no Keboola e, em seguida, salva a sessão válida para toda a stack em ~/.keboola/mcp/credentials.json (legível apenas por você, uma entrada por stack). Depois, inicie o servidor definindo apenas KBC_STORAGE_API_URL — não é necessário token. O(s) projeto(s) em que trabalhar será(ão) escolhido(s) depois, na conversa (get_accessible_projects / set_project_scope), não durante o login.

Comando	O que faz
login --api-url <url>	Entrar em uma stack
login --force	Entrar novamente / trocar de conta
login --show-token	Imprimir o token da sessão atual (depuração)
logout [--api-url <url>] [--all]	Remover a sessão armazenada de uma stack (ou de todas as stacks)

Quando você inicia o servidor por stdio em um terminal interativo sem uma sessão armazenada, ele executa automaticamente esse login pelo navegador na primeira inicialização. Clientes MCP (Claude, Cursor, …) iniciam o servidor em segundo plano, onde não é possível abrir um navegador, então execute login uma vez antes.

Iniciar sem uma conta Keboola

Você também pode iniciar o servidor definindo apenas KBC_STORAGE_API_URL, sem nenhuma credencial. Ele inicia em modo de bootstrap: as ferramentas que precisam de acesso ao Keboola explicam como obter uma credencial, e uma ferramenta funciona sem ela — create_project. Ela cria um novo projeto Keboola, inicia uma sessão nele e retorna uma URL de confirmação. Ao abrir essa URL em um navegador e entrar, o projeto passa a ser seu permanentemente; até lá, ele é temporário e o Keboola pode recuperá-lo. Depois da confirmação, a sessão criada pela ferramenta é revogada e você continua com seu próprio login.

Isso requer uma stack com provisionamento de agentes ativado; em outras stacks, a ferramenta informa que não está disponível.

O mesmo é possível sem executar um servidor, em um servidor MCP hospedado remotamente cujo operador tenha ativado esse recurso (KBC_ALLOW_ANONYMOUS_PROVISIONING): essa implantação também oferece https://mcp.<stack>/mcp-anonymous, que não aceita credenciais. Aponte seu cliente para ele sem autenticação, chame create_project e continue trabalhando no projeto criado por essa chamada — o servidor mantém as credenciais para você, e a ferramenta retorna um scope_token opaco para reenviar em chamadas posteriores. Ele usa uma URL separada porque o endpoint comum /mcp precisa continuar recusando solicitações não autenticadas: essa recusa é como os clientes MCP sabem que devem iniciar o login OAuth. Depois de reivindicar o projeto, mude para /mcp e entre com a conta que agora é proprietária dele.

Autenticação sem navegador

Para contêineres ou CI em que não é possível fazer login pelo navegador, forneça diretamente um token de acesso ou token de acesso pessoal do Keboola — defina KBC_STORAGE_TOKEN (variável de ambiente) ou envie o cabeçalho X-StorageAPI-Token — junto com KBC_PROJECT_ID (ou o cabeçalho X-KBC-ProjectId) para selecionar o projeto. Em transportes HTTP, eles podem ser fornecidos como cabeçalhos por solicitação, para que cada solicitação carregue suas próprias credenciais.

KBC_WORKSPACE_ID

Direciona as consultas a um workspace específico já existente, identificado pelo ID, em vez de usar a busca baseada em esquema descrita acima, e tem precedência sobre KBC_WORKSPACE_SCHEMA quando ambos estão definidos. Esta é a opção que um chamador de Data App / kai-agent fornece como cabeçalho X-Workspace-Id, para que o Kai incorporado nesse app consulte apenas por meio do próprio workspace.

Defina-o pela variável de ambiente KBC_WORKSPACE_ID, pela opção de linha de comando --workspace-id ou pelo cabeçalho X-Workspace-Id (por solicitação, em implantações com vários usuários).

KBC_WORKSPACE_SCOPE

strict limita uma sessão ao workspace fixado, para o Kai em um Data App cujo workspace tem mapeamento de entrada por concessão direta. A sessão então:

• oferece apenas query_data, get_buckets, get_tables, get_project_info e docs_query, independentemente do que os cabeçalhos de autorização informem (eles podem restringir ainda mais essa lista, mas não ampliá-la);
• nunca procura nem cria o workspace gerenciado pelo MCP e nunca se expande para vários projetos;
• recusa um workspace com acesso somente de leitura a todo o Storage e recusa pré-visualizações de configuração. É necessário fixar um workspace (KBC_WORKSPACE_ID / X-Workspace-Id). strict é o único valor aceito, portanto, uma solicitação pode restringir uma sessão, mas nunca flexibilizar um strict definido no servidor. Defina pela variável de ambiente KBC_WORKSPACE_SCOPE ou, por solicitação, pelo cabeçalho X-Workspace-Scope.

KBC_STORAGE_API_URL (Região da Keboola)

A URL da API da sua região da Keboola depende da região de implantação. Você pode identificar sua região verificando a URL no navegador enquanto estiver conectado ao seu projeto da Keboola:

Região	URL da API
AWS América do Norte	https://connection.keboola.com
AWS Europa	https://connection.eu-central-1.keboola.com
Google Cloud UE	https://connection.europe-west3.gcp.keboola.com
Google Cloud EUA	https://connection.us-east4.gcp.keboola.com
Azure UE	https://connection.north-europe.azure.keboola.com

KBC_BRANCH_ID (Opcional)

Para operar em uma ramificação de desenvolvimento da Keboola específica, defina o ID da ramificação usando o parâmetro KBC_BRANCH_ID. O servidor MCP limita seu funcionamento à ramificação especificada, garantindo que todas as alterações permaneçam isoladas e não afetem a ramificação de produção.

• Se não for informado, o servidor usará a ramificação de produção por padrão.
• Para trabalhar em desenvolvimento, defina KBC_BRANCH_ID como o ID numérico da sua ramificação (por exemplo, 123456). Você pode encontrar o ID da ramificação de desenvolvimento na URL ao navegar até ela na interface, por exemplo: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard.
• Em transportes remotos, você pode substituir esse valor por solicitação usando o cabeçalho HTTP X-Branch-Id: <branchId> ou KBC_BRANCH_ID: <branchId>.

Instalação

Verifique se você tem:

• Python 3.11+ instalado
• Acesso a um projeto da Keboola com direitos de administrador
• Seu cliente MCP preferido (Claude, Cursor etc.)

Observação: verifique se uv está instalado. O cliente MCP o usará para baixar e executar automaticamente o Keboola MCP Server. Instalando o uv:

macOS/Linux:

#if homebrew is not installed on your machine use:
# /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install using Homebrew
brew install uv

Windows:

# Using the installer script
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or using pip
pip install uv

# Or using winget
winget install --id=astral-sh.uv -e

Para ver mais opções de instalação, consulte a documentação oficial do uv.

Executando o Keboola MCP Server

Há quatro maneiras de usar o Keboola MCP Server, dependendo das suas necessidades:

Opção A: Modo integrado (recomendado)

Nesse modo, o Claude ou o Cursor inicia automaticamente o servidor MCP para você.

1. Faça login uma vez em um terminal para que uma sessão seja armazenada (o cliente inicia o servidor em segundo plano, onde não é possível abrir um navegador):

   uvx keboola_mcp_server login --api-url https://connection.YOUR_REGION.keboola.com
   

2. Configure seu cliente MCP (Claude/Cursor) com as definições abaixo — somente KBC_STORAGE_API_URL é necessário.
3. O cliente iniciará automaticamente o servidor MCP quando necessário.

Configuração do Claude Desktop

1. Acesse Claude (canto superior esquerdo da tela) -> Settings → Developer → Edit Config (se você não encontrar claude_desktop_config.json, crie-o)
2. Adicione a seguinte configuração:
3. Reinicie o Claude desktop para que as alterações entrem em vigor

{
  "mcpServers": {
    "keboola": {
      "command": "uvx",
      "args": ["keboola_mcp_server --transport <transport>"],
      "env": {
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Locais do arquivo de configuração:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuração do Cursor

1. Acesse Settings → MCP
2. Clique em "+ Add new global MCP Server"
3. Configure com estas definições:

{
  "mcpServers": {
    "keboola": {
      "command": "uvx",
      "args": ["keboola_mcp_server --transport <transport>"],
      "env": {
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Observação: use nomes curtos e descritivos para os servidores MCP. Como o nome completo da ferramenta inclui o nome do servidor e deve ter menos de ~60 caracteres, nomes mais longos podem ser filtrados no Cursor e não serão exibidos ao Agent.

Configuração do Cursor para Windows WSL

Ao executar o servidor MCP no Windows Subsystem for Linux com o Cursor AI, use esta configuração:

{
  "mcpServers": {
    "keboola":{
      "command": "wsl.exe",
      "args": [
          "bash",
          "-c '",
          "export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com &&",
          "export KBC_BRANCH_ID=your_branch_id_optional &&",
          "/snap/bin/uvx keboola_mcp_server --transport <transport>",
          "'"
      ]
    }
  }
}

Opção B: Modo de desenvolvimento local

Para desenvolvedores que trabalham no próprio código do servidor MCP:

1. Clone o repositório e configure um ambiente local
2. Configure o Claude/Cursor para usar seu caminho local do Python:

{
  "mcpServers": {
    "keboola": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": [
        "-m",
        "keboola_mcp_server --transport <transport>"
      ],
      "env": {
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Opção C: Modo CLI manual (somente para testes)

Você pode executar o servidor manualmente em um terminal para testar ou depurar:

# Sign in once (stores a session under ~/.keboola/mcp), then start the server.
export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com
uvx keboola_mcp_server login --api-url "$KBC_STORAGE_API_URL"

uvx keboola_mcp_server --transport streamable-http

Observação: este modo é usado principalmente para depuração ou testes. Para uso normal com Claude ou Cursor, não é necessário executar o servidor manualmente.

Observação: o servidor usará o transporte Streamable HTTP e escutará em localhost:8000 as conexões recebidas em /mcp. Você pode usar os parâmetros --port e --host para fazê-lo escutar em outro local.

Opção D: Usando Docker

Um contêiner não pode abrir um navegador, então autentique-se com um token (consulte Autenticação sem navegador): defina KBC_STORAGE_TOKEN como um token de acesso/token de acesso pessoal da Keboola e KBC_PROJECT_ID como o projeto de destino. (Por HTTP, você pode passar os cabeçalhos X-StorageAPI-Token / X-KBC-ProjectId por solicitação e omitir essas variáveis.)

docker pull keboola/mcp-server:latest

docker run \
  --name keboola_mcp_server \
  --rm \
  -it \
  -p 127.0.0.1:8000:8000 \
  -e KBC_STORAGE_API_URL="https://connection.YOUR_REGION.keboola.com" \
  -e KBC_STORAGE_TOKEN="YOUR_KEBOOLA_TOKEN" \
  -e KBC_PROJECT_ID="YOUR_PROJECT_ID" \
  -e KBC_BRANCH_ID="YOUR_BRANCH_ID_OPTIONAL" \
  keboola/mcp-server:latest \
  --transport streamable-http \
  --host 0.0.0.0

Observação: o servidor usará o transporte Streamable HTTP e escutará em localhost:8000 as conexões recebidas em /mcp. Você pode alterar -p para mapear a porta do contêiner para outro local.

Preciso iniciar o servidor por conta própria?

Cenário	Preciso executar manualmente?	Use esta configuração
Usando Claude/Cursor	Não	Configure o MCP nas definições do aplicativo
Desenvolvendo o MCP localmente	Não (o Claude inicia)	Aponte a configuração para o caminho do Python
Testando a CLI manualmente	Sim	Execute pelo terminal
Usando Docker	Sim	Execute o contêiner do Docker

Usando o servidor MCP

Depois que seu cliente MCP (Claude/Cursor) estiver configurado e em execução, você poderá começar a consultar seus dados da Keboola:

Verifique sua configuração

Você pode começar com uma consulta simples para confirmar que tudo está funcionando:

What buckets and tables are in my Keboola project?

Exemplos do que você pode fazer

Exploração de dados:

• "Quais tabelas contêm informações de clientes?"
• "Execute uma consulta para encontrar os 10 principais clientes por receita"

Análise de dados:

• "Analise meus dados de vendas por região no último trimestre"
• "Encontre correlações entre a idade dos clientes e a frequência de compras"

Pipelines de dados:

• "Crie uma transformação SQL que una as tabelas de clientes e pedidos"
• "Inicie o job de extração de dados do meu componente Salesforce"

Compatibilidade

Suporte a clientes MCP

Cliente MCP	Status do suporte	Método de conexão
Claude (Desktop e Web)	✅ com suporte	stdio
Cursor	✅ com suporte	stdio
Windsurf, Zed, Replit	✅ Com suporte	stdio
Codeium, Sourcegraph	✅ Com suporte	Streamable HTTP
Clientes MCP personalizados	✅ Com suporte	Streamable HTTP ou stdio

Ferramentas compatíveis

Observação: seus agentes de IA se adaptarão automaticamente às novas ferramentas.

Para ver a lista completa de ferramentas disponíveis, com descrições detalhadas, parâmetros e exemplos de uso, consulte TOOLS.md.

Solução de problemas

Problemas comuns

Problema	Solução
Erros de autenticação	Execute novamente keboola_mcp_server login (ou, se estiver autenticando com um token, verifique o token e KBC_PROJECT_ID)
Tempo limite de conexão	Verifique a conectividade de rede

Desenvolvimento

Instalação

Configuração básica:

uv sync --extra dev

Com a configuração básica, você pode usar uv run tox para executar testes e verificar o estilo do código.

Configuração recomendada:

uv sync --extra dev --extra tests --extra integtests --extra codestyle

Com a configuração recomendada, os pacotes para testes e verificação do estilo do código serão instalados, permitindo que IDEs como VsCode ou Cursor verifiquem o código ou executem testes durante o desenvolvimento.

Testes de integração

Para executar testes de integração localmente, use uv run tox -e integtests. OBSERVAÇÃO: você precisará definir as seguintes variáveis de ambiente:

• INTEGTEST_POOL_STORAGE_API_URL
• INTEGTEST_STORAGE_TOKENS
• INTEGTEST_STORAGE_TOKEN_STORAGE_BRANCHES

Para obter esses valores, você precisa de projetos dedicados da Keboola para testes de integração. Cada sessão de teste cria seu próprio workspace somente leitura, portanto, não é necessário configurar o esquema do workspace. Consulte integtests/README.md para ver instruções detalhadas de configuração e a documentação de design.

Atualizando uv.lock

Atualize o arquivo uv.lock se você tiver adicionado ou removido dependências. Considere também atualizar o lock com versões mais recentes das dependências ao criar uma versão (uv lock --upgrade).

Atualizando a documentação das ferramentas

Ao fazer alterações nas descrições de qualquer ferramenta (docstrings nas funções das ferramentas), você deve gerar novamente o arquivo de documentação TOOLS.md para refletir essas alterações:

uv run python -m src.keboola_mcp_server.generate_tool_docs

Lançamento

Não fazemos um lançamento para cada PR mesclado. O trabalho é integrado continuamente ao trunk (main), e lançamos versões periodicamente, depois que as alterações são testadas novamente em conjunto — isso evita interromper configurações que já funcionam para os usuários.

Um lançamento é feito enviando uma ou duas tags do git:

• vX.Y.Z — o lançamento do servidor MCP (sempre)
• agent-vX.Y.Z — o lançamento do In Platform Agent (somente quando o agente também estiver sendo lançado)

Qualquer uma das tags aciona o CI release.yml, que compila e publica a imagem do Docker. O KaiBench é executado somente em tags de produção vX.Y.Z (não em agent-vX.Y.Z nem em pré-lançamentos -dev.). Use a skill release-notes — ela prepara as notas de lançamento e um PR de rascunho e orienta você durante a criação das tags de vX.Y.Z e agent-vX.Y.Z.

Suporte e feedback

⭐ A principal forma de obter ajuda, relatar bugs ou solicitar recursos é abrir uma issue no GitHub. ⭐

A equipe de desenvolvimento acompanha as issues ativamente e responderá o mais rápido possível. Para informações gerais sobre a Keboola, use os recursos abaixo.

Recursos

• Documentação do usuário
• Documentação para desenvolvedores
• Plataforma Keboola
• Rastreador de issues ← Principal forma de contato para o MCP Server

Conecte-se

• LinkedIn
• Twitter
• Changelog