Skip to main content
Glama
baic-dl-mcp

baic-dl-mcp

by prepmonk

BAIC Data Layer MCP Server

An MCP server over the BAIC Data Layer: sources, knowledge bases, knowledge clusters, the three data agents, and transformation pipelines.

API behaviour is documented in DL-API-REFERENCE.md, verified live against two environments. Read that first if anything here surprises you — several endpoints are named misleadingly.

SESSION-LOG.md records how this was built: the platform behaviours found, the bugs fixed along the way, claims that were later corrected, and the open items.

Setup

cp .env.example .env      # then fill in credentials + hosts
uv sync

.env is gitignored (as is any .env* except the example). Nothing environment-specific is hardcoded: the tenant and user ids are derived from the access token at runtime, because the platform uses different tenant ids on different endpoints and they vary per deployment.

Pointing at a different environment

Edit .env — the hosts and credentials there are all that select a deployment:

BAIC_UI_URL  BAIC_BACKEND_URL  BAIC_USER_MGMT_URL  BAIC_USER_NAME  BAIC_USER_PASSWD

Keeping spare copies (.env-udl-demo, .env-poc-farmers) and copying one over .env works fine; all .env* files are gitignored except .env.example.

.env is optional when the variables are supplied directly, which is how Docker (--env-file) and fastmcp.cloud work — the image ships no dotenv file on purpose. Missing values fail at startup naming the variable.

whoami reports the backend host, tenant and user, so you can always confirm where you are pointed before running anything.

Related MCP server: bika-mcp

Running

Built on FastMCP. Two transports, chosen by BAIC_TRANSPORT:

uv run baic-dl-mcp                          # stdio (default) - what Claude Desktop drives
BAIC_TRANSPORT=http uv run baic-dl-mcp      # HTTP on :8000

Claude Desktop — local

{
  "mcpServers": {
    "baic-dl": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/BAIC-DL-MCP", "run", "baic-dl-mcp"]
    }
  }
}

Claude Desktop — Docker

docker build -t baic-dl-mcp:latest .
{
  "mcpServers": {
    "baic-dl": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "--env-file", "/absolute/path/to/BAIC-DL-MCP/.env",
               "baic-dl-mcp:latest"]
    }
  }
}

-i is required — stdio needs stdin held open. Credentials are passed at run time via --env-file and never baked into the image.

fastmcp.cloud

fastmcp.json points at server.py:mcp and is ready to deploy. Connect the repo in fastmcp.cloud, then set these as environment variables in the cloud UI — never commit them:

BAIC_USER_NAME  BAIC_USER_PASSWD  BAIC_UI_URL  BAIC_BACKEND_URL  BAIC_USER_MGMT_URL

Root server.py is a path shim, not a second copy of the server: hosted runners load that file directly rather than importing the installed package, so the relative imports inside src/baic_dl_mcp/ need src on the path first.

HTTP, for a shared deployment

docker compose up -d          # serves http://localhost:8000/mcp

Both paths are verified: 36 tools listed and tools invoked successfully over container stdio and container HTTP.

Start with whoami to confirm which environment you're pointed at.

Tools

36 tools.

Connectivity

Tool

Purpose

whoami

Confirm connectivity and show which environment, tenant, and user are in play

Sources

Tool

Purpose

list_sources

List configured data sources (source connections), one page at a time

get_source

Full detail for one source, including its connection config (secrets masked)

list_connector_types

The connector engines this platform supports

create_snowflake_source

Create a new Snowflake source connection

create_postgres_source

Create a new Postgres source connection

Ingestion

Tool

Purpose

list_available_tables

List the tables a source exposes, before importing any of them

list_destinations

List destinations - the vector stores or warehouses that ingestion writes into

import_source_metadata

Crawl a source's metadata into a new knowledge base

import_and_wait

Import a source's metadata into a knowledge base and wait for it to finish

get_ingestion_task

Check the status of a metadata import started by import_source_metadata

Knowledge bases

Tool

Purpose

list_knowledge_bases

List knowledge bases (KBs) - the metadata imported via Data Ingestion, one page at a time

list_kb_tables

List the tables inside a knowledge base, one page at a time

