Teradata Workload Management (WLM) MCP Server
A Model Control Protocol (MCP) server for Teradata Workload Management (WLM) that provides comprehensive monitoring and management capabilities for Teradata systems.
Power your agent
Install from the publisher. Not a PlugMCP endpoint.
Host a copy with our keys and logs.
No packaged release in the registry yet. Follow the repository README.
Remote URL or a command on your machine? How the two installs differ
Run on PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
LaunchScenario: Identify why queries are running slowly or getting delayed
Tools to use:
show_sessions - Identify active sessions and their stateidentify_blocking - Find sessions causing blocksshow_sql_text_for_session - See what SQL is runningmonitor_amp_load - Check AMP utilizationdisplay_delay_queue - See if queries are delayedshow_tasm_statistics - Analyze TASM workload distributionResources to explore:
tdwm://summary - Overall system statustdwm://throttle-statistics - Current throttle limits and delaysScenario: System is overloaded, need to quickly restrict workload
Workflow:
tdwm://workflow/emergency-throttle resource for step-by-step guidetdwm://template/throttle/application-basic for quick throttle patterncreate_system_throttle with low concurrency limitenable_throttle to activateactivate_ruleset to apply changes immediatelyshow_trottle_statisticsScenario: Block user access during maintenance window
Workflow:
tdwm://workflow/maintenance-window for complete guidecreate_filter targeting all users or specific applicationsenable_filter + activate_ruleset to block accessdisable_filter + activate_ruleset to restore accesspip install tdwm-mcp
# 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
All configuration is done via environment variables. See .env.example for a complete reference.
# Connection URL (required)
export DATABASE_URI="teradata://username:password@hostname/database"
The server supports all Teradata authentication methods via the DB_LOGMECH environment variable:
export DATABASE_URI="teradata://username:password@hostname/database"
# DB_LOGMECH=TD2 is the default, no need to set explicitly
export DATABASE_URI="teradata://@hostname/database"
export DB_LOGMECH=LDAP
export DB_LOGDATA="[email protected] password=ldap_password"
export DATABASE_URI="teradata://@hostname/database"
export DB_LOGMECH=KRB5
# Requires valid Kerberos ticket (kinit)
export DB_LOGMECH=TDNEGO
# Negotiates between TD2, LDAP, KRB5 automatically
export DATABASE_URI="teradata://@hostname/database"
export DB_LOGMECH=JWT
export DB_LOGDATA="authcid=token_issuer password=jwt_token_string"
# SSL mode: ALLOW, PREFER, REQUIRE, VERIFY-CA, VERIFY-FULL
export DB_SSL_MODE=REQUIRE
# Transport encryption (default: true)
export DB_ENCRYPT_DATA=true
# 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/
# Allowed origins (default: * for all)
export CORS_ALLOWED_ORIGINS="https://your-app.example.com"
# 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
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
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
The server includes automatic retry logic for handling Teradata connection failures.
All tools are wrapped with an intelligent retry decorator that:
SELECT 1Every 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.
+------------------------------------------------------------+
| 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) |
+--------------------------------------------------------------+
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)
tdwm://reference/classification-types - All 31 classification types with categoriestdwm://reference/classification-types/{category} - Filter by categorytdwm://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 resourcestdwm://templates/throttle - List all throttle templatestdwm://template/throttle/{template_id} - Specific throttle templatetdwm://templates/filter - List all filter templatestdwm://template/filter/{template_id} - Specific filter templatetdwm://templates/catalog - Templates catalogtdwm://rulesets - List all available rulesetstdwm://system/active-ruleset - Get currently active ruleset nametdwm://ruleset/{ruleset_name} - Detailed ruleset informationtdwm://ruleset/{name}/throttles - List throttles in rulesettdwm://ruleset/{name}/throttle/{throttle_name} - Throttle detailstdwm://ruleset/{name}/filters - List filters in rulesettdwm://ruleset/{name}/filter/{filter_name} - Filter detailstdwm://ruleset/{name}/pending-changes - Check pending changestdwm://workflows - List all available workflowstdwm://workflow/create-throttle - Complete throttle creation workflowtdwm://workflow/create-filter - Complete filter creation workflowtdwm://workflow/maintenance-window - Enable/disable filters for maintenancetdwm://workflow/emergency-throttle - Quick emergency response workflowtdwm://workflow/modify-existing-throttle - Modify existing throttle workflowtdwm://sessions, tdwm://workloads, tdwm://active-workloads, tdwm://summarytdwm://delayed-queries, tdwm://throttle-statistics, tdwm://physical-resourcestdwm://amp-load, tdwm://classification-typesawait call_tool("show_sessions")
await call_tool("show_sql_text_for_session", {"sessionNo": 1234})
await call_tool("show_sql_steps_for_session", {"sessionNo": 1234})
await call_tool("create_system_throttle", {
"ruleset_name": "MyFirstConfig",
"throttle_name": "ETL_THROTTLE",
"description": "Limit ETL workload concurrency",
"throttle_type": "DM",
"limit": 5,
"classification_criteria": [
{"description": "ETL App", "type": "APPL", "value": "ETL_APP", "operator": "I"}
]
})
await call_tool("create_filter", {
"ruleset_name": "MyFirstConfig",
"filter_name": "MAINTENANCE_BLOCK",
"description": "Block non-critical queries during maintenance",
"classification_criteria": [
{"description": "Reporting Users", "type": "USER", "value": "reporting_user", "operator": "I"}
],
"action": "E"
})
# 1. Read template
template = await read_resource("tdwm://template/throttle/application-basic")
# 2. Get active ruleset
active = await read_resource("tdwm://system/active-ruleset")
# 3. Create throttle using template structure
await call_tool("create_system_throttle", { ... })
# 4. Activate
await call_tool("activate_ruleset", {"ruleset_name": "MyFirstConfig"})
# 5. Verify
result = await read_resource("tdwm://ruleset/MyFirstConfig/throttle/MY_THROTTLE")
obfuscate_password()${VAR} expansion - no real credentials in version control? placeholders)CALL ... (?, ?, ?) patternMonitorSQLSteps / MonitorSQLTextOAUTH_REQUIRE_HTTPSasyncio.to_thread() (event loop never blocked)asyncio.Lock() to prevent concurrent reconnection racesFOR TRANSACTION (not session-level, no cross-tool leakage)tdwm-mcp/
+-- src/tdwm_mcp/
| +-- __init__.py
| +-- server.py # FastMCP app and initialization
| +-- settings.py # Frozen Settings dataclass
| +-- queryband.py # Per-tool QueryBand builder
| +-- fnc_common.py # Shared utilities & connection management
| +-- fnc_tools.py # Core monitoring tools (28 tools)
| +-- fnc_tools_priority1.py # Configuration management (13 tools)
| +-- fnc_resources.py # Resource routing (39 resources)
| +-- fnc_prompts.py # MCP prompts
| +-- retry_utils.py # Retry decorator & error detection
| +-- connection_manager.py # Connection health management
| +-- resource_reference.py # Reference data resources
| +-- resource_templates.py # Configuration templates
| +-- resource_queries.py # Ruleset exploration queries
| +-- tdwm_static.py # Static reference data
| +-- oauth_context.py # OAuth scope-based authorization
| +-- tdsql/
| | +-- __init__.py
| | +-- tdsql.py # Teradata SQL wrapper (LOGMECH/TLS)
| +-- auth/
| +-- config.py # OAuth configuration
| +-- middleware.py # JWT validation middleware
| +-- endpoints.py # OAuth HTTP endpoints
| +-- metadata.py # Protected resource metadata
+-- docker-compose.yml # Basic SSE transport
+-- docker-compose.oauth.yml # With Keycloak integration
+-- docker-compose.sse.yml # SSE on alternate port
+-- Dockerfile
+-- .env.example # Environment variable reference
+-- pyproject.toml
+-- uv.lock
+-- README.md
# In fnc_tools.py
@with_connection_retry()
async def my_new_tool(param1: str) -> ResponseType:
"""Description of what the tool does."""
tdconn = await get_connection()
def _run():
_set_queryband(tdconn, "my_new_tool")
cur = tdconn.cursor()
rows = cur.execute("SELECT * FROM my_table WHERE col1 = ?", [param1])
return format_text_response(list(rows.fetchall()))
try:
return await asyncio.to_thread(_run)
except ConnectionError:
raise
except Exception as e:
logger.error(f"Error in my_new_tool: {e}")
return format_error_response("Failed to execute. Check server logs for details.")
# Register in handle_list_tools() and handle_tool_call()
Key patterns:
asyncio.to_thread(_run) (non-blocking)_set_queryband(tdconn, "tool_name") for audit trailConnectionError for retry decoratorstr(e))uv sync
export DATABASE_URI="teradata://user:pass@host/db"
uv run tdwm-mcp
# Test with MCP Inspector
npx @modelcontextprotocol/inspector uv run tdwm-mcp
teradatasql>=20.0.0.30 - Teradata SQL drivermcp[cli]>=1.12.3 - Model Control Protocol frameworkfastapi>=0.115.12 - HTTP framework for SSE/streamable-httppydantic>=2.11.4 - Data validationuvicorn>=0.34.2 - ASGI serverpyjwt[crypto]>=2.8.0 - JWT token handlingauthlib>=1.2.0 - OAuth 2.1 clientaiohttp>=3.9.0 - Async HTTP for token introspectionhttpx>=0.24.0 - HTTP clientTeradata Workload Management MCP server
Tools
No tool list yet. Remote servers get one after the first health check.
FAQ
Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.
No required environment variable is listed on this record.
Tdwm runs locally over stdio.
Last checked 2026-10-28. Teradata Workload Management MCP server