Connecting and Using VDM with an AI Assistant (MCP)

VDM’s MCP integration lets you work with VDM from a compatible AI assistant, such as Codex or Claude Code. You can ask the assistant to explore an approved database, prepare queries, build Finished Reports and Visualize dashboards, reuse parameters, and prepare Scheduler jobs and appointments. The assistant uses VDM’s native tools to carry out your requests and save files that you can open in VDM.

MCP stands for Model Context Protocol. In this integration, VDM provides the tools and your connected assistant interprets your requests. This is a separate connection from the Ask Bridgit and Talk to Bridgit conversations inside VDM.

Important: Source database queries are read-only. However, enabled profiles also provide tools that can save or change native VDM content, including Knowledge, parameter-library definitions, job files and calendar appointments. Enabling a profile provides more than schema browsing.

In this guide: Before You Begin · Step-by-Step Setup · What You Can Do · Queries and Parameters · Knowledge · Finished Reports and Visualize · Jobs and Scheduling · Saved Files · Maintenance · Troubleshooting

Before You Begin

• Use a VDM build that includes Settings > MCP. If MCP is missing, contact BridgeWorks about the build available to your organization.
• Have a working VDM Connection Profile and permission to read the information you intend to use. Your assistant needs the profile’s name, not its database password.
• Use an assistant client that supports Streamable HTTP MCP and environment-backed bearer authentication. The client must be able to reach VDM’s local endpoint on the Windows computer running VDM.
• Follow your organization’s rules for sharing database metadata, saved Knowledge and query results with an AI service. Choose profiles and requests accordingly.
• Keep VDM open while MCP is in use. Starting VDM’s Scheduler service is not required just to connect an assistant to MCP.

VDM’s endpoint is local to the computer. Pasting its address into a cloud-only chat service does not by itself give that service access to your computer. Use a compatible local client; do not expose the MCP port publicly as a setup workaround.

Your assistant uses its own model access and account. Ordinary MCP query, report, dashboard and job-authoring tools do not require VDM’s Bridgit OpenAI API key. Optional embedding services and later execution of Scheduler AI analysis have separate requirements described below.

The screenshots use the demonstration Connection Profile ABCLocal. Select your own approved profile when following the instructions. The illustrated session has no saved Knowledge examples; missing examples do not prevent setup.

Step-by-Step Setup

1. Open MCP in VDM

1. Open VDM.
2. Select Settings in the main navigation.
3. Select MCP, below Profiles, in the left navigation.
4. On the VDM MCP Server window, select the Setup tab.

MCP appears below Profiles in Settings.

The Home ribbon is organized into four numbered groups: 1. Set Environment, 2. Enable Profiles, 3. Start MCP and 4. Connect Your Agent. The checklist highlights the next incomplete step.

The Setup tab before a profile is enabled. This example already has matching Windows environment values. Select any screenshot to view it at full size.

2. Set the Windows Environment

1. Read the environment status at the bottom of the window. It shows Windows user environment and the states of VDM_MCP_URL and VDM_MCP_API_KEY.
2. If setup is missing or mismatched, select Set Environment on the Home ribbon.
3. Wait for the setup confirmation. VDM sets the local MCP address and authentication key in your Windows user environment.
4. Confirm the status is green and reports Ready. The first checklist step should also show Ready.

If the values already match, Set Environment is disabled and you can continue. You do not need to enter a key manually or run PowerShell. If VDM cannot recover an available matching key, the explicit Set Environment action provisions a replacement; existing clients then need to restart with the new value.

Keep the key private: Do not paste its value into chat, screenshots, configuration examples or support requests. Copy Agent Setup includes variable references, not the actual key.

3. Enable the Connection Profiles to Share

1. In Connection profiles, find the profile you want your assistant to use. Use Search profiles… and Find if needed.
2. Select the profile’s Enabled checkbox.
3. Confirm the enabled-profile count increases. Enable additional profiles only when they are needed for your work.
4. Review the Selected profile · saved knowledge panel below the profile list.

