Cloudera Iceberg MCP Server (via Impala)

A Model Context Protocol server that lets AI assistants query Iceberg tables through Apache Impala, read-only and as the person who asked. It comes with a chat app that runs inside Cloudera AI (CAI).

Tools offered to the AI:

• get_schema(): the tables in the configured database, with their columns.

• execute_query(query): run one read-only SQL statement and return the rows as JSON.

Architecture

The core rule: every query runs in Impala as the individual who asked, never as a shared service account. Ranger decides what that person may read, and Impala's query log records their name.

How a question becomes a query

1. A person asks a question in an AI app.

2. The app calls the MCP server, carrying proof of who the person is.

3. The MCP server verifies that proof and works out the person's Cloudera username.

4. It connects to Impala as a dedicated machine user and asks to run the query as that person (impersonation, Impala's doAs).

5. Impala checks that the machine user is allowed to impersonate that person, then Ranger checks that the person may read the tables.

6. The query log records both names: the person (db_user) and the machine user that connected for them (db_user_connection).

Two ways in, one identity rule

The identity mode is chosen by settings (see Configuration). A third, test mode, runs every call as one fixed user with no identity check. It exists only to prove a first deployment and must not be exposed beyond a controlled test.

Layers of protection

Safe defaults throughout:

• Deny by default. Missing, invalid or unmapped identities are refused.

• No silent fallbacks. The server refuses to start without an identity mode, never falls back to the machine user, and refuses to combine Entra with CAI mode.

• Misconfiguration fails closed. In CAI mode the server refuses to start if its Application allows unauthenticated access. Even then, CAI strips forged identity headers (tested), so calls would be refused, not impersonated.

• Secrets stay out of the repo. The machine user's password lives only in Application settings, and the diagnostic whoami tool never returns a token.

The chat app's model is either Cloudera AI Inference (inside Cloudera, authenticated with the user's CAI login token) or AWS Bedrock (AWS access keys or a Bedrock API key). Either way, the model only sees results that the person's own permissions allowed.

Verified end to end

• An Azure AI Foundry agent queried through the MCP server, and Impala's query log showed the real end user as db_user, with the machine user as db_user_connection.

• The CAI chat app answered questions for two different users. Each person's queries appear in the query log under their own name, and Ranger checked each person's own access.

See docs/install-guide.md for the full setup (Impala, Ranger, impersonation, deployment) and docs/build-plan.md for the design history.

Related MCP server: Cloudera Iceberg MCP Server

Deploy on Cloudera AI

.project-metadata.yaml turns this repo into a Cloudera AI project template. You choose the mode with MCP_MODE:

1. In Cloudera AI: New Project > Git, paste this repo's URL, then Configure Project.

2. Fill in the environment variables it asks for:

   Variable	What to enter
   MCP_MODE	cai, entra or test
   IMPALA_HOST	Impala coordinator host
   IMPALA_USER	The machine user's workload username (machine users get an extra srv_ prefix)
   IMPALA_PASSWORD_B64	Its password, base64-encoded: printf %s 'PASSWORD' | base64 -w0
   IMPALA_PORT, IMPALA_DATABASE	Defaults are 443 and default
   cai: CAI_INFERENCE_BASE_URL or BEDROCK_MODEL_ID	The chat app's model; CAI_TRUSTED_CALLERS defaults to you
   entra: ENTRA_TENANT_ID, ENTRA_AUDIENCE	From the server's Entra app registration
   test: MCP_TEST_USER	The Cloudera user every request runs as

3. Launch. It installs dependencies, creates an optional sample-data job (not run automatically), and runs scripts/create_mcp_app.py, which creates the applications for the mode with the right CAI login setting. The MCP endpoint is the MCP application's URL plus /mcp.

4. Check it: scripts/curl_mcp.sh https://<application-url> list (see below).

