Skip to content

Added documentation for DAB MCP and AI Foundry integration setup. #2971

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Added documentation for DAB MCP and AI Foundry integration setup. #2971

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 85 additions & 0 deletions docs/Testing/ai-foundry-integration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
# Deploying Data API Builder (DAB) MCP Server and Integrating with Azure AI Foundry

This document provides an end‑to‑end guide to stand up a **Data API Builder (DAB)** container that exposes **REST**, **GraphQL**, and **Model Context Protocol (MCP)** endpoints, and to integrate those endpoints with an **Azure AI Foundry Agent**.

## 1. Architecture Overview

**Components**
- **Azure SQL Database** hosting domain tables and stored procedures.
- **DAB container** (Azure Container Instances in this guide) that:
- reads `dab-config.json` from an **Azure Files** share at startup,
- exposes **REST**, **GraphQL**, and **MCP** endpoints.
- **Azure Storage (Files)** to store and version `dab-config.json`.
- **Azure AI Foundry Agent** configured with an **MCP tool** pointing to the DAB MCP endpoint.

**Flow**
1. DAB starts in ACI → reads `dab-config.json` from the mounted Azure Files share.
2. DAB exposes `/api` (REST), `/graphql` (GraphQL), and `/mcp` (MCP).
3. Azure AI Foundry Agent invokes MCP tools to read/update data via DAB’s surface (entities and stored procedures).


## 2. Prerequisites
- Azure Subscription with permissions for Resource Groups, Storage, ACI, and Azure SQL.
- Azure SQL Database provisioned and reachable from ACI.
- Azure CLI (`az`) and .NET SDK installed locally.
- DAB CLI version **1.7.81 or later**.
- Outbound network access from ACI to your Azure SQL server.


## 3. Prepare the Database
Create tables and stored procedures:
- Tables
- Stored Procedures

Comment on lines +30 to +33
Copy link

Copilot AI Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Section 3 "Prepare the Database" lacks sufficient documentation. The section only lists bullet points ("Tables" and "Stored Procedures") without providing any actual instructions, examples, or SQL scripts for creating the necessary database objects.

Suggested change
Create tables and stored procedures:
- Tables
- Stored Procedures
You need to create the necessary tables and stored procedures in your Azure SQL Database. Below is an example of how to create a simple `Products` table and a stored procedure to retrieve products by category.
**Example:**
1. Connect to your Azure SQL Database using Azure Data Studio, SQL Server Management Studio, or the Azure Portal's Query Editor.
2. Run the following SQL script to create a sample table and stored procedure:
```sql
-- Create Products table
CREATE TABLE Products (
ProductID INT IDENTITY(1,1) PRIMARY KEY,
Name NVARCHAR(100) NOT NULL,
Category NVARCHAR(50) NOT NULL,
Price DECIMAL(10,2) NOT NULL
);
-- Create stored procedure to get products by category
CREATE PROCEDURE GetProductsByCategory
@Category NVARCHAR(50)
AS
BEGIN
SET NOCOUNT ON;
SELECT ProductID, Name, Category, Price
FROM Products
WHERE Category = @Category;
END;
  1. You can modify the table and stored procedure definitions to fit your application's needs. Make sure to note the table and procedure names, as you will reference them in your dab-config.json file.

Copilot uses AI. Check for mistakes.
## 4. Install DAB CLI and Bootstrap Configuration
```
dotnet tool install --global Microsoft.DataApiBuilder --version 1.7.81
export DATABASE_CONNECTION_STRING="Server=<server>.database.windows.net;Database=<db>;User ID=<user>;Password=<pwd>;Encrypt=True;"

dab init \
--database-type "mssql" \
--connection-string "@env('DATABASE_CONNECTION_STRING')" \
--host-mode "Development" \
--rest.enabled true \
--graphql.enabled true \
--mcp.enabled true \
--mcp.path "/mcp"