One enabled profile is ready to share. Source database writes remain blocked.

New profiles start disabled. Disabled profiles are not available to the assistant. The assistant cannot enable profiles itself. A profile’s Enabled checkbox shares its schema, saved Knowledge, supported read-only query results and native VDM tools, subject to their normal checks.

The Knowledge panel reports saved schema status and available examples or validated query history. Saved schema missing, No example reports or No validated query history yet are not setup failures. Select the profile and choose Open Knowledge if you need to prepare its saved schema or examples. Live schema discovery is also available through the connected assistant on supported providers.

4. Review the Connection Options

• Port: The default is 18765. Leave the displayed port unless your administrator requires a different available port.
• MCP URL: Use the exact address displayed by VDM, including 127.0.0.1, the port and /mcp. Do not substitute a computer name or hostname alias.
• Start MCP automatically when VDM starts: Optional and off by default. Enable it if you want future VDM launches to start sharing your saved enabled profiles.
• Allow Bridgit embedding API calls (billed): Optional and off by default. Leave it off for initial setup unless you specifically need the embedding features and have approved their API use.

Settings save automatically after edits. There is no separate Save Settings button. If VDM reports that settings could not be saved, resolve that message before relying on the changed configuration.

5. Start MCP

1. Select Start MCP in the Home ribbon.
2. Wait for the status bar to show Running.
3. Confirm that the ribbon action changes to Stop MCP and the third checklist step shows Ready.

MCP is running. The next step is to connect and verify the assistant.

Click Start MCP once. If the port is busy or startup fails, VDM reports the problem and remains stopped; it does not silently select another port. Profile enablement, port and embedding settings must be changed while sharing is stopped.

6. Restart Your Assistant, Then Copy Agent Setup

1. After completing the environment, profile and server steps, fully close and restart your assistant client so it can read the Windows environment values.
2. If you launch the assistant from a terminal, close and reopen that parent terminal too, then launch the assistant again.
3. Keep VDM open. Return to Settings > MCP and select Copy Agent Setup.
4. Paste the complete copied message directly into the assistant’s chat and send it.
5. Allow the assistant to configure its VDM connection. Complete any client-specific trust or approval prompt it identifies.

The copied message tells the assistant to configure the client you are currently using, preserve unrelated settings, connect to VDM, discover the tools and request the built-in MCP help. You do not need to select a client format, manually edit JSON or TOML, or copy a key into a configuration file.

For Codex, the package supplies its environment-backed bearer setting. For Claude Code, it supplies the client’s HTTP configuration with a literal environment-variable reference. Other clients must support their own documented authentication format; variable substitution is not universal. See the official Codex MCP documentation or Claude Code MCP documentation for client-specific controls.

If the assistant reports that another restart or client reload is necessary after configuration, complete that step and resume verification. A new chat alone may not reload the client’s process environment.

7. Verify the Connection

1. Ask the assistant: “Verify your VDM MCP connection, list my enabled profiles, and explain what is available using VDM’s MCP help.”
2. Check that it reports a successful connection and the expected profiles.
3. Ask it to identify missing permissions, unsupported providers or other readiness requirements before proceeding with a task.
4. In VDM, open the Activity tab to see recent tool activity.

Actual activity after an authenticated help request. Tool discovery and help do not execute a report query.

Copying setup does not verify a connection. Running means VDM is listening; Ready environment status means the saved Windows values match. Neither proves that the assistant has connected. A successful help request also does not prove a particular database, file, renderer or calendar is ready.

8. Close the Setup Window When Finished

Close the MCP window using its title-bar X. Sharing continues while VDM remains open. Closing VDM stops sharing. To stop access while keeping VDM open, reopen MCP and select Stop MCP.

What You Can Do with MCP

You can use ordinary language. Replace demonstration names, fields and reporting rules with your own. Ask the assistant to check the live capability guide whenever a feature or setting is uncertain.

Build, Review and Run Queries

