SqlDBM MCP Server

The SqlDBM MCP server exposes an organization's SqlDBM data models to AI agents and assistants through the Model Context Protocol (MCP). A connected AI can discover accessible projects, inspect model structure as structured data or DDL, read revision history, and generate migration scripts between revisions or environments.

With write access granted, an AI can also create projects, branches, and revisions; update model-governance fields; and import semantic-model YAML or a dbt manifest.

The server works with the data model maintained in SqlDBM: its schema, structure, relationships, metadata, and history. Access is subject to the authenticated user's SqlDBM permissions, account entitlements, and the capabilities enabled for the company.

Connection and authentication

Endpoint

Your company account must have MCP access enabled to use the tools. Contact your administrator or the SqlDBM team for access and enablement requirements. MCP write access is controlled separately.

Connecting

Add the SqlDBM MCP server in a compatible client or AI application and sign in with your SqlDBM account through OAuth. With an OAuth-capable client, there is no access token to generate, copy, or paste manually.

Client support for remote MCP connections and OAuth varies. Follow your client's connection instructions.

Authorization

The client requests the scopes it needs:

A client that needs both capabilities must obtain both scopes. When the client requests write access, the user can continue with read-only access or explicitly approve write access. Approving a scope does not override company controls, subscription requirements, or project permissions.

A read-only authorization cannot invoke write tools.

Permission model

Access is tied to the SqlDBM account used to sign in. Project access, subscription roles, branch permissions, and applicable feature entitlements remain enforced.

Developer configuration

Custom integrations authenticate with an OAuth access token issued by the SqlDBM MCP authorization server for the MCP resource, supplied as an HTTP bearer token. Read tools require mcp:modeling:read; write tools require mcp:modeling:write.

A legacy SqlDBM OpenAPI token with a modeling scope is not a substitute for an MCP OAuth access token.

For clients that support local command-based MCP servers but need a bridge to a remote OAuth-enabled server, mcp-remote is one option:

{
  "mcpServers": {
    "sqldbm": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.sqldbm.com/"]
    }
  }
}

The configuration location and syntax depend on the client. This example requires Node.js and npx; -y allows installation without an npm confirmation prompt. Clients with native remote-MCP and OAuth support may not need this bridge.

Requirements for write access

• Approve the mcp:modeling:write scope when requested.
• Ensure MCP access and MCP Write are enabled for your company.
• The specific write tool must be enabled.
• Existing-project writes require an eligible Modeler or Admin subscription role and Writer/Owner permissions on the relevant project or branch. When targeting a branch through its parent project, permissions on both are checked.
• Creating a new project requires eligible project-creation permissions, rather than permissions on an existing project.
• Updating model-governance fields additionally requires an Enterprise plan.
• Project locks, concurrent-work restrictions, and other operation-specific checks still apply.

If your AI client supports per-tool approval, configure write operations to require approval when you want to review each request before execution.

Read tools

The server implements 23 read tools across eight areas. Tool visibility and successful execution depend on authorization, account settings, and applicable project or feature restrictions.

Discovery

Model queries: structured and filterable

These tools expose the stored project model as structured JSON. A required jq expression selects the information returned.

The project-model JSON uses PascalCase property names, integer enumerations, and many collections keyed by object IDs. Consult the schema guide before constructing queries.

DDL retrieval

Object-name matching is case-insensitive by default; use caseSensitive: true when needed. A schema-qualified name helps distinguish objects with the same name in different schemas. An unqualified name can match multiple objects.

Revision history

Environments and migration

Environment comparisons use the model snapshots maintained in SqlDBM. They do not inspect the live warehouse or apply the generated migration.

Semantic models

get_semantic_model_yaml formats:

• cortex selects a named semantic model and requires its exact, case-sensitive modelName.
• sqldbm-default selects project-wide semantic defaults and does not accept a model name. This is the default when format is omitted.

Model governance

Governance fields are custom metadata definitions and values attached to model objects or columns. They are not physical table columns.

dbt

These tools return raw dbt YAML, rather than a jq-filtered JSON projection. The required format is source or model. The optional layout is legacy or fusion, defaulting to legacy.

Object-name matching is case-insensitive by default. Use a schema-qualified name or caseSensitive: true to narrow the match when needed. The object-level dbt tools select tables and views, not other object types supported by DDL retrieval.

Write tools

The server implements six write tools.

Revision and branch targeting

create_revision requires an explicit target:

• Supply branchId and set targetMainLine to false; or
• Supply no branch ID and set targetMainLine to true.

Do not select both. Direct revision creation on concurrent-work Main is not supported; use a branch instead.

baseRevisionId selects the revision to build from; a null value selects the latest revision. It is a base-selection parameter, not a guarantee that stale writes will be rejected. A non-empty description supplies the revision name.

A branch has its own project ID. Keep both the parent Main project ID and the returned branch project ID. For subsequent create_revision calls targeting the branch, use the parent Main projectId and the branch project ID as branchId, with targetMainLine: false.