```

## 5. Add entities and stored procedure to `dab-config.json` and enable MCP tools in the config.
Copy link

Copilot AI Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nitpick] Inconsistent formatting: This section title uses a period at the end while other section titles (sections 1-4, 6-8) do not. Section titles should have consistent formatting throughout the document.

Suggested change
## 5. Add entities and stored procedure to `dab-config.json` and enable MCP tools in the config.
## 5. Add entities and stored procedure to `dab-config.json` and enable MCP tools in the config

Copilot uses AI. Check for mistakes.

Comment on lines +50 to +51
Copy link

Copilot AI Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Section 5 lacks specific instructions. This section mentions adding entities and stored procedures to dab-config.json and enabling MCP tools, but provides no examples, commands, or detailed steps on how to accomplish this.

Suggested change
## 5. Add entities and stored procedure to `dab-config.json` and enable MCP tools in the config.
## 5. Add entities and stored procedures to `dab-config.json` and enable MCP tools in the config.
Here is how to add a table entity and a stored procedure to your `dab-config.json`, and ensure MCP tools are enabled:
1. **Open your `dab-config.json` file.**
2. **Add an entity (table) definition** under the `"entities"` section. For example, to expose a `Customers` table:
```json
"entities": {
"Customers": {
"source": "Customers",
"rest": true,
"graphql": true,
"mcp": true,
"permissions": [
{
"role": "anonymous",
"actions": [ "read", "create", "update", "delete" ]
}
]
},

  1. Add a stored procedure under the "entities" section. For example, to expose a stored procedure called GetCustomerOrders:

      "GetCustomerOrders": {
    "source": {
      "object": "GetCustomerOrders",
      "type": "stored-procedure"
    },
    "rest": true,
    "graphql": true,
    "mcp": true,
    "permissions": [
      {
        "role": "anonymous",
        "actions": [ "execute" ]
      }
    ]
  }
}

    Note: Make sure the "entities" section is a valid JSON object. If you have multiple entities, separate them with commas.

  2. Ensure MCP is enabled in the "runtime" section:

    "runtime": {
  "rest": { "enabled": true },
  "graphql": { "enabled": true },
  "mcp": {
    "enabled": true,
    "path": "/mcp"
  }
}

  3. Example dab-config.json structure:

    {
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('DATABASE_CONNECTION_STRING')"
  },
  "entities": {
    "Customers": {
      "source": "Customers",
      "rest": true,
      "graphql": true,
      "mcp": true,
      "permissions": [
        {
          "role": "anonymous",
          "actions": [ "read", "create", "update", "delete" ]
        }
      ]
    },
    "GetCustomerOrders": {
      "source": {
        "object": "GetCustomerOrders",
        "type": "stored-procedure"
      },
      "rest": true,
      "graphql": true,
      "mcp": true,
      "permissions": [
        {
          "role": "anonymous",
          "actions": [ "execute" ]
        }
      ]
    }
  },
  "runtime": {
    "rest": { "enabled": true },
    "graphql": { "enabled": true },
    "mcp": {
      "enabled": true,
      "path": "/mcp"
    }
  }
}

  4. Save the file.

For more details, see the DAB documentation on entities and stored procedures and MCP configuration.

Copilot uses AI. Check for mistakes.
Copy link
Contributor

@RubenCerna2079 RubenCerna2079 Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also think we should add more specific instructions in this step, at the very least add a link to a place in the DAB documentation that shows how the user is supposed to add the entities to the config file and how to enable the MCP tools.

## 6. Store dab-config.json in Azure Files
- Create a Storage Account and File Share.
Copy link
Contributor

@RubenCerna2079 RubenCerna2079 Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is a Storage Account and a File Share? Are these resources in Azure? Is there any specific way in which they need to be set up?

- Upload dab-config.json.
- Record account name and key for mounting in ACI.

Comment on lines +53 to +56
Copy link

Copilot AI Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Section 6 lacks detailed instructions. The section only provides high-level bullet points without actual commands or step-by-step instructions for creating the Storage Account, File Share, uploading the configuration file, or retrieving the necessary credentials.