1. Name the enabled Connection Profile to use.
2. Describe the requested columns, population, date range, calculations, grouping, sorting and exclusions. Supply business definitions that the assistant should not guess.
3. Ask it to inspect the available schema and saved Knowledge and prepare a View draft.
4. Review the proposed SQL and any assumptions. Preparing, opening or saving a View does not itself run its query.
5. Provide required parameter values, then request execution when ready.
6. Review the returned fields, row count and limit notices. Compare important values with a trusted source.
7. Request a native save when satisfied.

MCP uses dedicated database connections for ordinary operations and works independently of your active desktop query and unsaved editor content. It does not automatically replace the SQL currently visible in VDM.

Source SQL is read-only. Data-changing statements, SQL batches, schema changes, executable procedures and unsupported calls are blocked. Supported SQL still depends on the actual provider and database dialect. Enabling a profile does not guarantee that every driver or read-only SQL construct is supported.

Understand Result Limits

Query results default to a maximum of 100 returned rows and a 30-second request timeout. Requests can use up to 1,000 returned rows and 60 seconds. Column, cell and overall response-size limits also apply. The assistant should disclose truncation or clipping rather than treating a limited response as the complete population.

A displayed row count is the number returned, which may be smaller than the number matching the query. For full-population totals, ask for an appropriate database aggregate query and verify the calculation and filters. Do not sum a limited detail sample and assume it represents the whole database.

Use Parameters and Multi-Query Views

Parameters let a saved View request different inputs without rewriting the query. MCP supports typed values such as text, integers, decimals, dates, date-times and Boolean inputs. Supported static list parameters accept 1–100 non-null typed values; empty or missing required inputs must be supplied before execution. Values are bound as database parameters.

For example: “Create required StartDate and EndDate parameters. Preserve them in the saved View and ask me for the execution values.” The assistant should not invent values or automatically execute dynamic lookup/default SQL or parameter expressions.

A multi-query View can retain each query’s approved profile and result name. Execution occurs one query at a time on that query’s profile. Finished Report and Visualize initialization currently require a compatible single-query source; combining queries into a View does not remove that requirement.

Reuse the Parameter Library

1. Ask the assistant to browse categories and show the full saved definition you want.
2. Confirm its type, required status, defaults and compatibility with the target View.
3. Ask it to copy the supported definition into the draft.
4. Save the View separately.

Browsing, editing or copying definitions does not execute library SQL. Advanced native definitions can be inspected, but unsupported dynamic or expression behavior cannot be silently converted. Editing a library entry does not update copies already stored in existing Views. If a revision conflict occurs, reload and review the current definition before retrying.

Use and Maintain Saved Knowledge

MCP can read the enabled profile’s saved reporting instructions, Schema Vocabulary, join guidance, examples, successful queries, repair lessons and profile memories where available. The assistant uses that evidence with the actual schema to author SQL.

The selected-profile summary describes saved Knowledge. Missing examples do not block sharing.

1. Select the profile in MCP and choose Open Knowledge to prepare or maintain its saved content in VDM.
2. Save your Knowledge edits. Unsaved editor changes are not shared.
3. Ask the assistant to reload saved Knowledge for that profile. Restart MCP when you need to reload all captured context.
4. If the saved schema is stale, request the appropriate schema refresh. Reloading Knowledge and refreshing schema are different operations.

Explicit MCP edits can manage supported authored vocabulary, joins, examples, profile memories and instructions. They preserve untouched content and use revision checks. MCP cannot manufacture a validated query success, rewrite protected validation history, or treat missing metadata as proof that a field or relationship does not exist.

Optional Embeddings and Retrieval Index Refresh

Ordinary saved-Knowledge browsing does not call a model. Ranked retrieval can use the existing native index, and results report whether semantic retrieval, cached evidence or fallback matching was actually used.

To permit API-backed embedding requests, stop MCP, enable Allow Bridgit embedding API calls (billed), and restart MCP. This requires configured Bridgit embedding credentials and can incur OpenAI API usage. It is separate from your assistant’s own account and is not required for basic setup.