get_table_details

Table descriptions and column-level detail for one or more tables

get_table_relationships

Discovered foreign-key style relationships between tables in a knowledge base

Knowledge resources

Tool

Purpose

list_golden_sql

List the Golden SQL examples attached to a knowledge base

add_golden_sql

Save a SQL query as a Golden SQL example on a knowledge base

delete_golden_sql

Delete a Golden SQL example. Requires BAIC_ALLOW_DESTRUCTIVE=true

get_kb_instructions

Read the instructions attached to a knowledge base, with all versions

update_kb_instructions

Overwrite the active instructions on a knowledge base. Replaces, does not append

Knowledge clusters

Tool

Purpose

list_knowledge_clusters

List knowledge clusters (KCs) - the groupings of knowledge bases used by the agents

get_knowledge_cluster

KC detail: member knowledge bases, their engines, and the KC instructions

get_kc_instructions

Read a knowledge cluster's instructions, with all versions

update_kc_instructions

Overwrite a knowledge cluster's active instructions. Replaces, does not append

create_knowledge_cluster

Create a knowledge cluster from knowledge bases, optionally with instructions

check_kc_federation

Check whether a set of knowledge bases could legally share one knowledge cluster

delete_knowledge_cluster

Delete a knowledge cluster. Requires BAIC_ALLOW_DESTRUCTIVE=true

Agents

Tool

Purpose

discover_tables

Ask the Data Discovery agent which tables and columns are relevant to a question

ask_data_analyst

Ask the Data Analyst agent a question about a knowledge cluster

generate_pipeline_sql

Ask the Data Engineering agent to write pipeline SQL

approve_table_selection

Confirm the table selection and generate the SQL. Step 2 of 2

Pipelines

Tool

Purpose

list_pipelines

List data pipelines, optionally only those in one knowledge cluster

create_pipeline

Create a data pipeline

get_pipeline_sql

Read a pipeline's saved SQL and visual pipeline graph. Defaults to the active version

save_pipeline_sql

Save SQL and/or the visual pipeline graph onto a pipeline version. Write-only

delete_pipeline

Delete a pipeline. Requires BAIC_ALLOW_DESTRUCTIVE=true

Two things worth knowing before you use it

Saving pipeline SQL is a write, not a review

Pass save_to_version_id to generate_pipeline_sql or approve_table_selection and the SQL is generated and saved in that one call. You get back a saved receipt plus a short sql_preview; the full SQL body and graph are deliberately not returned.

That shape is intentional. Returning 1-2 kB of SQL to the model invites it to re-read the SQL, call get_table_details to check the column names, and then write several paragraphs explaining the query and flagging joins for review. None of that is wanted — the SQL comes from the platform's own engineering agent, generated from the knowledge cluster's metadata and instructions. With nothing to summarise, there is nothing to summarise.

save_pipeline_sql behaves the same way if you call it directly: compact receipt, no SQL echo. Its description tells the model not to validate, not to reformat, and not to restate. Use get_pipeline_sql when you actually want the SQL back.

Two related things worth knowing:

  • Empty columns from get_table_details is normal, not a verification failure. It means enrichment has not run on that table. The response now says so explicitly, because reading it as "I cannot verify this" was what triggered the hedging in the first place. The agents read the source schema directly and do not depend on that endpoint.

  • Branch on outcome, don't assume a review. generate_pipeline_sql usually returns review_required with numbered_tables for a human to pick from, but it sometimes returns sql_generated straight away, and occasionally no_sql_returned.

ask_data_analyst retries on empty results, on purpose

Snowflake execution is intermittent: the identical request returned data in roughly 3 of 14 measured attempts. The UI behaves the same way, so it is not a client problem. Postgres is reliable — 5/5 on the same kind of query.

Worse, a failed execution is reported as IWX-AI-SUCCESS-001 with an empty result and the answer "The query returned no results", so on Snowflake an empty result is indistinguishable from a failure. (Tell-tale: a genuinely empty table returns one row, [{"count": 0}]; a failed execution returns zero rows, [].)