Branch parameters vary by tool; consult the individual tool's input schema. In particular, import_semantic_model and get_job_status accept projectId but do not expose a separate branchId parameter.

Supported inputs

create_project and create_revision currently accept only sourceFormat: "Ddl". JSON project-model imports are not supported by those two tools.

Separate tools accept:

• Semantic-model YAML.
• dbt manifest JSON.
• Structured governance-field changes.

Governance-field updates

An update replaces the complete field, including its binding set. Bindings omitted from the replacement are removed. Deleting a field also removes its bindings.

Read the current field before updating it, and supply the complete desired replacement using the write tool's input schema — not only the changed properties. The read and write representations are not identical. Use the returned revision identifier to inspect the saved result.

Semantic imports and job status

import_semantic_model is asynchronous. Supply the complete YAML document and set isProjectDefaultsExpected to match it:

• true for a project-defaults document whose root name is $$SQLDBM_DEFAULT.
• false for a named semantic-model document.

Poll get_job_status until status is completed, then inspect conclusion:

Submit a complete semantic document, not a filtered inspection result. A named-model import replaces that model's definition, so omissions can remove semantic content. Project-default imports can also remove omitted semantic-only defaults and dependent overrides while preserving physical model structures.

dbt manifest imports

import_dbt_manifest accepts the actual contents of manifest.json as a string, not a file path, base64 value, or compressed archive.

The operation is synchronous: it returns saved revision identifiers, not a job ID, and does not use get_job_status. Review the resulting revision before relying on it; a successful save does not mean the changes have been reviewed or approved.

How governance works

Writing through MCP does not bypass permission checks or automatically merge a branch into Main. Changes are saved under the authenticated user's permissions and recorded through SqlDBM's revision workflow.

The MCP tool surface does not include operations to merge branches, approve changes, or delete revisions. That does not make writes additions-only: supported updates and imports can replace or remove model content. Follow your organization's normal review and merge process before promoting changes.

Failure handling and rate limits

Authentication failures and validation failures rejected before write dispatch do not submit model changes. Once a request has been submitted, however, a failed response does not always establish whether changes were saved. Do not assume that every service error or timeout guarantees a rollback.

If a write times out or its outcome is uncertain:

• Inspect the project and revision history before retrying.
• For a queued import, poll the existing job when its ID is available rather than submitting the same document again.
• If no job ID was received, verify the outcome before resubmitting. A retry can create a second job or duplicate changes.

MCP requests are rate-limited per user, with an additional limit for write calls. Writes also count toward the overall MCP request limit. Follow the retry guidance returned when throttled.

Contact SqlDBM for current entitlement and billing terms; your AI client or provider may apply separate usage charges.

What the project model contains

The structured model exposes SqlDBM's stored schema and modeling information, including databases, schemas, tables, views, functions, procedures, sequences, and domains, as applicable to the project's platform.

Table information includes columns and their data types, nullability, identity settings, defaults, comments, and logical names; indexes; relationships and column mappings; and check constraints. Project-level information includes naming conventions, glossary entries, and tags.

Platform-specific properties are available for supported targets such as Snowflake, Databricks, BigQuery, Redshift, PostgreSQL, SQL Server, MySQL, and Oracle. Snowflake model information additionally includes supported object and column tags and policy assignments, including masking, row-access, and privacy policies.

Available properties depend on the target platform and the information maintained in the model.

What the server can answer

Representative questions include:

• Inventory: Count and list tables, views, functions, and other modeled objects.
• Relationships: List foreign-key relationships, column mappings, and cardinality.
• Sensitive data: Find columns whose names or comments match PII patterns, and inspect modeled policy assignments. Pattern matching is not a substitute for formal data classification.
• Object detail: Retrieve an object's structure or generated DDL.
• Change and migration: Inspect revision history and generate alter scripts between selected model snapshots.
• Schema as code: Retrieve generated DDL for a model or supported named objects.
• Semantic and dbt context: Inspect semantic definitions, export dbt YAML, and review import results.
• Governance metadata: Read custom fields and their values on model objects or columns.

Constraints and limits

• Model only, no warehouse row data. The server works with SqlDBM model information. It does not read or modify warehouse table contents or execute generated SQL.
• Read-only unless write access is granted. Write operations require explicit OAuth write authorization and the applicable account, role, and project permissions.
• Permission- and feature-scoped. Accessible operations depend on company settings, subscription entitlements, project permissions, and operation-specific restrictions.
• Revision saves are not automatic approval requests. Successful writes can become the target's latest revision. Review and promotion remain part of your organization's workflow.
• Focused model queries. Model-query tools require a non-empty jq expression. Request a focused projection rather than the entire model; output limits and execution timeouts apply.
• Large outputs may need narrower requests. Use object-level retrieval or smaller query projections when a result exceeds the response limit. Do not treat a limit message as model data or exported YAML.
• Write outcomes require inspection. Do not assume a failed response proves that nothing changed, or that a completed import job succeeded. Inspect returned identifiers, conclusions, and diagnostics.