Saving Knowledge does not automatically rebuild its retrieval index. After relevant edits, use Knowledge’s Refresh Retrieval Index action or explicitly request the supported MCP index-refresh workflow with its required access and embedding opt-in. Ask the assistant to report actual coverage or failures. Refreshing an index is not a database-query validation.

Create Finished Reports and Visualize Dashboards

Finished Reports

1. Prepare and review a compatible single-query View. Supply any required parameters.
2. Describe the layout, grouping, totals, number/date formats, page orientation and desired export behavior.
3. Ask the assistant to initialize the report and use VDM’s installed Finished Report guidance. Initialization executes the source query for bounded preview data.
4. Review the rendered pages and the assistant’s validation evidence. Request focused changes.
5. Ask it to save the completed native Finished Report and return the saved file link.
6. Open the saved View in VDM and run it with the intended inputs to validate your normal production population.

The workflow supports native report components, expressions, grouping, summaries and charts. Where required, supported native script edits can handle behavior such as data-derived worksheet names. Scripts run locally with native VDM permissions; use them only for approved report behavior. Uploaded images, subreports and scripted chart bridges are outside the current MCP toolset.

Preview rendering and export checks cover the assigned preview data. Ask which PDF or Excel checks actually ran; an image preview alone does not establish workbook sheet names, every record, or complete export correctness.

Visualize Dashboards

1. Prepare a compatible single-query source and provide its required parameters.
2. Describe the measures, dimensions, filters, layout and interactions you need.
3. Ask the assistant to initialize Visualize, inspect the available fields and use VDM’s installed dashboard guidance.
4. Review the returned dashboard and tab images. Confirm labels, aggregation, formatting and any reported interaction limits.
5. Request changes, then save the reviewed dashboard as a native View.

Supported native items include charts, grids, cards, gauges, pivots, filters, text, groups and tabs. The current workflow uses one data source, up to 24 standard items and eight tab pages. Maps, custom items, external connections/assets, scripts and multi-query dashboard bindings are outside this toolset.

For both designers, initial data loading executes SQL. Later design edits, retained-preview reads and saves do not automatically rerun it. Saved designs preserve the query and parameter definitions and exclude the newly captured preview rows and supplied execution values. Session drafts are temporary; save the native deliverable before stopping MCP.

Desktop rendering does not prove WebReports behavior. Validate deployment-specific execution, interaction and export requirements in the environment where the report will be used.

Prepare Scheduler Jobs and Calendar Appointments

Create a Job Definition

1. Save the source Views first. Current MCP job authoring uses supported saved Advanced Query Views.
2. Ask the assistant to inspect the available job settings, source requirements and existing email-profile metadata.
3. Specify the Views and executions, fixed parameter values, export components, formats, destinations and filenames.
4. Provide delivery, alerts, analysis or other supported settings that you want configured.
5. Ask it to validate the complete job and explain missing inputs or conflicts.
6. Save the validated job as a new native .vdmj file.

Supported job configuration includes Details, Summary, Pivot, Chart, Finished Report and CombinedExport output; format-specific options; master and execution email settings; success/failure alerts; and supported AI analysis, storage, Insights, printing and post-process options. Ask for the live Scheduler capability guide for exact choices and dependencies. The tools can use existing email-profile metadata but do not create email profiles or reveal their authentication fields.

Availability still depends on the View’s components and the installed exporter. Current MCP Scheduler parameter editing supports fixed scalar values. Dynamic, list, conditional, SQL-override and relative-date rules require a supported native workflow; do not substitute guessed fixed dates.

Saving a job does not run or schedule it. Authoring tools do not produce delivery exports, send email, print, run post-process actions or perform AI analysis. Those settings apply when the normal runner executes the job later. Scheduled AI analysis uses its normal VDM runtime configuration and key at execution time.

Review and Activate a New Calendar Appointment

