home / mcp / ssb mcp server

SSB MCP Server

Model Context Protocol (MCP) server for SQL Steam Builder (SSB)

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "brooksian-ssb-mcp-server": {
      "command": "/path/to/run_mcp_server.sh",
      "args": [],
      "env": {
        "KNOX_TOKEN": "<your_knox_bearer_token>",
        "KNOX_COOKIE": "<KNOX_COOKIE>",
        "SSB_API_BASE": "https://ssb-gateway.yourshere.cloudera.site/ssb/api/v1",
        "SSB_BASE_URL": "https://your-ssb-host:443",
        "SSB_READONLY": "true",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

You deploy and use the SSB MCP Server to manage SQL Stream Builder environments through Claude Desktop or other MCP clients. It provides controlled access to SSB functionality, supports multiple authentication methods, and exposes a comprehensive set of tools for managing streams, data sources, environments, UDFs, and more while enabling safe read-only exploration by default.

How to use

Use Claude Desktop or your MCP client to interact with the SSB MCP Server. You can explore streams, jobs, tables, connectors, formats, and configuration options. By default, deployments in CDP (Cloudera Data Platform) run in read-only mode to prevent unintended changes, while standalone deployments can enable write access. When you are ready to perform actions, adjust the read-only setting and restart the MCP server if needed.

How to install

Follow these concrete steps to install and start the MCP server in two common ways: standalone SSB deployments using Claude Desktop locally, or integration with Cloudera AI Agent Studio.

# Option A: Standalone SSB deployments ( Claude Desktop Local )
# Prerequisites
# - Git
# - Python 3.8+ with venv support
# - Internet access to clone and install

# Step 1: Clone the MCP server repository and install in editable mode
git clone https://github.com/your-org/ssb-mcp-server.git
cd ssb-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Step 2: Configure Claude Desktop to load the MCP server (example shown in this section)
```
```]} ,{

# Start all services via Docker Compose (standalone path)
git clone https://github.com/your-org/ssb-mcp-server.git
cd ssb-mcp-server
docker-compose up -d

# Confirm services are running
docker-compose ps

docker-compose logs -f ssb-sse
```
```]} ,{

# Option A: Claude Desktop local config (stdin stdio transport)
{
  "mcpServers": {
    "ssb-mcp-server": {
      "command": "/FULL/PATH/TO/SSB-MCP-Server/run_mcp_server.sh",
      "args": [],
      "cwd": "/FULL/PATH/TO/SSB-MCP-Server"
    }
  }
}
```]} ,{

Note: The exact path and file used to start the MCP server in your environment may differ. Ensure Claude Desktop is pointed at the correct command and working directory for your installation.

### Option 2: Cloudera AI Agent Studio

If you are using Cloudera AI Agent Studio, configure the MCP server with environment variables and the given command flow to load the MCP server through the UVX runner.

{
  "mcpServers": {
    "ssb-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/your-org/ssb-mcp-server@main",
        "run-server"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "SSB_BASE_URL": "https://your-ssb-host:443",
        "SSB_TENANT": "your-tenant-name",
        "KNOX_TOKEN": "your_jwt_token_here",
        "MVE_USERNAME": "your_mve_username",
        "MVE_PASSWORD": "your_mve_password",
        "SSB_READONLY": "false"
      }
    }
  }
}
```

Environment variables shown above should be set according to your deployment. Restart the Cloudera AI Agent Studio after updating the configuration.

Additional setup and access points

Access points and UI details for the local Docker-based setup are shown here for quick reference.

SSB SSE: http://localhost:18121
SSB MVE: http://localhost:18131
Flink Job Manager: http://localhost:8081
NiFi: http://localhost:8080
Knox Gateway: https://localhost:8444 (if enabled)
```]}]} ,{

Configuration and environment notes

Configure the MCP server using either environment variables or a JSON configuration file. Environment variables take precedence over JSON. Important credentials to consider include Knox tokens for CDP deployments and SSB API base URLs for direct access. For Cloudera AI Agent Studio, always use environment variables as shown in the examples.

# Example JSON configuration for cloud/SSB access
{
  "cloud_ssb": {
    "base_url": "https://your-ssb-host:443",
    "tenant": "your-tenant-name",
    "jwt_token": "your_jwt_token_here",
    "ssb_readonly": false,
    "knox_verify_ssl": true,
    "http_timeout_seconds": 60,
    "http_max_retries": 3,
    "http_rate_limit_rps": 5,
    "mve_username": "your_mve_username",
    "mve_password": "your_mve_password"
  }
}
```

Environment variables example:

```
export SSB_BASE_URL="https://your-ssb-host:443"
export SSB_TENANT="your-tenant-name"
export KNOX_TOKEN="your_jwt_token_here"
export MVE_USERNAME="your_mve_username"
export MVE_PASSWORD="your_mve_password"
export SSB_READONLY="false"
```
```} ,{

If you plan to use the standalone mode with Claude Desktop, place the Python-based server run command in a setup similar to the example shown in the installation section and ensure Claude Desktop is restarted after applying changes.

Troubleshooting and tips

When you encounter issues, check authentication credentials, ensure services are running, and validate connector configurations. For issues with token expiration, refresh tokens manually as tokens do not auto-refresh.

If you need to verify which tables or data sources are available for querying, use the relevant discovery methods and remember that materialized views are accessed via the MVE API, not SQL.

Security and maintenance

Sensitive data such as passwords and tokens are redacted in responses. Read-only mode is enabled by default for CDP deployments to prevent unintended changes. Use API keys and proper authentication for secure access, and rotate credentials as part of your security best practices.

License

Apache License 2.0.

Available tools

get_job_events

Get detailed job event history and timeline

get_job_state

Get comprehensive job state information

copy_job

Duplicate an existing job

copy_data_source

Clone a data source

get_diagnostic_counters

Get system performance counters and diagnostics

get_heartbeat

Check system health and connectivity

analyze_sql

Analyze SQL query for syntax and performance without execution

list_tables_detailed

Get comprehensive table information

get_table_tree

Get hierarchical table structure organized by catalog

validate_data_source

Validate data source configuration

create_table_detailed

Create table with full configuration

get_table_details

Get detailed information about a specific table

list_data_formats

List all available data formats

get_data_format_details

Get details about a specific data format

create_data_format

Create a new data format

get_connector_jar

Get connector JAR information

get_connector_type_details

Get detailed connector type information

get_connector_details

Get detailed connector information

get_user_settings

Get user preferences and settings

update_user_settings

Update user configuration

list_projects

List available projects

get_project_details

Get project information

create_project

Create a new project

get_user_info

Get current user information

list_api_keys

List user API keys

create_api_key

Create new API key

delete_api_key

Delete API key

get_api_key_details

Get API key information

list_environments

List available environments

activate_environment

Activate/switch to an environment

get_environment_details

Get environment configuration

create_environment

Create new environment

deactivate_environment

Deactivate current environment

get_sync_config

Get sync configuration

update_sync_config

Update sync configuration

export_project

Export project configuration

import_project

Import project configuration

list_udfs_detailed

Get comprehensive UDF information

run_udf

Execute UDF function

get_udf_artifacts

Get UDF artifacts and dependencies

list_streams

List all SQL streams (jobs)

get_stream

Get details of a specific stream

create_stream

Create new stream (write mode)

update_stream

Update an existing stream

delete_stream

Delete a stream

start_stream

Start a stream

stop_stream

Stop a stream

execute_query

Execute SQL query and create SSB job

execute_query_with_sampling

Execute query with custom sampling

get_job_status

Get status of a specific SSB job

get_job_sample

Get sample data from a job execution

get_job_sample_by_id

Get sample data from a job by ID

list_jobs_with_samples

List all jobs with their sample information

stop_job

Stop a specific SSB job

execute_job

Execute/restart a job with new SQL

restart_job_with_sampling

Restart job with sampling options

configure_sampling

Configure sampling parameters

list_tables

List all available tables (data sources)

get_table_schema

Get table schema information

create_kafka_table

Create new Kafka data source (local-kafka enforced)

register_kafka_table

validate_kafka_connector

Validate that a connector type is valid for local-kafka

list_udfs

List user-defined functions

get_udf

Get UDF details

list_connectors

List available connectors

get_connector

Get connector details

list_topics

List Kafka topics

get_topic

Get topic details

get_cluster_info

Get cluster information

get_cluster_health

Get cluster health status

get_ssb_info

Get SSB version and system info