So the tool retries up to max_attempts (default 3) and reports per-attempt outcomes. Retrying often recovers but is not dependable. If every attempt is empty you get an execution_warning — do not relay that to a user as "there is no data". Evidence in DL-API-REFERENCE.md §5.1.

The BAIC DataLayer skill

skills/baic-datalayer/ covers the whole Data Layer, organised the way the UI is — Manage Connector, Data Ingestion, Data Visualization, and the three Data Agents — with a table mapping each UI surface to its tools, plus the flows for building a pipeline, asking a question, and onboarding a source.

It leads with three rules that override default assistant behaviour, because each one breaks a scripted demo:

  1. Pass user wording through verbatim. The knowledge cluster's instructions already supply grain, dedup keys, null handling and dialect, so an "improved" prompt generates different SQL than the one you rehearsed.

  2. Never read, validate or summarise generated SQL. No checking column names via get_table_details, no explaining the design, no flagging joins for review. Saves are reported in one line.

  3. Chain to the next tool call instead of narrating.

reference/quirks.md carries the platform behaviours worth not re-deriving — the intermittent Snowflake execution, the review gate that does not always fire, empty columns being normal.

Adding it to Claude Desktop

The skill links to the API reference, which Desktop cannot reach because uploads have no access to repo files. Build the self-contained bundle first — it copies the referenced docs inside and rewrites the links:

uv run python scripts/package.py
# -> dist/baic-datalayer-skill.zip

Then in Claude Desktop:

  1. Settings → Capabilities → Skills (on some builds: Settings → Features → Skills)

  2. Upload skill and choose dist/baic-datalayer-skill.zip

  3. Confirm baic-datalayer is listed and enabled

  4. Start a new conversation — skills are picked up per conversation, not retroactively

  5. Check it loaded by asking something that should trigger it, e.g. "list the knowledge clusters in baic"

The zip has the skill folder as its root, which is the layout Desktop expects:

baic-datalayer/
  SKILL.md
  reference/quirks.md
  reference/api-reference.md    <- copied in, links rewritten

Rebuild and re-upload whenever the skill or the tool set changes.

Claude Code does not load this skill in this repo, deliberately: it lives in skills/, not .claude/skills/, because it tells an assistant how to drive the Data Layer, which is not what you are doing when you are editing the server. To use it from Claude Code in another project, copy skills/baic-datalayer/ into that project's .claude/skills/, or unzip the bundle there.

It stays environment-neutral

The skill names no deployment: no hostnames, user emails, ids, or row counts. It tells the model to call whoami first and to discover ids at run time, because all of those change when you point .env somewhere else.

DL-API-REFERENCE.md is deliberately not bundled into the skill. It is a human record of building this server — raw endpoints, one deployment's hosts, ids and counts — and shipping it made the skill assert things that become false the moment you switch environment. The skill drives MCP tools, not HTTP, so it does not need it. That dropped the bundle from 31 KB to 5 KB.

scripts/package.py fails the build if the bundle mentions a specific host, email, or UUID, so this cannot creep back in.

Keeping it honest

uv run python scripts/check_skill.py

Fails if the skill names a tool that does not exist, and warns if a tool is never mentioned. A skill that points at a renamed tool sends the model down a dead end, so this is checked rather than trusted.

It is a nudge, not a guarantee

Skills and tool descriptions steer; they do not enforce. The enforcement is structural:

  • Pass save_to_version_id so SQL is saved server-side and never returned to the model. SQL that is not in the response cannot be summarised.

  • save_pipeline_sql returns a compact receipt, not the SQL body.

  • get_table_details labels an empty columns list as expected, so it stops reading as a verification failure.

instruction and question are documented as verbatim in the tool descriptions and in the server-level instructions too, so the rule still holds when the skill is not loaded.

Guard rails

Two flags in .env, both default-off:

  • BAIC_ALLOW_DESTRUCTIVE — gates delete_pipeline, delete_golden_sql, delete_knowledge_cluster

  • BAIC_ALLOW_AUTO_APPROVE — reserved for chaining the pipeline review gate automatically

create_knowledge_cluster also refuses knowledge bases that would need federation. All structured KBs in a cluster must share one engine and one account — the platform cannot query across them, and the API will not stop you. Unstructured (document) KBs are exempt.