Suggested change
- Create a Storage Account and File Share.
- Upload dab-config.json.
- Record account name and key for mounting in ACI.
1. **Create a Storage Account** (if you don't have one):

az storage account create
--name
--resource-group
--location
--sku Standard_LRS


2. **Create a File Share**:

az storage share create
--name
--account-name 


3. **Upload `dab-config.json` to the File Share**:

az storage file upload
--account-name
--share-name
--source ./dab-config.json
--path dab-config.json


4. **Retrieve the Storage Account key** (needed for mounting in ACI):

az storage account keys list
--account-name
--resource-group 

Use the value of `key1` or `key2` as `<StorageAccountKey>` in the next step.

Copilot uses AI. Check for mistakes.
## 7. Deploy DAB to Azure Container Instances

```
az container create \
--resource-group <RG> \
--name dab-mcp-demo \
--image mcr.microsoft.com/azure-databases/data-api-builder:1.7.81-rc \
--dns-name-label <globally-unique-label> \
--ports 5000 \
--location <location> \
--environment-variables DAB_CONFIG_PATH="/aci/dab-config.json" \
--azure-file-volume-share-name <FileShareName> \
--azure-file-volume-account-name <StorageAccountName> \
--azure-file-volume-account-key <StorageAccountKey> \
--azure-file-volume-mount-path "/aci"
Copy link

Copilot AI Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing backslash continuation character. The az container create command has a line break before --os-type Linux but is missing the backslash (\) at the end of line 71 to continue the command.

Suggested change
--azure-file-volume-mount-path "/aci"
--azure-file-volume-mount-path "/aci" \

Copilot uses AI. Check for mistakes.
--os-type Linux \
--cpu 1 \
Comment on lines +61 to +73
Copy link
Contributor

@RubenCerna2079 RubenCerna2079 Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some of the variables are easy to know where to get. But I am not sure if that is the case for all of them. I think this ties to my previous comment of showing the user how are the resources supposed to be set up.

--memory 1.5 \
--command-line "dotnet Azure.DataApiBuilder.Service.dll --ConfigFileName $configFile --LogLevel Debug"
Copy link

Copilot AI Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Incorrect variable reference in command. The --command-line argument references $configFile, but this variable is never defined. It should be /aci/dab-config.json or reference the DAB_CONFIG_PATH environment variable defined earlier.

Suggested change
--command-line "dotnet Azure.DataApiBuilder.Service.dll --ConfigFileName $configFile --LogLevel Debug"
--command-line "dotnet Azure.DataApiBuilder.Service.dll --ConfigFileName $DAB_CONFIG_PATH --LogLevel Debug"

Copilot uses AI. Check for mistakes.
```
REST: http://<fqdn>/api/<EntityName>
Copy link
Contributor

@RubenCerna2079 RubenCerna2079 Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does fqdn mean?

GraphQL: http://<fqdn>/graphql
MCP: http://<fqdn>/mcp
Comment on lines +76 to +79
Copy link

Copilot AI Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing code block formatting. Lines 77-79 appear to be endpoint URLs that should be formatted as a code block or properly structured list for better readability.

Suggested change
```
REST: http://<fqdn>/api/<EntityName>
GraphQL: http://<fqdn>/graphql
MCP: http://<fqdn>/mcp 
REST: http://<fqdn>/api/<EntityName>
GraphQL: http://<fqdn>/graphql
MCP: http://<fqdn>/mcp

Copilot uses AI. Check for mistakes.

## 8. Integrate with Azure AI Foundry
- Create or open a Project.
- Add an Agent.
- Add MCP tool with URL: http://<fqdn>/mcp.
- Test in Playground
Comment on lines +82 to +85
Copy link

Copilot AI Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Section 8 lacks detailed instructions. The section only lists high-level steps without specific guidance on how to create a project, add an agent, configure the MCP tool, or what to expect when testing in the Playground.

Suggested change
- Create or open a Project.
- Add an Agent.
- Add MCP tool with URL: http://<fqdn>/mcp.
- Test in Playground
Follow these steps to connect your DAB MCP endpoint to Azure AI Foundry and test the integration:
1. **Create or Open a Project**
- Navigate to the [Azure AI Foundry portal](https://ai.azure.com/foundry) and sign in.
- On the dashboard, click **Projects** in the left navigation pane.
- To create a new project, click **New Project**, enter a name (e.g., `DAB-MCP-Demo`), and click **Create**.
- To use an existing project, select it from the list.
2. **Add an Agent**
- Within your project, go to the **Agents** tab.
- Click **Add Agent**.
- Enter an agent name (e.g., `DAB-MCP-Agent`).
- (Optional) Add a description.
- Click **Create**.
3. **Configure the MCP Tool**
- In the agent's configuration page, go to the **Tools** section.
- Click **Add Tool** and select **MCP** from the tool type dropdown.
- In the **MCP Endpoint URL** field, enter your DAB MCP endpoint, e.g., `http://<fqdn>/mcp`.
- (Optional) Configure authentication if your endpoint requires it.
- Click **Save** to add the tool.
4. **Test in Playground**
- Go to the **Playground** tab in your project.
- Select the agent you created from the agent dropdown.
- In the input box, enter a prompt that will trigger the MCP tool, such as:
```
Get all records from the Customers entity.
```
- Click **Run**.
- The agent should invoke the MCP tool, which will call your DAB MCP endpoint and return the results.
- **Expected Result:** You should see the data returned from your DAB instance displayed in the Playground output panel.
- If there are errors, check the DAB container logs and ensure the MCP endpoint is reachable from Azure AI Foundry.

Copilot uses AI. Check for mistakes.