1. Identify the saved job or jobs you want to schedule.
2. Specify the appointment subject, future local start date and time, time zone, duration and recurrence.
3. Ask the assistant to check the calendar backend, readiness and locks, then prepare an appointment draft.
4. Review the native upcoming-occurrence preview. Confirm the dates, time zone, recurrence and end condition.
5. Explicitly request activation only when the reviewed schedule is correct.
6. Check the save receipt. An active saved appointment makes the job eligible for the existing Scheduler runner.

New schedules can use one-time, daily, weekly, monthly or yearly recurrence, subject to native validation. Review daylight-saving transition warnings and ambiguous times carefully. The appointment tools do not start the Scheduler service; normal runner availability remains a separate operational requirement.

File-backed calendars respect writer locks, including VDM’s own calendar editor. A draft can be prepared while locked, but activation must wait until the owner releases editing through the normal workflow. MCP does not force an unlock or automatically stop a service. If a commit result is uncertain, inspect the calendar and receipt before retrying to avoid duplicates.

Current MCP calendar tools create new appointments and inspect saved records. Editing or deleting existing saved appointments is not exposed through this toolset.

Find Saved Files and Display Them in VDM

Ask the assistant to return the successful native save’s actual file link. Preview images, local notes and unapplied design files are supporting material; they are not a saved VDM deliverable. New View/report/dashboard/job saves create new files rather than overwriting existing ones. Knowledge and library edits are separate persistent changes with their own revision checks.

VDM captures folder settings when sharing starts. After changing those folders in VDM Settings, stop and restart MCP before saving more work. Existing files are not moved automatically.

Opening a View through MCP normally loads it into the MCP session. To display it on the desktop, explicitly ask: “Show this saved View in VDM without running it.” Save or close unsaved desktop work and wait for active queries to finish if VDM refuses the display. Displaying a View does not execute its SQL. Complete native Views preserve their saved report, Visualize and other sections; preserving a section does not mean MCP can edit every type of section.

Manage Sharing, Environment Values and Access

Maintenance actions are separate from the normal Home setup steps.

To change enabled profiles, stop MCP, adjust the Enabled checkboxes, then start MCP again. Restarting sharing also reloads captured settings and saved context. Use Copy Agent Setup again after a port or client-configuration change.

Understand Data Sharing and Costs

The MCP listener is local, but the connected assistant may send tool results to its AI provider for reasoning. Depending on your requests, those results can include schema names and descriptions, saved Knowledge, returned database rows, report images, file metadata and scheduling details. Local hosting is not a promise that all information remains on the workstation.

Database credentials and authentication keys are not returned through ordinary schema/help tools. This does not make report results non-sensitive. Share only approved profiles and data, and avoid unnecessary detail rows when aggregate results will answer the question.

Your assistant’s model usage follows its account arrangements. Optional MCP embedding calls use VDM’s configured Bridgit embedding service and require the separate billed-call opt-in. Configuring a Scheduler AI analysis does not call a model immediately; later job execution uses its normal runtime settings.

Current Boundaries

• Arbitrary source database writes, SQL batches and executable calls are unavailable.
• Standalone MCP authoring for the native Chart section, Notes and Details/Summary/Pivot grid layouts is unavailable, even though complete saved Views can preserve and display those sections.
• Immediate Scheduler execution, direct delivery-export production and email sending are outside the job-setup tools. Finished Report preview/export validation is a separate workflow.
• Creating email profiles, editing/deleting saved calendar appointments and changing MCP grants through the assistant are unavailable.
• Designer and scheduling compatibility limits still apply. Ask for the current installed capability guide rather than assuming every desktop option has an MCP equivalent.

Troubleshooting

For help, provide the VDM version, assistant/client name, affected workflow, exact visible error and whether MCP shows Running and the environment shows Ready. The Activity and Help tabs can help identify the operation. Remove confidential report data from screenshots and never include keys, passwords or connection strings.

Related Articles

• Building a Report with Ask Bridgit
• Bridgit AI Knowledge Editor Overview
• Teaching Bridgit About Your Database
• Maintaining Bridgit Knowledge and Resolving Health Warnings