Teradata MCP Server

# Customizing the MCP Server: Semantic Layers > **📍 Navigation:** [Documentation Home](../README.md) | [Server Guide](../README.md#-server-guide) | [Getting started](GETTING_STARTED.md) | [Architecture](ARCHITECTURE.md) | [Installation](INSTALLATION.md) | [Configuration](CONFIGURATION.md) | [Security](SECURITY.md) | [<u>**Customization**</u>](CUSTOMIZING.md) | [Client Guide](../client_guide/CLIENT_GUIDE.md) The Teradata MCP server enables rapid creation of domain-focused semantic layers by allowing you to declaratively define custom tools, prompts, cubes, and glossary terms. No code change needed, you can customize the server by placing YAML files in your current working directory. This approach empowers admins and data teams to tailor the MCP experience to specific business domains—without writing Python code or modifying the server itself. ## Key principles - **Domain Focus:** Build MCP servers that speak your users' language and provide business-relevant tools and explanations. - **Controlled Access:** Predefine queries, aggregations, and resources to ensure correctness, security, and optimal resource utilization. - **Declarative Workflow:** All customization is done via YAML—no code changes required. Admins can add, update, or remove domain logic by editing a single file. - **Trustworthy Outcomes:** By specifying queries and logic up front, you avoid the risks of LLMs repeatedly "guessing" at database structure, ensuring reliable, consistent and auditable results. ### Semantic Layer A semantic layer in this context is a collection of custom tools, prompts, cubes, and glossary terms focused on a specific business domain (e.g., sales, finance, HR). It provides: - **Custom Tools:** Parameterized SQL queries exposed as callable MCP tools. - **Prompts:** Predefined user prompts for natural language interactions. - **Cubes:** Aggregation templates for business metrics, with dimensions and measures. - **Glossary:** Domain-specific terms, definitions, and synonyms, automatically enriched from cubes and tools. - **Profiles:** Named sets of tools, prompts, and resources that enable domain-specific server instantiations. ### Declarative Specification All custom objects can be defined in a YAML file (e.g., `sales_objects.yml`, `finance_objects.yml`). The file is a dictionary keyed by object name, with each entry specifying its type and details: ```yaml sales_by_region: type: cube description: Sales metrics by region and product sql: | SELECT region, product, amount AS total_sales FROM sales_data dimensions: region: description: Sales region expression: region product: description: Product name expression: product measures: total_sales: description: Total sales amount expression: SUM(amount) get_top_customers: type: tool description: Get top N customers by sales sql: | SELECT customer, SUM(amount) AS total FROM sales_data GROUP BY customer ORDER BY total DESC LIMIT %(limit)s parameters: limit: description: Number of top customers to return sales_analyst: type: prompt description: Customer sales analysis prompt prompt: "You are a helpful sales data analyst, you make sure that all your statements are backed by actual data and are ready to share details of your analysis." glossary: type: glossary customer: definition: A person or company that purchases goods or services. synonyms: - client - buyer ``` ## Configuration Files and Loading The server uses a **layered configuration system** that loads and merges configurations from multiple sources. See the [Configuration Guide](CONFIGURATION.md#layered-configuration-strategy) for full details. ### Configuration Directory You can specify a custom configuration directory using the `--config_dir` parameter or `CONFIG_DIR` environment variable: ```bash # Using command line teradata-mcp-server --config_dir /path/to/my/config --profile sales # Using environment variable export CONFIG_DIR=/path/to/my/config teradata-mcp-server --profile sales ``` **Default:** If not specified, the current working directory is used. ### Profiles Configuration **Default profiles** are packaged with the server installation in `src/teradata_mcp_server/config/profiles.yml`. You can override or extend these by creating a `profiles.yml` file in your **configuration directory**. The server uses a **simple override strategy**, so your custom `profiles.yml` can: - Add new profiles - Override existing profiles entirely (top-level keys are replaced completely) Each profile defines which tools, prompts, and resources are enabled for a given context (e.g., user group, domain, or use case). Profiles use regular expression patterns to match tool, prompt, and resource names, allowing flexible grouping and reuse. **Example `profiles.yml` in your config directory:** ```yaml sales: tool: - sales_.* prompt: - sales_.* resource: - sales_.* dba: tool: - dba_.* - base_.* - sec_.* prompt: - dba_.* ``` **Configuration loading priority:** 1. **Packaged defaults** - Built-in profiles shipped with the package 2. **Config directory** - Your `profiles.yml` in the config directory (top-level keys replace packaged profiles) ### Running with Profiles You can run the MCP server with the `--profile` command-line argument or the `PROFILE` environment variable to select a profile at startup. If the profile is unspecified or set to `all`, all tools, resources, and prompts are loaded by default. **Examples:** ```bash # PyPI installation teradata-mcp-server --profile dba # Development build uv run teradata-mcp-server --profile sales ``` ## Custom Objects Implementation Details ### Custom Objects Loading The server loads custom objects (tools, cubes, prompts, glossaries) from multiple sources: **Configuration loading priority:** 1. **Packaged defaults** - Built-in objects from `src/tools/*/*.yml` (shipped with package) 2. **Config directory** - Any `*.yml` files in your config directory (overrides packaged objects by name) **File naming:** Custom object files should be named `*.yml` (e.g., `sales_objects.yml`, `finance_objects.yml`, `my_custom_tools.yml`). The special config files (`profiles.yml`, `chat_config.yml`, `rag_config.yml`, `sql_opt_config.yml`) are handled separately using the layered configuration system. ### Supported Object Types and Attribute Rules Each entry in the YAML file is keyed by its name and must specify a `type`. Supported types and their required/optional attributes: #### Tool - **Required:** - `type`: Must be `tool` - `sql`: SQL query string (it can be a prepared statement with parameters) - **Optional:** - `parameters`: Dictionary of parameter name (key) and properties (dictionary with `description`, `default`, `type_hint`}) - if used in the sql - `description`: Text description of the tool #### Cube - **Required:** - `type`: Must be `cube` - `sql`: SQL base query - `dimensions`: Dictionary of dimension definitions (each with `expression`) - `measures`: Dictionary of measure definitions (each with `expression`) - **Optional:** - `description`: Text description of the cube - `parameters`: Dictionary of parameter name (key) and properties (dictionary with `description`, `default`, `type_hint`}) - if used in the sql #### Prompt - **Required:** - `type`: Must be `prompt` - `prompt`: Text of the prompt - **Optional:** - `parameters`: Dictionary of parameter name (key) and definitions (value) - if used in the prompt - `description`: Text description of the prompt #### Glossary - **Required:** - `type`: Must be `glossary` - Each glossary term must have a `definition` - **Optional:** - `synonyms`: List of synonyms for the term ### Dynamic Registration and Glossary Enrichment - All objects are registered dynamically at server startup—no code changes required. - You can add, update, or remove tools, cubes, prompts, or glossary terms by creating/editing YAML files in your **config directory** and restarting the server. - Config directory files override packaged defaults by object name, so you can customize existing objects or add new ones. - The server will register each tool, prompt, and cube using the dictionary key as its name. - Glossary terms are automatically enriched with references from cubes and tools. ### Quick Start for Customization 1. **Install from PyPI:** `pip install teradata-mcp-server` 2. **Create config directory:** `mkdir my-teradata-config` 3. **Create custom objects:** Add your `*.yml` files (e.g., `my_tools.yml`) to the config directory 4. **Optionally customize profiles:** Create `profiles.yml` in config directory to override default profiles 5. **Run server:** `teradata-mcp-server --config_dir my-teradata-config --profile my_profile` The server will automatically load packaged defaults plus your custom configurations from the config directory. ## Best Practices - **Organize by domain:** Use separate YAML files for each business domain (e.g., `sales_tools.yml`, `finance_metrics.yml`) - **Use descriptive names:** Clear, descriptive names for each tool, cube, and prompt help users understand their purpose - **Document everything:** Add descriptions to all parameters, dimensions, and measures - **Config directory approach:** Create a dedicated directory for your custom configurations and use `--config_dir` to point to it - **Version control:** Keep your custom YAML files in version control for change tracking - **Test profiles:** Create profiles that match your user groups' needs and permissions ## Examples ### Working Directory Structure ``` my-teradata-config/ ├── profiles.yml # Custom profiles (optional) ├── sales_objects.yml # Sales domain tools and cubes ├── finance_metrics.yml # Finance domain objects └── hr_tools.yml # HR domain tools ``` ### Complete Example See the provided [`custom_objects.yml`](../custom_objects.yml) in the repository for a complete working example. ### Running with Custom Configuration ```bash # Run server with config directory and profile teradata-mcp-server --config_dir my-teradata-config --profile sales # Server automatically loads (layered): # 1. Packaged defaults (from installation) # 2. Your custom YAML files (from config directory) # 3. Your custom profiles.yml (if present, top-level keys override packaged) ```