Skip to main content

Configuring metadata tables

Most databases have a catalogue of tables that describe the database itself: data dictionaries, UDF configuration, column descriptions, lookup definitions. Common examples:

  • Oracle: ALL_TABLES, ALL_TAB_COLUMNS, plus any application-level dictionary tables your team or vendor maintains.
  • SQL Server: INFORMATION_SCHEMA.COLUMNS, sys.columns, plus any application-level metadata tables your team maintains.

DataStar's MCP server has a set of tools that can search and query these tables on behalf of an AI agent, but only the tables you explicitly add to the metadata tables list for your workspace. Anything outside that list is off-limits.

Why configure them​

With a metadata table list in place, an agent can answer questions like:

  • "What user-defined columns exist on the ACCOUNT table?"
  • "Which tables reference a specific party code?"
  • "How many columns have no description?"

Without configuring any, the MCP still works, but the agent can only see what's in get_database_schema and get_table_details, which covers physical schema only, not whatever documentation your team has built on top.

How to configure​

  1. Open the workspace you want to configure for.
  2. Workspace → Workspace Settings (or the cog icon on the workspace in the sidebar).
  3. Select the MCP tab.
  4. Click Add table and enter a table name. You can enter:
    • Just the table name, e.g. UDF_CONFIG
    • Or schema-qualified, e.g. APP.UDF_CONFIG
  5. Repeat for each metadata table you want to expose.
  6. Save.

Workspace Settings, Metadata Tables tab

  1. Tab bar: select the Metadata Tables tab.
  2. Description: explains what metadata tables are and how the AI agent uses them.
  3. Table list: the tables exposed to MCP; Add and Delete buttons on the right.
  4. Action buttons: Reset, Cancel, or Save.

The settings are per-workspace, stored in the workspace's user settings file. Your teammates won't inherit them automatically; share the list as part of your onboarding.

What the agent can then do​

Once a table is in the list, the metadata_table MCP tool can act on it. The tool dispatches by action:

ActionWhat it does
listEnumerate the allowed set.
describeShow column names, types, nullability.
queryRead rows with optional filters (=, LIKE, IS NULL, etc.) and column projection. Set countOnly=true for a SELECT COUNT(*) instead of rows.
searchFree-text search across every column of every allowed table.

Anything not on the list is invisible; the agent can't query it even if the database user has permission.

  • ALL_TABLES
  • ALL_TAB_COLUMNS
  • ALL_CONSTRAINTS
  • ALL_TAB_COMMENTS
  • ALL_COL_COMMENTS

Safety​

  • The metadata_table tool is read-only. There's no write equivalent.
  • Column names passed as filters are validated: identifiers must match [A-Za-z0-9_.#]+. SQL injection through a column filter is not possible.
  • Values are parameter-escaped for single-quote embedding before being interpolated.
  • Nothing is cached; every call runs against the live database, so data is fresh.

Troubleshooting​

"Table X is not in the configured metadata tables". The agent tried to query a table that isn't on the list. Add it and save.

metadata_table with action='search' returns results for some tables but not others. Check the Errors field on the response. A table may have failed because it doesn't exist in the current schema, the user lacks permission, or the name is typo'd.

An agent keeps using the wrong schema prefix. Ask it to call get_database_context first. That returns the effective default schema, so it can construct the right names.

See also​

Last updated on