If the template's variables don't reach the project (a known issue in some CAI versions), set them in Project Settings > Advanced > Environment Variables and run python scripts/create_mcp_app.py from a session. See docs/install-guide.md §5d.

Before you start, on the Impala side: the machine user must be allowed to impersonate the end users (authorized_proxy_user_config), and they need Ranger access to the tables (install guide §4). To try it with demo data, run the Load MovieLens sample data job, then set IMPALA_DATABASE to mcp_demo in the MCP application's settings and restart it.

Things to know:

• Unauthenticated applications can be blocked by a workspace admin ("unauthenticated access to applications prevented by site-wide configuration"). Entra and test mode need them allowed.

• In test mode anyone with the URL can run read-only queries as MCP_TEST_USER. Stop it when idle.

• The subdomains iceberg-mcp and iceberg-mcp-chat must be unused in the workspace (change them with APP_SUBDOMAIN), and the workspace must be able to reach PyPI. The runtime is PBJ Workbench, Python 3.12, Standard.

• The template is checked by tests (tests/test_project_metadata.py, tests/test_create_apps.py), but the first import into a fresh workspace is the real test.

Check the server with curl

scripts/curl_mcp.sh https://<application-url> health                       # is it up? (no token needed)
scripts/curl_mcp.sh https://<application-url> list                         # which tools does it offer?
scripts/curl_mcp.sh https://<application-url> call get_schema
scripts/curl_mcp.sh https://<application-url> call execute_query '{"query":"SELECT effective_user()"}'

A server that checks tokens needs one: TOKEN=<token> scripts/curl_mcp.sh ... (or TOKEN_FILE=<path>). No token gives HTTP 401, which is the correct answer from such a server. The script needs only curl. An MCP server expects a short conversation first (initialize, confirm, then your request), which the script does for you; the three steps are described at the top of the script.

Configuration

Impala on-prem (a cluster managed by Cloudera Manager), limits and scale

Do not put a round-robin load balancer between this server and Impala: the Impala client library opens a new connection for every request, so the requests of one session land on different coordinators and fail. List the coordinators in IMPALA_HOST, or use a balancer that keeps one client on one coordinator. tests/onprem_lab/ holds the test environment these settings were checked in (a real LDAP directory, a real Kerberos server and a stand-in for Impala), and scripts/test_doas.py runs the same checks against a real cluster.

The server refuses to start unless one identity mode is set: ENTRA_TENANT_ID+ENTRA_AUDIENCE (external apps), CAI_TRUSTED_CALLERS (CAI-hosted apps) or MCP_TEST_USER (test only). Entra and CAI mode together is refused, because they need opposite Application login settings.

Chat app (chat_app/)

Deploy as a second Application with script start_chat.py and CAI authentication on. Its dependencies are the chat extra (pip install ".[chat]"), which start_chat.py installs.

Testing

pip install -e ".[chat]" --group dev   # everything comes from pyproject.toml
pytest                                   # unit + end-to-end auth tests, no Cloudera needed
python scripts/test_doas.py --allowed <user> --denied <user>   # against a real Impala VW
python scripts/get_entra_token.py                               # real Entra sign-in (device code) -> .entra_token
python scripts/call_mcp.py <url> get_schema --token-file .entra_token --claims   # against a deployed server

Usage with AI frameworks

The ./examples folder contains several examples how to integrate this MCP Server with common AI Frameworks like LangChain/LangGraph, OpenAI SDK.

Transport

The MCP server's transport protocol is configurable via the MCP_TRANSPORT environment variable. Supported values:

• stdio (default) — communicate over standard input/output. Useful for local tools, command-line scripts, and integrations with clients like Claude Desktop.

• http - expose an HTTP server. Useful for web-based deployments, microservices, exposing MCP over a network.

• sse — use Server-Sent Events (SSE) transport. Useful for existing web-based deployments that rely on SSE.

Copyright (c) 2025 - Cloudera, Inc. All rights reserved.