Packaging and release

uv run python scripts/package.py        # build skill bundle + validate all targets
uv run python scripts/package.py --check # validate only

Three deployment targets are kept working at once, and the validator fails if any breaks:

Target

Entry

Transport

Local

baic-dl-mcp console script

stdio

Docker

Dockerfile / docker-compose.yml

stdio or http

fastmcp.cloud

fastmcp.json → server.py:mcp

http

Before a demo or a release, run the sequence in the package-baic-mcp skill — it regenerates the README tool table, checks the skill for stale tool names, builds the bundle, rebuilds the image, and finishes with a live smoke test against the configured environment.

Credentials never enter an artefact: .gitignore covers .env* (except .env.example), .dockerignore keeps them out of the image, and both are asserted by the validator. Docker and fastmcp.cloud take them as run-time environment variables.

Layout

src/baic_dl_mcp/
  config.py            env loading
  client.py            auth, token refresh, envelope normalisation, paging
  domain.py            the operations, and the reasons behind each workaround
  server.py            FastMCP tool surface
server.py              path shim for hosted runners (fastmcp.cloud) - no logic
fastmcp.json           fastmcp.cloud deployment config
Dockerfile             stdio + http, credentials injected at run time
docker-compose.yml     HTTP deployment
scripts/
  gen_readme_tools.py  regenerates the Tools table from the running server
  check_skill.py       fails if the skill names a tool that does not exist
  package.py           builds the Desktop skill bundle, validates all targets
skills/
  baic-datalayer/      how to drive the Data Layer - ships to Desktop, not loaded here
.claude/skills/
  package-baic-mcp/    the release workflow, used while working in this repo

The transport layer is deliberately thin: config/client/domain know nothing about MCP, which is why swapping the server from the low-level SDK to FastMCP touched only server.py.

The Tools table above is generated from the running server, so it cannot drift out of date:

uv run python scripts/gen_readme_tools.py

It fails if a tool exists that the table does not list, or vice versa. Run it after adding a tool.

A note on tool schemas

Tools are registered with FastMCP's decorator and no hand-rolled wrapper. An earlier version wrapped each tool in *args, **kwargs and copied __annotations__ but not __signature__; MCP introspects the callable it is handed, so every tool advertised two bogus string parameters named args and kwargs, and clients sent those instead of the real arguments. If you add a wrapper here, set __signature__ — or better, don't wrap.

Available Tools

36 tools
add_golden_sqlA

Save a SQL query as a Golden SQL example on a knowledge base.

Use the description to record the question the query answers - that is what makes it useful to the agents later.

Inputs: golden_sql (required), description (required), knowledge_base_id (required). Returns: result

approve_table_selectionA

Confirm the table selection and generate the SQL. Step 2 of 2.

keep_tables and all_offered_tables take fully-qualified DB.SCHEMA.TABLE names; all_offered_tables is the offered_tables list from generate_pipeline_sql.

