Skip to main content

​
Overview

Once Azure SQL is connected, the Dema Agent can explore schemas, read records, and run governed queries against your Azure SQL Database — useful for bringing live operational data into an analysis alongside Dema metrics without rebuilding the data into a separate warehouse. The agent connects over MCP to a Microsoft SQL MCP Server that you run in your own Azure subscription using Data API builder (DAB). Your database stays in your tenant — Dema only sees the entities you expose and the rows the agent reads. What the agent is allowed to do (read vs. write, and which tables) is controlled entirely by your DAB configuration, not by Dema. The agent only acts when you ask it to.

​
What the agent can do

The SQL MCP Server exposes a fixed, predictable set of tools over the entities you publish. The agent never writes raw SQL or sees your internal schema directly — it works through Data API builder’s secure abstraction layer, so every call is deterministic and governed by your role-based permissions. The tools cover:
  • Discover — list and describe the entities you’ve exposed (describe_entities).
  • Read — fetch and summarize records (read_records, aggregate_records).
  • Write — create, update, and delete records (create_record, update_record, delete_record) — only on entities where you grant those actions.
  • Stored procedures — run a stored procedure mapped as an entity (execute_entity). To suppress this tool, do not expose any stored-procedure entities in dab-config.json.
The read and write tools map to your DAB permissions, so a read-only setup (grant only read) refuses every create, update, and delete. Stored-procedure entities are a separate entity type: execute_entity runs whatever the procedure does internally regardless of read/write grants, so control it by choosing which procedures — if any — you expose as entities.

​
Prerequisites

  • An Azure SQL Database (or SQL Server) with the data you want the agent to access.
  • The ability to deploy the SQL MCP Server — Data API builder 2.0 — to Azure Container Apps or Azure App Service with network access to your database.
  • Permission in Microsoft Entra ID to register an application and create a client secret.
  • An Azure role that can grant the MCP Server access to your database (for example to assign a managed identity).
The SQL MCP Server ships with Data API builder version 1.7 and later. Use the latest 2.0 release for the current capabilities and fixes.
Dema connects only to MCP endpoints on .azurecontainerapps.io, .azurewebsites.net, or .azure-api.net (the default Azure Container Apps, App Service, and API Management hosts). Custom domains — Azure Front Door, an API Management custom domain, or your own ingress hostname — aren’t accepted as the connect URL yet, so deploy where the endpoint is reachable on one of these hosts. If you need a custom domain, contact support.

​
Set up the SQL MCP Server

This is a one-time setup in your own Azure environment. The steps below are the essentials — follow the linked Microsoft Learn guides for full detail.
1

Deploy Data API builder pointed at your database

Deploy the DAB SQL MCP Server to Azure Container Apps (or App Service) and point its connection string at your Azure SQL Database. For outbound database authentication, Microsoft recommends managed identity rather than a SQL username and password:
Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Managed Identity;
The server exposes a streamable HTTP MCP endpoint at https://<host>/mcp. See the Azure Container Apps quickstart.
2

Expose only the entities the agent needs

In dab-config.json, add an entity for each table or view you want the agent to reach, and grant read-only access with the authenticated:read permission so only authenticated callers (Dema) can read them:
dab update Products --permissions "authenticated:read"
Anything you don’t expose as an entity is invisible to the agent. The MCP Server turns each entity into the tool surface described in What the agent can do above.
3

Register an app in Microsoft Entra ID

Register one application in Microsoft Entra ID. It serves as both the API that the MCP Server protects and the identity Dema uses to call it. Record the:
  • Directory (tenant) ID — used to build the issuer and token URLs.
  • Application (client) ID and Application ID URI in the form api://<app-id>.
Then create a client secret on the app. Dema uses the client ID and secret to obtain a token. See Register an application in Microsoft Entra ID.
4

Configure inbound authentication on the MCP Server

Data API builder 2.0 starts unauthenticated by default, so you must turn on Entra ID JWT validation. Set the provider to EntraId and point the audience at your Application ID URI and the issuer at your tenant:
dab configure --runtime.host.authentication.provider EntraId
dab configure --runtime.host.authentication.jwt.audience "api://<app-id>"
dab configure --runtime.host.authentication.jwt.issuer "https://login.microsoftonline.com/<tenant-id>/v2.0"
See Configure authentication for SQL MCP Server.

​
Connect Azure SQL in Dema

1

Open the Azure SQL connector

In Dema, go to Agents → Settings → Integrations, find Azure SQL, and click Connect.
2

Enter the connection details

Fill in the values from your setup:
  • MCP URL — your server’s endpoint, in the form https://<host>/mcp (for example https://<app-name>.azurecontainerapps.io/mcp).
  • Token URL — https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token.
  • Client ID — the Application (client) ID of the Entra app you registered.
  • Client secret — the secret you created on that app.
Click Add. Dema obtains a token from Entra ID and marks the integration as Active.
Use the same Entra app as both the protected API (the DAB jwt.audience) and Dema’s client. That keeps the Application ID URI api://<app-id> aligned with the client ID, so the connection works with just the four values above — no extra configuration in Dema.

​
Permissions

Dema does not request named scopes of its own. What the agent can do is governed entirely by the entity permissions in your dab-config.json. Grant the authenticated role only the access the agent should have:
  • For read-only access, expose each entity with authenticated:read.
  • The agent can only see entities you explicitly define — unexposed tables and views stay out of reach.
Access is enforced on your side, in Data API builder. Dema can only do what your DAB entity permissions allow, so review them before connecting and keep the exposed surface to what the agent actually needs.

​
When the connection expires

Dema uses a machine-to-machine (client-credentials) flow: it mints a fresh access token from your client ID and secret for each session and refreshes automatically. There is no interactive sign-in to repeat. The connection breaks only when the client secret expires or is rotated in Microsoft Entra ID. When that happens, create a new secret on the app, then go to Agents → Settings → Integrations, find Azure SQL, click Reconnect, and enter the new secret.

​
Troubleshooting

Double-check the Client ID, Client secret, and Token URL. The secret must be current (not expired or rotated), and the token URL must use your Directory (tenant) ID. Confirm the Entra app exposes the api://<app-id> Application ID URI that the MCP server validates as its audience.
The MCP URL must be an HTTPS URL on your own tenant — on .azurecontainerapps.io, .azurewebsites.net, or .azure-api.net — and must end in /mcp. Copy it from your deployed app rather than typing it by hand.
The token URL must be on login.microsoftonline.com, in the form https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token. Use your Directory (tenant) ID.
The token Dema sends must match what Data API builder validates. Confirm runtime.host.authentication.jwt.audience is api://<app-id> and jwt.issuer is https://login.microsoftonline.com/<tenant-id>/v2.0 (note the /v2.0). For a 403, make sure the entity grants authenticated:read (or the action the agent needs).
Only entities defined in dab-config.json are visible. Add the table or view as an entity and grant it authenticated:read, then ask the agent again.
If you are still stuck, contact support with the error message you see.

​
Additional resources