Skip to content

Model Context Protocol (MCP) & AI Agent Integration

The Model Context Protocol (MCP) is an open standard that allows autonomous AI agents and desktop assistants (such as Claude Desktop, Cursor IDE, or custom LangChain / LlamaIndex agents) to interact with VDA's enterprise metadata, lineage graph, data quality engine, and SQL execution services.

1. Generating an API Key for MCP

To authenticate an external AI agent:

  1. In the VDA portal, click your user avatar and select API Keys & Tokens.
  2. Click Generate New Key.
  3. Configure the token parameters:
  4. Name: e.g., Claude Desktop - MacBook Pro.
  5. Expiration: 30, 90, or 365 days.
  6. Role Binding: Tokens inherit your corporate Keycloak roles by default.
  7. Optional Scope Restriction: Limit the token to specific datasources (e.g. datasource:retail_banking).
  8. Click Generate and securely copy the generated key (vda_...).

[!WARNING] The full token is displayed only once. Store it in a secure password manager or credential vault.

2. Connecting Claude Desktop

Open your Claude Desktop configuration file: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the VDA MCP Server entry under mcpServers:

{
  "mcpServers": {
    "vda-enterprise": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://vda.company.internal/api/v2/mcp/sse?token=YOUR_VDA_API_KEY"
      ]
    }
  }
}

Restart Claude Desktop. A hammer icon (🔨) will appear in the bottom-right corner displaying all enabled VDA tools.

3. Connecting Cursor IDE

  1. In Cursor, open Settings (Cmd + , or Ctrl + ,) and navigate to Features > MCP Servers.
  2. Click + Add New MCP Server.
  3. Configure:
  4. Name: vda-metadata
  5. Type: sse
  6. URL: https://vda.company.internal/api/v2/mcp/sse?token=YOUR_VDA_API_KEY
  7. Click Save. Cursor's AI Composer will now automatically invoke VDA tools when answering database questions or generating migration scripts.

4. Dual-Layer Security & Dynamic Tool Filtering

When an AI agent connects via MCP, VDA enforces dual-layer security:

flowchart TD
    Agent["AI Agent (Claude / Cursor)"] -->|1. ListToolsRequest| Gateway["MCP Gateway"]
    Gateway --> PBAC1{"PBAC Role Filter"}
    PBAC1 -->|Hide Restricted Tools| ToolList["Visible Tool List (Scoped to Role)"]

    Agent -->|2. CallToolRequest| Exec["Tool Execution Engine"]
    Exec --> PBAC2{"AST & Column PBAC Firewall"}
    PBAC2 -->|Validate Scope & Mask Columns| DB[("Enterprise Database")]
    DB --> FilteredRes["Masked / Safe Result"]
    FilteredRes --> Agent
  1. Tool Listing Filter: Agents only see tools that match the caller's permissions (e.g., if a user lacks pipeline management access, pipeline mutation tools are omitted from tools/list).
  2. Execution-Time AST Interception: When the agent calls execute_text_to_sql or preview_data_asset, the query AST is inspected. Any denied columns are blocked or masked before results are returned to the agent.

5. What Can AI Agents Do With VDA?

Equipped with VDA's 91 MCP tools, an agent can autonomously: - Discover relevant datasets based on business questions (search_data_assets, find_tables_by_column). - Explain and generate complex SQL queries (generate_text_to_sql, execute_text_to_sql). - Trace end-to-end data lineage (get_asset_lineage, get_column_lineage, get_upstream_sources). - Assess change impact (get_downstream_impact). - Profile and validate data quality (get_column_profiles, run_expectation_suite). - Design source-to-target mappings (create_ssm_mapping, resolve_join_path).

[!NOTE] For the complete reference of all 91 tools, see the MCP Comprehensive Specification.