PREFERRED: pass save_to_version_id (the pipeline's version_id) and the SQL is generated and saved in this single call. You get back a saved receipt and a short sql_preview instead of the full body.

Do not validate the generated SQL. It is produced by the platform's own engineering agent from the knowledge cluster's metadata and instructions; it does not need checking against table metadata, and calling get_table_details or list_kb_tables to verify it is wasted work. Report the saved receipt and stop.

Without save_to_version_id you get sql and graph back, which must then be handed to save_pipeline_sql unchanged - do not reformat, re-indent, or edit them.

Inputs: session_id (required), keep_tables (required), pipeline_id (required), target_table (required), +4 more. Returns: object

ask_data_analystA

Ask the Data Analyst agent a question about a knowledge cluster.

question must be the user's question VERBATIM - do not rephrase or elaborate it. The cluster's metadata and instructions supply the context the agent needs.

execute_query mirrors the UI's "Run SQL" toggle and defaults to true, which is almost always what is wanted: a question about data wants an answer, not a query. Only pass false when the user explicitly asks for the SQL without running it. Each attempt takes roughly 40-60s. Pass session_id to continue a conversation.

When executing, an empty result is retried up to max_attempts times, because the same question intermittently produces SQL that returns no rows. If every attempt comes back empty the result carries an execution_warning - an empty result is indistinguishable from a failed execution on this platform, so do not tell the user "there is no data".

Inputs: question (required), knowledge_cluster_id (required), session_id, max_attempts, +1 more. Returns: object

check_kc_federationB

Check whether a set of knowledge bases could legally share one knowledge cluster.

Inputs: knowledge_base_ids (required). Returns: object

create_knowledge_clusterA

Create a knowledge cluster from knowledge bases, optionally with instructions.

Refuses knowledge bases that would need federation - all structured KBs must share one engine and one account, because the platform cannot query across them. Unstructured (document) KBs are exempt.

Inputs: name (required), knowledge_base_ids (required), description, instructions. Returns: object

create_pipelineA

Create a data pipeline.

source_id and knowledge_base_id identify where the pipeline writes; knowledge_cluster_id supplies the context the agent reasons over. Returns the pipeline id and its first version id, both needed to save SQL.

Inputs: name (required), source_id (required), description (required), knowledge_base_id (required), +1 more. Returns: object

create_postgres_sourceA

Create a new Postgres source connection.

connection_url is a full JDBC URL, e.g. jdbc:postgresql://host:5432/dbname?sslmode=require Postgres config differs from Snowflake: one JDBC URL + schema, no account or warehouse.

Inputs: name (required), schema (required), password (required), username (required), +2 more. Returns: object

create_snowflake_sourceA

Create a new Snowflake source connection.

authentication_type: "default" (username+password), "oauth", or "keypair". Only "oauth" has been confirmed against the live API; if a create fails on this field, that is the most likely cause.

Inputs: name (required), warehouse (required), source_schema (required), source_database (required), +5 more. Returns: object

delete_golden_sqlA

Delete a Golden SQL example. Requires BAIC_ALLOW_DESTRUCTIVE=true.

Inputs: golden_sql_id (required), knowledge_base_id (required).

delete_knowledge_clusterB

Delete a knowledge cluster. Requires BAIC_ALLOW_DESTRUCTIVE=true.

Inputs: knowledge_cluster_id (required).

delete_pipelineC

Delete a pipeline. Requires BAIC_ALLOW_DESTRUCTIVE=true.

Inputs: pipeline_id (required).

discover_tablesA

Ask the Data Discovery agent which tables and columns are relevant to a question.

Fast (~15s) and the best starting point before writing SQL. Returns the relevant tables, their join relationships, and a per-table column shortlist.

Inputs: question (required), knowledge_cluster_id (required). Returns: object

generate_pipeline_sqlA

Ask the Data Engineering agent to write pipeline SQL.

Branch on outcome, do not assume:

  • "review_required" - the usual case. Print review_prompt verbatim - it is already formatted with numbers. Do not renumber, reformat, or drop the numbers, and do not recommend which tables to keep: the selection is the user's, and a recommendation defeats the point of the review. Then ALSO offer the same numbered tables (plus "keep all") through the client's selection UI and wait - the verbatim rule governs the printed text, and offering those options as a selection does not violate it. Wait on a typed reply only if the client has no selection UI. Then call approve_table_selection with the same session_id. If target_is_also_a_source is non-empty, the pipeline would write over a table it reads from - surface that and get explicit confirmation.

  • "sql_generated" - the agent skipped the review and wrote SQL immediately. If you passed save_to_version_id it is already saved; just report the saved receipt.

  • "needs_clarification" - the agent needs more detail. Relay questions to the user verbatim, offering the answers as a selection where the options are enumerable, then call this tool again with the SAME session_id and their answers as the instruction. Do not answer on their behalf and do not invent a definition for an ambiguous term.

Pass save_to_version_id (the pipeline's version_id) so that if SQL arrives on this turn it is saved without a round trip.

instruction must be the user's request VERBATIM - their exact wording, not a rephrasing. Do not add table names, columns, joins, grain or dialect hints they did not write: the knowledge cluster's own instructions already supply those, and rewriting the request changes what the platform's agent generates.

Do not validate generated SQL against table metadata, and do not summarise it.

Inputs: instruction (required), pipeline_id (required), knowledge_cluster_id (required), session_id, +1 more. Returns: object

get_ingestion_taskA

Check the status of a metadata import started by import_source_metadata.

Inputs: task_id (required).

get_kb_instructionsA

Read the instructions attached to a knowledge base, with all versions.

Inputs: knowledge_base_id (required). Returns: object

get_kc_instructionsA

Read a knowledge cluster's instructions, with all versions.

Note: a KC can have an empty active version while an older version holds the real content, so instructions here is the effective text, not blindly the active row.

Inputs: knowledge_cluster_id (required). Returns: object

get_knowledge_clusterA

KC detail: member knowledge bases, their engines, and the KC instructions.

knowledge_base_ids here is what the agent tools need, so fetch this before asking questions if you want to inspect the context first.

Inputs: knowledge_cluster_id (required). Returns: object

get_pipeline_sqlA

Read a pipeline's saved SQL and visual pipeline graph. Defaults to the active version.

Inputs: pipeline_id (required), version_id. Returns: object

get_sourceB

Full detail for one source, including its connection config (secrets masked).

Inputs: source_id (required). Returns: object

get_table_detailsA

Table descriptions and column-level detail for one or more tables.

Batches - pass several table names in one call. include_profiles adds full profiling stats, which are large.

Paged over table_names: read has_more and pass page=1, page=2, ... to continue. page_size defaults to 25 with include_profiles=True and 200 without, because profiles run about 5 KB per table and a bigger page is rejected by the client. Passing many table names is fine - only one page of them is fetched and returned per call.

An empty columns list is an ordinary state meaning enrichment has not run for that table. It is not an error and not a signal that anything is wrong. In particular it says nothing about SQL generated by the platform's agents, which read the source schema directly - do not treat empty columns as a reason to distrust or flag generated SQL.

This tool is for exploring a schema. It is not a validation step for generated SQL; do not call it to check SQL before saving a pipeline.

Inputs: table_names (required), knowledge_base_id (required), page, page_size, +1 more. Returns: object

get_table_relationshipsC

Discovered foreign-key style relationships between tables in a knowledge base.

Inputs: knowledge_base_id (required).

import_and_waitA

Import a source's metadata into a knowledge base and wait for it to finish.

Convenience wrapper over import_source_metadata + get_ingestion_task. Returns the knowledge_base_id and the final status; if it is still running when timeout_s elapses the import continues server-side and you can keep polling get_ingestion_task.

Writes embeddings into destination_id, so use a destination you own.

Inputs: name (required), source_id (required), table_names (required), source_schema (required), +3 more. Returns: object

import_source_metadataA

Crawl a source's metadata into a new knowledge base.

Asynchronous: returns a task_id plus the new knowledge_base_id. Poll with get_ingestion_task. destination_id is required - get one from list_destinations. This writes embeddings into that destination, so pick a destination you own.

Inputs: name (required), source_id (required), table_names (required), source_schema (required), +4 more. Returns: object

list_available_tablesA

List the tables a source exposes, before importing any of them.

This is the Import Source table picker - use it to choose what to ingest.

Inputs: source_id (required), source_schema (required). Returns: result

list_connector_typesA

The connector engines this platform supports.

There is no server endpoint for this; the list is fixed in the frontend.

Inputs: no named parameters. Returns: object

list_destinationsA

List destinations - the vector stores or warehouses that ingestion writes into.

Needed to pick a destination_id for import_source_metadata.

Paged: read has_more and total, and pass page=1, page=2, ... to continue.

Inputs: page, page_size. Returns: object

list_golden_sqlA

List the Golden SQL examples attached to a knowledge base.

Paged: read has_more and total, and pass page=1, page=2, ... to continue.

Inputs: knowledge_base_id (required), page, page_size. Returns: object

list_kb_tablesA

List the tables inside a knowledge base, one page at a time.

Paged: read has_more and total, and pass page=1, page=2, ... to continue.

Inputs: knowledge_base_id (required), page, page_size. Returns: object

list_knowledge_basesA

List knowledge bases (KBs) - the metadata imported via Data Ingestion, one page at a time.

Each row links a KB to its source, so use this to go from a source name to a knowledge_base_id. status SUCCESS means metadata was crawled successfully.

Paged, and this is the big one: a deployment can hold thousands of KBs. Read total and has_more, then pass page=1, page=2, ... to walk it. page_size is capped at 500 - asking for more does not return more, and requesting the whole collection at once is what breaks the client's 1 MB response limit. To find one specific KB, prefer paging until you match it over trying to pull everything at once.

Inputs: page, page_size. Returns: object

list_knowledge_clustersA

List knowledge clusters (KCs) - the groupings of knowledge bases used by the agents.

Paged: read has_more and total, and pass page=1, page=2, ... to continue.

Inputs: page, page_size. Returns: object

list_pipelinesA

List data pipelines, optionally only those in one knowledge cluster.

Paged: read has_more and total, and pass page=1, page=2, ... to continue.

Inputs: page, page_size, knowledge_cluster_id. Returns: object

list_sourcesA

List configured data sources (source connections), one page at a time.

source_type: RELATIONAL_DB (default), DOCUMENT, CONVERSATION, NOSQL, or "" for all. Returns source_id (usable everywhere a source id is needed), name, engine type, and the account/database/schema so you can tell which sources can share a knowledge cluster.

Paged: read has_more and total, and pass page=1, page=2, ... to continue. Deployments hold hundreds of sources, so never assume one page is all of them. page_size is capped at 500 because a larger response is rejected by the client.

Inputs: page, page_size, source_type. Returns: object

save_pipeline_sqlA

Save SQL and/or the visual pipeline graph onto a pipeline version. Write-only.

This is a plain write. Do NOT do any of the following around it:

  • do not validate or lint the SQL, or check it against table metadata

  • do not call get_table_details, list_kb_tables or get_table_relationships first

  • do not reformat, re-indent, re-qualify or otherwise edit the SQL

  • do not restate or summarise the SQL afterwards

Pass the sql and graph from approve_table_selection through byte-for-byte. The SQL comes from the platform's own engineering agent and is already validated against the knowledge cluster's metadata.

Returns a compact receipt - saved flag, byte count, graph node count, version - and deliberately not the SQL body. Confirm the receipt in one line and stop. Use get_pipeline_sql only if the SQL itself is genuinely needed later.

Partial update: passing only sql leaves an existing graph untouched.

Inputs: version_id (required), pipeline_id (required), sql, graph. Returns: object

update_kb_instructionsA

Overwrite the active instructions on a knowledge base. Replaces, does not append.

Inputs: instructions (required), knowledge_base_id (required). Returns: object

update_kc_instructionsA

Overwrite a knowledge cluster's active instructions. Replaces, does not append.

High leverage: these instructions steer the SQL the Data Engineering agent generates - grain, dedup keys, null handling, dialect, idempotency. Verified to change the output.

Inputs: instructions (required), knowledge_cluster_id (required). Returns: object

whoamiA

Confirm connectivity and show which environment, tenant, and user are in play.

Call this first in a session. Everything is environment-specific - hosts, ids, how much data exists - so never assume which deployment you are pointed at; the backend_url identifies it.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 36 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes. The only potential confusion is between import_source_metadata and import_and_wait, and among list_available_tables, list_kb_tables, and discover_tables, but their descriptions clarify the different stages. Overall, an agent can reliably select the right tool.

    Naming Consistency5/5

    Tool names overwhelmingly follow a consistent verb_noun pattern with clear prefixes like list_, get_, create_, update_, delete_. The use of KB/KC abbreviations is consistent within entities. The only outlier is whoami, but it's a standard connectivity check and doesn't break the pattern.

    Tool Count2/5

    36 tools is excessively high for a coherent MCP surface, exceeding the 25-tool threshold. The server bundles multiple subdomains (sources, destinations, KBs, KCs, pipelines, agents) into one toolset, which would be better split into focused servers.

    Completeness3/5

    The toolset covers the core ingestion-to-pipeline workflow well, including source listing, import, KB/KC management, and SQL generation. However, there are notable gaps: no update or delete for sources, no direct KB delete, no destination creation, and no pipeline execution/trigger tool. This creates dead ends for lifecycle management.

    Related MCP Connectors

    Related MCP Servers