teradata-gcfr-mcp-server
Provides tools for querying and monitoring Teradata GCFR operational reporting, including stream status, process execution history, load statistics, transform performance, error logs, SLA compliance, and data lineage.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@teradata-gcfr-mcp-server show me failed processes from yesterday"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
teradata-gcfr-mcp-server
An MCP (Model Context Protocol) server that exposes Teradata GCFR (Global Control Framework Repository) operational reporting as natural-language tools consumable by Claude Desktop, Claude Code, VS Code Copilot Chat, and any other MCP-compatible client. Connect Claude to your Teradata environment and ask questions like "show me failed processes since yesterday" or "what are the slowest streams this week" — without writing SQL.
Prerequisites
Requirement | Notes |
Python 3.11+ | Earlier versions not supported |
Package manager and runner — | |
| Installed automatically by |
Network access to Teradata | Direct TCP to port 1025, or via ODBC gateway |
Related MCP server: redash-mcp
How it works
Server architecture:
Entry point (
server.py) — Initializes the connection pool, registers all tools, applies profile filtering, and starts the MCP server.Connection pool (
db.py) — Thread-safe pooling of Teradata connections with configurable size, overflow, and timeout. Queries have automatic reconnect-once on transient failures.Tool modules (
tools/*.py) — 7 categories of MCP tools:Streams (3 tools): Live stream status and business date tracking
Processes (3 tools): Process execution history and current status
Loads (3 tools): Data ingestion statistics and registration audit
Transforms (5 tools): Transform statistics, performance ranking, and trend analysis
Errors (3 tools): Error log, execution trace, and failed process diagnostics
SLA (2 tools): Service-level agreement compliance reporting
Lineage (2 tools): Data lineage tracing and health checks
Custom tools (
tool_loader.py) — YAML-defined SQL tools loaded fromCONFIG_DIRat startup, allowing site-specific reporting without Python code.
Query execution:
All SQL uses parameterized queries (
?placeholders) to prevent injection.Schema/table names come from
settings.pyconstants, never user input.Per-query timeout enforced via
GCFR_QUERY_TIMEOUT(default 120s).Queries are capped at
GCFR_MAX_ROWS(default 500 rows).Results returned as structured error dicts on failure — no exceptions.
Transport modes:
Transport | Best for | Visibility |
| Claude Desktop, local REPL | Silent (stdout = MCP protocol) |
| Development, debugging, VS Code | Log output on stderr |
| Web dashboards, REST clients | HTTP on configured port/path |
Recent improvements
Query timeout enforcement (2025-04-02)
GCFR_QUERY_TIMEOUTis now wired toteradatasql.connect()at connection initializationQueries that exceed the timeout are interrupted at the database level (no more runaway queries)
Timeout applies to all tool queries uniformly
HTTP mount path support (2025-04-02)
MCP_PATHsetting is now properly passed to FastMCP'smcp.run()callHTTP transports now mount at the configured path (e.g.,
/mcp/→http://127.0.0.1:8001/mcp/)Enables better URL hierarchy and multi-server configurations
Connection pool robustness
Automatic reconnect-once on transient failures (stale connections, temporary network issues)
QueryBand set on all connections for Teradata workload-management attribution
Graceful handling of connection exhaustion with timeout-aware blocking
Quick start
Local development (recommended)
git clone <repo-url>
cd teradata-gcfr-mcp-server
uv sync
cp .env.example .env # Edit with your Teradata credentials
MCP_TRANSPORT=sse uv run teradata-gcfr-mcp-server # Or use stdio for Claude DesktopThe MCP_TRANSPORT defaults to stdio (for Claude Desktop), but sse is useful for debugging
with visible log output on stderr.
Development install
git clone <repo-url>
cd teradata-gcfr-mcp-server
# Install all dependencies including dev extras
uv sync
# Run linting and type checks before making changes
uv run ruff check src/
uv run mypy src/
# Run unit tests (no Teradata connection required)
uv run pytest tests/unit/ -v
# Run the server locally in development mode
MCP_TRANSPORT=sse uv run teradata-gcfr-mcp-serverCopy .env.example to .env and update with your Teradata credentials. The server will use
environment variables automatically.
Verification gate (run before committing):
All three checks must pass with zero errors:
uv run ruff check src/ # Linting
uv run mypy src/ # Type checking (strict)
uv run pytest tests/unit/ -v # Unit tests (76 tests)Configuration reference
All settings are read from environment variables or a .env file in the working directory.
Variable | Type | Default | Description |
| str | (required) |
|
| str |
| Auth mechanism: |
| int |
| Persistent connections in the pool |
| int |
| Extra connections allowed under burst load |
| int |
| Seconds to wait for a free connection |
| str |
| Base view layer — registration/metadata tools |
| str |
| Operational reporting views ( |
| str |
| BKEY/BMAP surrogate-key views |
| str |
| Physical tables — health-check only |
| int |
| Maximum rows any single tool may return |
| int |
| Per-query timeout in seconds (enforced at connection init) |
| str |
|
|
| str |
| (read-only) Bind host for HTTP/SSE — not configurable at runtime |
| int |
| (read-only) Bind port for HTTP/SSE — not configurable at runtime |
| str |
| URL path prefix for HTTP transports |
| str |
| Active tool profile (see Profiles below) |
| str |
| Python logging level |
| str |
| Directory scanned for |
Notes on transport configuration:
MCP_HOSTandMCP_PORTare FastMCP internal settings and cannot be changed at runtime. The server binds to these values but the MCP framework controls the actual binding. Modify them only if you understand the implications.MCP_PATHis properly wired and controls the HTTP mount point (e.g.,/mcp/→http://host:port/mcp/).GCFR_QUERY_TIMEOUTis now wired toteradatasql.connect(), ensuring all queries respect the configured timeout.
Profiles
Profiles limit which tools are exposed to the MCP client. Set via the PROFILE env var or the
--profile CLI flag.
all (default)
Every tool is available.
ops
Focused on live operational monitoring:
gcfr_stream_status, gcfr_current_stream_status, gcfr_stream_business_date,
gcfr_current_process_status, gcfr_process_history, gcfr_process_status_summary,
gcfr_failed_processes, gcfr_error_log, gcfr_execution_log,
gcfr_load_status, gcfr_health_check
performance
Focused on SLA and throughput analysis:
gcfr_sla_process_report, gcfr_sla_stream_report, gcfr_top_slowest_processes,
gcfr_top_slowest_streams, gcfr_data_trend_loads, gcfr_data_trend_transforms,
gcfr_stream_status, gcfr_health_check
lineage
Focused on data lineage and registration audit:
gcfr_data_lineage, gcfr_dataset_registered, gcfr_load_stats,
gcfr_transform_stats, gcfr_health_check
Available MCP tools (22 total)
All tools are read-only queries against GCFR operational views. None modify data.
Streams (3 tools)
gcfr_stream_status— History and completion state for a date rangegcfr_current_stream_status— Real-time stream status (running now)gcfr_stream_business_date— Current, previous, next business date for a stream
Processes (3 tools)
gcfr_process_status_summary— All processes for a business date (completed vs incomplete)gcfr_current_process_status— Real-time process statusgcfr_process_history— Execution history with timing and outcomes
Loads (3 tools)
gcfr_load_status— Which staging tables loaded successfully and row countsgcfr_load_stats— Detailed load statistics (rejections, ET/UV violations, errors)gcfr_dataset_registered— Source datasets registered for processing
Transforms (5 tools)
gcfr_transform_stats— Rows inserted/updated/deleted per processgcfr_top_slowest_processes— Top N slowest processes by elapsed timegcfr_top_slowest_streams— Top N slowest streams by elapsed timegcfr_data_trend_loads— Daily load volume trendsgcfr_data_trend_transforms— Daily transform volume trends
Errors (3 tools)
gcfr_failed_processes— Failed process instances with error detailsgcfr_error_log— Raw error log entries for root cause investigationgcfr_execution_log— Step-level execution trace (debug level only)
SLA (2 tools)
gcfr_sla_process_report— Expected vs actual process timing and SLA compliancegcfr_sla_stream_report— Expected vs actual stream duration and SLA compliance
Lineage (2 tools)
gcfr_data_lineage— Trace target table back to source objectsgcfr_health_check— Verify GCFR databases are reachable
Database naming
GCFR uses two distinct tiers of databases:
Tier | Name pattern | Purpose |
View layer (V) |
| All |
Table layer (T) |
| Physical base tables — referenced only by the health-check |
Never reference GDEV1_GCFR (no T or V suffix) — that database does not exist. All tool
queries target the GDEV1V_* view layer. Only gcfr_health_check touches GDEV1T_GCFR to
verify the physical tables are reachable.
Required Teradata permissions
The server account needs SELECT privilege on the three view-layer databases:
GRANT SELECT ON GDEV1V_GCFR TO <your_user>;
GRANT SELECT ON GDEV1V_OPR TO <your_user>;
GRANT SELECT ON GDEV1V_UTLFW TO <your_user>;
-- For health-check (optional):
GRANT SELECT ON GDEV1T_GCFR TO <your_user>;No INSERT, UPDATE, DELETE, or DDL privileges are required — the server is read-only.
Claude Desktop configuration
Add the following to your claude_desktop_config.json (replace credential values):
{
"mcpServers": {
"teradata-gcfr": {
"command": "uvx",
"args": ["teradata-gcfr-mcp-server"],
"env": {
"DATABASE_URI": "teradata://myuser:mypass@gdev1-host:1025/GDEV1V_GCFR",
"LOGMECH": "TD2",
"GCFR_VIEW_DB": "GDEV1V_GCFR",
"GCFR_OPR_DB": "GDEV1V_OPR",
"GCFR_UTLFW_DB": "GDEV1V_UTLFW",
"GCFR_TABLE_DB": "GDEV1T_GCFR",
"MCP_TRANSPORT": "stdio",
"PROFILE": "all"
}
}
}
}Config file location:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
VS Code / Copilot Chat configuration
Add to your VS Code settings.json or workspace .vscode/mcp.json. The SSE transport is
recommended for VS Code:
{
"mcp": {
"servers": {
"teradata-gcfr": {
"type": "sse",
"url": "http://127.0.0.1:8001/sse",
"env": {}
}
}
}
}Then run the server with:
MCP_TRANSPORT=sse uv run teradata-gcfr-mcp-serverDocker quick start
# Build image
docker build -t gcfr-mcp .
# Run with an .env file
docker run --rm --env-file .env -p 8001:8001 gcfr-mcp
# Or use docker-compose (starts with streamable-http transport)
docker compose upThe docker-compose.yml mounts ./gcfr_custom_tools.yml into the container at
/app/gcfr_custom_tools.yml (read-only). Create this file to add site-specific tools; if it
does not exist, the container starts without custom tools.
Custom tools (YAML)
Add read-only SQL tools without writing Python by placing a *_tools.yml file in CONFIG_DIR
(defaults to ., the current working directory).
Example — gcfr_custom_tools.yml:
tools:
- name: gcfr_my_site_report
description: "Latest 20 stream records for this site"
sql: >
SELECT TOP 20
Stream_Key, Stream_Name, Business_Date, Stream_Status
FROM {gcfr_opr_db}.GCFR_RV_Stream
ORDER BY Business_Date DESCSupported SQL placeholders:
Placeholder | Expands to | Purpose |
|
| Operational reporting views ( |
|
| Base registration/metadata views |
|
| BKEY/BMAP surrogate-key reference data |
Custom tools are zero-argument — they execute their SQL directly with a GCFR_MAX_ROWS row limit applied automatically. Tool names must follow the gcfr_ prefix convention so that profile filtering and naming conventions are consistent.
Sample questions
The following questions work out-of-the-box with Claude once the server is connected:
"Show me all failed processes since yesterday."
"What is the current status of stream 42?"
"Which streams have not completed today's business date?"
"Give me the top 10 slowest processes this week."
"Show the SLA report for process LOAD_CUSTOMER_DAILY from 2024-01-01 to 2024-01-31."
"What datasets are registered in GCFR?"
"List the lineage for target table CUSTOMER_DIM."
"Show me transform statistics for the last 7 days."
"Are the GCFR databases reachable? Run a health check."
"What errors occurred in the execution log today?"
Linting and type checking
# Lint
uv run ruff check src/
# Auto-fix lint issues
uv run ruff check --fix src/
# Type checking (strict)
uv run mypy src/Running tests
Unit tests (no Teradata connection required)
uv run pytest tests/unit/ -vAll database calls are mocked — unit tests run offline.
Integration tests (requires GDEV1 network access)
uv run pytest tests/integration/ -vIntegration tests are not yet implemented. Contributions welcome — see CLAUDE.md for the
pending work list.
Skipping slow tests
uv run pytest tests/unit/ -v -m "not slow"Architecture and design patterns
See CLAUDE.md in the repository for comprehensive developer documentation including:
Async/sync split — Why MCP tool wrappers are async but DB logic is sync
Dynamic date defaults — How to avoid frozen dates in function signatures
Parameterised SQL only — Security model for user input vs schema names
Reconnect-once pattern — Transient failure handling in the connection pool
TOP clause injection — Why and how row limits are applied transparently
Testing patterns — How to mock database calls without hitting Teradata
Custom tool loading — YAML-driven tool registration and placeholder substitution
Profile filtering — How role-based access control works at startup
Design validation
This server was validated against the upstream Teradata/teradata-mcp-server
for architectural best practices and lessons learned. Key differences:
Aspect | This server | Upstream |
Connection layer | Direct teradatasql | SQLAlchemy + teradatasqlalchemy |
DB abstraction | Hand-rolled connection pool | SQLAlchemy QueuePool |
Tool registration | Module-based + YAML | Python (auto-discovery) + YAML + progressive disclosure |
Async strategy |
| Sync blocking in handlers (thread pool implicit) |
Type checking |
| Gradual mypy (strict disabled) |
Testing | 3 per handler (normal/empty/error) | Integration tests against live DB |
Error handling | Structured error dicts | Some handlers may raise |
Database timeout | ✓ Enforced at connection | Optional SQLAlchemy pool timeout |
HTTP path mounting | ✓ Wired to | Configuration-only |
Both implementations are production-ready and differ mainly in scope (GCFR-specific vs general Teradata) and deployment strategy (lightweight vs feature-rich).
Troubleshooting
Symptom | Likely cause | Fix |
| Wrong host/port in | Verify host resolves and port 1025 is reachable; check firewall |
| Missing | Run the |
Tool returns | Query execution failed or timeout | Check |
Query hangs or times out |
| Increase |
Claude Desktop shows no tools | Server not running or wrong transport | Confirm |
SSE transport shows | Server not running or wrong host/port | Verify server is running with |
| Expected — Teradata INTERVAL serialized to string | The |
Custom tools not appearing | Wrong | Set |
Profile filter not working | Tool name doesn't match pattern | Tool names must start with |
Server starts but no output |
| Use |
Available Tools
21 toolsgcfr_current_process_statusA
Show active processes and their current execution step.
Process_State values: 0=started, 1–98=in progress (restart point), 99=complete. Use this to find stuck or long-running processes. Filter by stream_key and/or process_name to narrow results.
Inputs: stream_key, process_name. Returns: result
gcfr_current_stream_statusA
Show streams that are actively running RIGHT NOW.
Use this first when investigating a running or stuck batch. Optionally filter to a specific stream by providing stream_key.
Inputs: stream_key. Returns: result
gcfr_data_lineageA
Trace a target table back to its source objects.
Shows the full lineage chain with edge relationships. Returns: Src_Object_Name_FQ, Src_Kind, Edge_Relationship, Tgt_Object_Name_FQ, Tgt_Kind, Crt_Process_Name. Defaults to today when business_date is not supplied.
Inputs: target_table (required), business_date. Returns: result
gcfr_dataset_registeredA
Show source data sets registered for processing and their file extract status.
Count_Source vs Count_Target reconciliation is here. date_from and date_to default to yesterday and today respectively. Optionally filter by ctl_id.
Inputs: ctl_id, date_to, date_from. Returns: result
gcfr_data_trend_loadsA
Show daily load volume trends — total rows loaded per business date.
Use this to spot unusual volume changes. date_from and date_to default to yesterday and today respectively.
Inputs: date_to, date_from. Returns: result
gcfr_data_trend_transformsA
Show daily transform volume trends by business date.
date_from and date_to default to yesterday and today respectively.
Inputs: date_to, date_from. Returns: result
gcfr_error_logA
Show raw error log entries for root cause investigation.
Includes the calling API and step where the error occurred. Sql_Text (CLOB) is excluded from output — ask separately if needed. date_from and date_to default to yesterday and today respectively. Optionally filter by process_name.
Inputs: date_to, date_from, process_name. Returns: result
gcfr_execution_logA
Show step-level execution trace for detailed process debugging.
Only populated when GCFR is running at debug level 2 or higher. Sql_Text (CLOB) is excluded from output — ask separately if needed. date_from and date_to default to yesterday and today respectively. Optionally filter by process_name and/or stream_key.
Inputs: date_to, date_from, stream_key, process_name. Returns: result
gcfr_failed_processesA
Show failed process instances with full error details.
This is the first tool to use when investigating a batch failure. date_from and date_to default to yesterday and today respectively. Optionally filter by stream_key and/or process_name.
Inputs: date_to, date_from, stream_key, process_name. Returns: result
gcfr_health_checkA
Verify the MCP server can reach both GCFR view databases.
Run this first if tools are returning errors. Returns status, database names, stream_count, and response_time_ms.
Inputs: no named parameters. Returns: result
gcfr_load_statsA
Show staging load statistics — row counts, rejections, ET errors, UV violations.
Key columns: Ctl_Id, File_Id, Business_Date, Process_Name, Rows_Input, Rows_Considered, Rows_Not_Considered, Rows_Rejected, Rows_Inserted, Rows_ET, Rows_UV, Start_Ts, End_Ts, Load_Status. date_from and date_to default to yesterday and today respectively. Optionally filter by ctl_id.
Inputs: ctl_id, date_to, date_from. Returns: result
gcfr_load_statusA
Show which staging tables loaded successfully for a business date, with row counts.
Use this to verify all expected feeds have arrived. Defaults to today when business_date is not supplied. Optionally filter by ctl_id.
Inputs: ctl_id, business_date. Returns: result
gcfr_process_historyB
Show process execution history with timing and outcomes for a date range.
Use this to understand how long processes took and whether they succeeded. date_from and date_to default to yesterday and today respectively when not supplied.
Inputs: date_to, date_from, process_name. Returns: result
gcfr_process_status_summaryA
Show all processes for a business date — completed vs not completed.
If a process did not complete, the error message is included. Use this for a quick end-of-day sign-off check. Defaults to today when business_date is not supplied.
Inputs: business_date. Returns: result
gcfr_sla_process_reportB
Compare expected vs actual process start time, end time, and duration.
Shows whether SLAs were met. SLA_Run_Duration is returned as a formatted string (INTERVAL DAY TO SECOND). date_from and date_to default to yesterday and today respectively.
Inputs: date_to, date_from. Returns: result
gcfr_sla_stream_reportB
Compare expected vs actual stream duration SLAs.
SLA duration fields are returned as formatted strings. date_from and date_to default to yesterday and today respectively.
Inputs: date_to, date_from. Returns: result
gcfr_stream_business_dateA
Show the current, previous, and next business date for a stream.
Use this to understand where a stream's processing date is set and whether it is in sync with the expected calendar date.
Inputs: stream_key (required). Returns: result
gcfr_stream_statusA
Show stream execution history and completion state for a date range.
Use this to find out whether a stream ran successfully, is still running, or failed for a given business date. date_from and date_to default to yesterday and today respectively when not supplied.
Inputs: date_to, date_from, stream_key. Returns: result
gcfr_top_slowest_processesA
Show the N slowest processes by elapsed duration for a business date.
Use this to identify performance bottlenecks. top_n must be between 1 and 50 (default 10). Defaults to today when business_date is not supplied.
Inputs: top_n, business_date. Returns: result
gcfr_top_slowest_streamsB
Show the N slowest streams by elapsed duration.
top_n must be between 1 and 50 (default 10). Defaults to today when business_date is not supplied.
Inputs: top_n, business_date. Returns: result
gcfr_transform_statsA
Show transformation statistics — rows inserted, updated, and deleted per process.
Use this to verify data movement through the warehouse. date_from and date_to default to yesterday and today respectively. Optionally filter by ctl_id.
Inputs: ctl_id, date_to, date_from. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Most tools target a distinct monitoring concern—streams vs processes, current vs historical, load vs transform. A few pairs like load_stats/load_status and process_history/process_status_summary have overlapping row/status information, but descriptions provide enough differentiation.
All tools share the gcfr_ prefix and use snake_case with descriptive subject+report type names (e.g., stream_status, process_history, sla_process_report). Minor structural deviations such as dataset_registered and health_check break the pattern slightly but remain predictable.
21 tools is in the heavy range and each one covers a specific report or query, which is justified by the broad monitoring domain. Still, the count is large enough that an agent may need to scan many similar names.
The tool surface covers the full operational monitoring lifecycle: stream/process status and history, load and transform statistics, failure/error investigation, SLA reporting, performance trends, data lineage, and connectivity health. No obvious dead ends or missing monitoring scenarios are apparent for the stated purpose.
Maintenance
Related MCP Connectors
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Cloud-hosted MCP server for secure AI access to enterprise data sources via CData Connect AI.
Hosted BigQuery MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server implementation that integrates Claude with Salesforce, enabling natural language interactions with Salesforce data and metadata.8MIT
- AlicenseAqualityBmaintenanceMCP server that connects Redash to Claude AI, enabling natural language data queries, dashboard management, and SQL execution.252,645 npm1MIT
- AlicenseAqualityDmaintenanceA database-agnostic MCP server that enables natural language queries to your database through Claude or Copilot, automatically writing and executing SQL.87 npmMIT
- FlicenseNot gradedqualityDmaintenanceEnables natural language interaction with Teradata databases through Claude, allowing data exploration, profiling, and in-database KMeans clustering via MCP.-