Mcp Server Teradata Wlm

Teradata Workload Management (WLM) MCP Server

[](https://www.python.org/downloads/) [](https://modelcontextprotocol.io)

A Model Control Protocol (MCP) server for Teradata Workload Management (WLM) that provides comprehensive monitoring and management capabilities for Teradata systems.

Features

• 41 Management Tools: 28 core monitoring tools + 13 configuration management tools
• 39 MCP Resources: Reference data, templates, ruleset exploration, and workflow guidance
• Full Teradata Connectivity: TD2, LDAP, Kerberos, TDNEGO, JWT authentication
• TLS/SSL Support: ALLOW, PREFER, REQUIRE, VERIFY-CA, VERIFY-FULL modes
• Per-Tool Audit Trail: QueryBand tracking per tool call for workload management
• Async DB Operations: All database calls run in thread pool (non-blocking)
• Connection Resilience: Intelligent retry with exponential backoff and jitter
• Connection Health Monitoring: Automatic health checks and recovery
• OAuth 2.1 Authentication: Optional Keycloak integration with scope-based access control
• Template-Driven Configuration: Pre-built patterns for common TDWM configurations
• Generic Error Messages: No raw database errors leaked to clients

Use Cases

Performance Troubleshooting

Scenario: Identify why queries are running slowly or getting delayed

Tools to use:

1. show_sessions - Identify active sessions and their state
2. identify_blocking - Find sessions causing blocks
3. show_sql_text_for_session - See what SQL is running
4. monitor_amp_load - Check AMP utilization
5. display_delay_queue - See if queries are delayed
6. show_tasm_statistics - Analyze TASM workload distribution

Resources to explore:

• tdwm://summary - Overall system status
• tdwm://throttle-statistics - Current throttle limits and delays

Emergency Response

Scenario: System is overloaded, need to quickly restrict workload

Workflow:

1. Use tdwm://workflow/emergency-throttle resource for step-by-step guide
2. Use tdwm://template/throttle/application-basic for quick throttle pattern
3. create_system_throttle with low concurrency limit
4. enable_throttle to activate
5. activate_ruleset to apply changes immediately
6. Monitor with show_trottle_statistics

Scheduled Maintenance

Scenario: Block user access during maintenance window

Workflow:

1. Use tdwm://workflow/maintenance-window for complete guide
2. Create filter with create_filter targeting all users or specific applications
3. enable_filter + activate_ruleset to block access
4. Perform maintenance
5. disable_filter + activate_ruleset to restore access

Installation

pip install tdwm-mcp

Quick Start

# 1. Install the package
pip install tdwm-mcp

# 2. Configure database connection
export DATABASE_URI="teradata://username:password@hostname/database"

# 3. Start the MCP server
uv run tdwm-mcp

# 4. Test with a simple tool call (via your MCP client)
# Tool: show_sessions

Configuration

All configuration is done via environment variables. See .env.example for a complete reference.

Database Connection

# Connection URL (required)
export DATABASE_URI="teradata://username:password@hostname/database"

Authentication Mechanisms

The server supports all Teradata authentication methods via the DB_LOGMECH environment variable:

TD2 (Default - Username/Password)

export DATABASE_URI="teradata://username:password@hostname/database"
# DB_LOGMECH=TD2 is the default, no need to set explicitly

LDAP

export DATABASE_URI="teradata://@hostname/database"
export DB_LOGMECH=LDAP
export DB_LOGDATA="authcid=user@domain.com password=ldap_password"

| Directory | authcid Format | |-----------|----------------| | Active Directory (Simple) | user@domain.com | | Active Directory (DIGEST-MD5) | DOMAIN\username | | OpenLDAP / Sun DS | username |

Kerberos (KRB5)

export DATABASE_URI="teradata://@hostname/database"
export DB_LOGMECH=KRB5
# Requires valid Kerberos ticket (kinit)

TDNEGO (Token Negotiation)

export DB_LOGMECH=TDNEGO
# Negotiates between TD2, LDAP, KRB5 automatically

JWT (JSON Web Token)

export DATABASE_URI="teradata://@hostname/database"
export DB_LOGMECH=JWT
export DB_LOGDATA="authcid=token_issuer password=jwt_token_string"

TLS/SSL Configuration

# SSL mode: ALLOW, PREFER, REQUIRE, VERIFY-CA, VERIFY-FULL
export DB_SSL_MODE=REQUIRE

# Transport encryption (default: true)
export DB_ENCRYPT_DATA=true

| Mode | Description | |------|-------------| | ALLOW | Try SSL, fall back to plaintext | | PREFER | Prefer SSL, but allow plaintext | | REQUIRE | Require SSL, fail if not available | | VERIFY-CA | Verify CA certificate | | VERIFY-FULL | Verify CA and hostname |

Transport Configuration

# Transport: stdio (default), sse, streamable-http
export MCP_TRANSPORT=stdio
export MCP_HOST=0.0.0.0
export MCP_PORT=8000
export MCP_PATH=/mcp/

CORS Configuration

# Allowed origins (default: * for all)
export CORS_ALLOWED_ORIGINS="https://your-app.example.com"

Retry Configuration

# Tool-level retry
export TOOL_MAX_RETRIES=2
export TOOL_RETRY_INITIAL_DELAY=0.5
export TOOL_MAX_RETRY_DELAY=2.0

# Connection-level retry
export DB_MAX_RETRIES=3
export DB_INITIAL_BACKOFF=1.0
export DB_MAX_BACKOFF=30.0

OAuth 2.1 (Optional)

export OAUTH_ENABLED=true
export KEYCLOAK_URL=https://your-keycloak-server.com
export KEYCLOAK_REALM=your-realm
export KEYCLOAK_CLIENT_ID=tdwm-mcp
export KEYCLOAK_CLIENT_SECRET=your-secret
export OAUTH_RESOURCE_SERVER_URL=https://your-mcp-server.com
export OAUTH_REQUIRED_SCOPES=tdwm:read,tdwm:monitor
export OAUTH_REQUIRE_HTTPS=true

Scopes: tdwm:read, tdwm:write, tdwm:admin, tdwm:query, tdwm:monitor, tdwm:workload

Docker

All docker-compose files use environment variable expansion - no credentials are hardcoded. Create a .env file from .env.example before running.

# Basic SSE transport
cp .env.example .env
# Edit .env with your credentials
docker compose up -d

# With OAuth (Keycloak)
docker compose -f docker-compose.oauth.yml up -d

# SSE on alternate port
docker compose -f docker-compose.sse.yml up -d

Connection Resilience

The server includes automatic retry logic for handling Teradata connection failures.

How It Works

All tools are wrapped with an intelligent retry decorator that:

1. Detects Connection Errors - Distinguishes between connection failures (retryable) and SQL errors (not retryable)
2. Smart Retry Logic - Based on operation safety:

• Read operations (queries, monitoring): Up to 2 retries
• Write operations (creates, updates): Up to 1 retry
• Dangerous operations (deletes, aborts): No automatic retry

1. Exponential Backoff - Progressive delays (0.5s -> 1.0s -> 2.0s) with jitter
2. Health Monitoring - Connection health checks every 5 minutes via SELECT 1

Detected Teradata Errors

• Network timeouts and disconnections
• Session disconnections (Error 3126)
• Transaction aborts due to TDWM termination (Error 2631)
• Session limit exceeded (Error 8017)
• Communication link failures

Per-Tool QueryBand

Every tool call sets a transaction-level QueryBand for audit and workload management:

SET QUERY_BAND = 'ApplicationName=TDWM_MCP;ToolName=show_sessions;Transport=stdio;' FOR TRANSACTION

This enables Teradata administrators to track which MCP tool initiated each query.

Architecture

+------------------------------------------------------------+
|                    MCP Client                               |
|              (Claude Desktop, etc.)                         |
+----------------------------+-------------------------------+
                             | MCP Protocol
+----------------------------v-------------------------------+
|                TDWM MCP Server                              |
|  +------------------------------------------------------+  |
|  |   server.py - FastMCP App + Settings                 |  |
|  +------------------------------------------------------+  |
|                             |                               |
|  +------------------------------------------------------+  |
|  |   fnc_common.py                                      |  |
|  |   - Connection Manager   - QueryBand helper          |  |
|  |   - get_connection()     - _set_queryband()          |  |
|  |   - @with_connection_retry decorator                 |  |
|  +------+-------------------+---------------------------+  |
|         |                   |                               |
|  +------v------+  +--------v---------+  +--------------+   |
|  | fnc_tools   |  | fnc_tools_       |  | fnc_         |   |
|  | .py         |  | priority1.py     |  | resources.py |   |
|  |             |  |                  |  |              |   |
|  | 28 core     |  | 13 config        |  | 39           |   |
|  | monitoring  |  | management       |  | resources    |   |
|  | tools       |  | tools            |  |              |   |
|  +------+------+  +--------+---------+  +------+-------+   |
|         |                  |                    |            |
|  +------v------------------v--------------------v--------+  |
|  |   settings.py      queryband.py     retry_utils.py   |  |
|  |   connection_manager.py             tdsql/tdsql.py    |  |
|  +-------------------------------------------------------+  |
+----------------------------+---------------------------------+
                             | teradatasql (TD2/LDAP/KRB5/JWT)
+----------------------------v---------------------------------+
|                 Teradata Database                             |
|               (TDWM/TASM System)                             |
+--------------------------------------------------------------+

Module Organization

| Module | Purpose | |--------|---------| | settings.py | Frozen Settings dataclass - all env vars read once at startup | | queryband.py | Per-tool QueryBand builder with value sanitization | | tdsql/tdsql.py | Teradata connection wrapper with LOGMECH/TLS support | | connection_manager.py | Connection health monitoring, retry, reconnection | | retry_utils.py | @with_connection_retry() decorator, error detection | | fnc_common.py | Shared utilities, connection access, queryband helper | | fnc_tools.py | 28 core monitoring tools (async, with queryband) | | fnc_tools_priority1.py | 13 configuration management tools | | fnc_resources.py | 39 MCP resource handlers | | resource_reference.py | Reference data resources (8) | | resource_templates.py | Configuration templates (13) | | resource_queries.py | Ruleset exploration queries (8) | | server.py | FastMCP app, transport setup, initialization | | oauth_context.py | OAuth scope-based authorization | | auth/ | OAuth 2.1 config, middleware, endpoints, metadata |

Dependency Graph

settings.py, queryband.py, retry_utils.py (no internal deps)
    |
tdsql/tdsql.py (uses settings)
    |
connection_manager.py (uses tdsql, queryband)
    |
fnc_common.py (uses connection_manager, queryband, retry_utils)
    |
    +-- fnc_tools_priority1.py (uses fnc_common)
    |       |
    +-- fnc_tools.py (uses fnc_common + fnc_tools_priority1)
    |       |
    +-- fnc_resources.py (uses fnc_common)
            |
        server.py (uses all above + settings + auth)

Available Tools

Session Management

• show_sessions - Show my active sessions
• showsqlstepsforsession - Show SQL execution steps for a specific session
• showsqltextforsession - Show SQL text for a specific session
• abortsessionsuser - Abort all sessions for a specific user
• identify_blocking - Identify users causing blocking situations

Query Band and Monitoring

• monitorsessionquery_band - Monitor query band for a specific session
• listqueryband - List query bands by type (TRANSACTION, PROFILE, SESSION, or ALL)
• showquerylog - Show query log for a specific user

System Resource Monitoring

• showphysicalresources - Monitor system physical resources
• monitorampload - Monitor AMP (Access Module Processor) load
• monitor_awt - Monitor AWT (AMP Worker Task) resources
• monitor_config - Monitor virtual configuration

Workload Management

• listactiveWD - List active workloads (WD)
• list_WD - List all workloads (WD)
• showtdwmsummary - Show workloads summary information

Delay Queue Management

• listdelayedrequest - List all delayed queries
• abortdelayedrequest - Abort delayed requests for a specific session
• displaydelayqueue - Display delay queue details by type (WORKLOAD, SYSTEM, UTILITY, or ALL)
• releasedelayqueue - Release delayed requests for a session or user

Throttle and Performance

• showtrottlestatistics - Show throttle statistics (ALL, QUERY, SESSION, WORKLOAD)
• listutilitystats - List statistics for utility usage on the system

System Information

• showcodlimits - Show COD (Capacity On Demand) limits
• showtopusers - Show users consuming the most resources
• showswevent_log - Show system software event logs (OPERATIONAL or ALL)

TASM (Teradata Active System Management)

• tdwmlistclasification - List classification types for workload (TASM) rules
• showtasmstatistics - Show TASM performance statistics
• showtasmeven_history - Show TASM event history
• showtasmrulehistoryred - Show what caused the system to enter RED state

Configuration Management

Throttle Management

• createsystemthrottle - Create system-level throttle with concurrency limits
• modifythrottlelimit - Dynamically adjust throttle concurrency limits
• delete_throttle - Remove throttle definition
• enable_throttle - Activate throttle rule
• disable_throttle - Deactivate throttle rule

Filter Management

• create_filter - Create filter to block/reject queries
• delete_filter - Remove filter definition
• enable_filter - Activate filter rule
• disable_filter - Deactivate filter rule

Rule Management

• addclassificationto_rule - Add classification criteria to any rule
• addsubcriteriato_target - Add sub-criteria (e.g., FTSCAN for TABLE)
• activate_ruleset - Apply all pending changes to make them live
• list_rulesets - List all available rulesets

Available Resources

Reference Data Resources

• tdwm://reference/classification-types - All 31 classification types with categories
• tdwm://reference/classification-types/{category} - Filter by category
• tdwm://reference/operators - Classification operators (I, O, IO)
• tdwm://reference/subcriteria-types - Sub-criteria types (FTSCAN, MINSTEPTIME, etc.)
• tdwm://reference/actions - Filter action types (E=Exception, A=Abort)
• tdwm://reference/throttle-types - Throttle types (DM, M)
• tdwm://reference/states - TASM system states (GREEN, YELLOW, ORANGE, RED)
• tdwm://reference/catalog - Comprehensive catalog of all reference resources

Configuration Templates

• tdwm://templates/throttle - List all throttle templates
• tdwm://template/throttle/{template_id} - Specific throttle template
• tdwm://templates/filter - List all filter templates
• tdwm://template/filter/{template_id} - Specific filter template
• tdwm://templates/catalog - Templates catalog

Ruleset Exploration

• tdwm://rulesets - List all available rulesets
• tdwm://system/active-ruleset - Get currently active ruleset name
• tdwm://ruleset/{ruleset_name} - Detailed ruleset information
• tdwm://ruleset/{name}/throttles - List throttles in ruleset
• tdwm://ruleset/{name}/throttle/{throttle_name} - Throttle details
• tdwm://ruleset/{name}/filters - List filters in ruleset
• `td

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: teradata-labs
• Source: teradata-labs/mcp-server-teradata-wlm
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.