Add server-level description field to MCP runtime configuration

[Copilot]

Why make this change?

MCP clients and agents require high-level behavioral context for servers via the initialize response's instructions field. DAB previously had no mechanism to surface this configurable semantic guidance.

What is this change?

Added optional description field to MCP runtime configuration that populates the MCP protocol's instructions field:

Configuration model

• McpRuntimeOptions now accepts description parameter
• McpRuntimeOptionsConverter handles serialization/deserialization

CLI integration

• dab configure --runtime.mcp.description "text" command support
• Configuration generator validates and persists the value
• Fixed config persistence bug: Added DML tools options to condition check to ensure MCP configuration updates are properly written to config file

MCP server response

• Stdio Server: HandleInitialize() retrieves description from RuntimeConfig.Runtime.Mcp.Description and conditionally includes instructions in initialize response when non-empty
• HTTP Server: Updated server name to "SQL MCP Server"
• Both servers now use explicit object type instead of var for better type clarity

Testing

• Added comprehensive unit tests in McpRuntimeOptionsSerializationTests covering:
  • Serialization/deserialization with description
  • Edge cases: null, empty strings, whitespace, very long strings (5000+ characters)
  • Special characters: quotes, newlines, tabs, unicode characters
  • Backward compatibility with existing configurations without description field
  • Improved assertion order to validate JSON field presence before value matching
• Consolidated CLI tests: removed duplicate TestAddDescriptionToMcpSettings and renamed TestUpdateDescriptionForMcpSettings to TestConfigureDescriptionForMcpSettings
• Fixed build errors by removing nullable reference type annotations (project has nullable disabled)

Example configuration:

{
  "runtime": {
    "mcp": {
      "enabled": true,
      "description": "This MCP provides access to the Products database..."
    }
  }
}

How was this tested?

• Unit Tests
  • 9 serialization/deserialization tests for MCP description field
  • 2 CLI configuration tests for description option (consolidated from 3)
  • All existing ConfigureOptionsTests pass (58 tests)
• Build verification - all projects build successfully with no errors

Sample Request(s)

CLI usage:

dab configure --runtime.mcp.description "This MCP provides access to the Products database and should be used to answer product-related or inventory-related questions from the user."

MCP initialize response (when description configured - Stdio Server):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { ... },
    "serverInfo": {
      "name": "SQL MCP Server",
      "version": "1.0.0"
    },
    "instructions": "This MCP provides access to the Products database..."
  }
}

Note: The HTTP server currently only updates the server name to "SQL MCP Server". Instructions support will be added when the ModelContextProtocol.AspNetCore library adds support for this field in future versions.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull request overview

This PR adds a server-level description field to the MCP runtime configuration that enables DAB to expose semantic guidance to MCP clients via the initialize response's instructions field.

• Adds optional description parameter to MCP runtime configuration model
• Implements CLI support for configuring the description via dab configure --runtime.mcp.description
• Wires the description value into the MCP initialize response as the instructions field

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/Config/ObjectModel/McpRuntimeOptions.cs	Adds Description property to store the server-level description
src/Config/Converters/McpRuntimeOptionsConverterFactory.cs	Implements serialization/deserialization for the description field
src/Cli/ConfigGenerator.cs	Updates configuration generator to handle description parameter and adds it to the MCP configuration check
src/Cli/Commands/ConfigureOptions.cs	Adds CLI option --runtime.mcp.description for setting the description
src/Cli.Tests/ConfigureOptionsTests.cs	Adds unit tests for setting and updating MCP description via CLI
src/Azure.DataApiBuilder.Mcp/Core/McpStdioServer.cs	Retrieves description from runtime config and includes it as instructions in initialize response

Comments suppressed due to low confidence (1)

src/Azure.DataApiBuilder.Mcp/Core/McpStdioServer.cs:209

• The serialization uses JsonSerializer.Serialize without specifying JsonSerializerOptions. By default, System.Text.Json includes null properties in the output, which means the instructions field will be present with a null value when the description is not configured. To omit null properties from the response, you should configure JsonSerializerOptions with DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull. This is important for MCP protocol compliance where optional fields should be omitted rather than included with null values.

            string json = JsonSerializer.Serialize(response);
            Console.Out.WriteLine(json);

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Aniruddh25]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[Aniruddh25]

LGTM

[Aniruddh25]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[Aniruddh25]

@copilot, can you look at the failures in this pipeline and fix the errors in the build? https://dev.azure.com/sqldab/Data%20API%20builder%20Dependency%20Packages/_build/results?buildId=16109&view=logs&j=12f1170f-54f2-53f3-20dd-22fc7dff55f9&t=006e6f7c-8314-5e02-a3df-483f3a1f4cfa

[Copilot]

@copilot, can you look at the failures in this pipeline and fix the errors in the build? https://dev.azure.com/sqldab/Data%20API%20builder%20Dependency%20Packages/_build/results?buildId=16109&view=log...

Fixed the build errors. The issue was using nullable reference type annotations (RuntimeConfig?) in McpRuntimeOptionsSerializationTests.cs, but the Service.Tests project has nullable disabled. Removed all ? annotations from the out parameters in TryParseConfig calls. Build now succeeds with no errors. All tests pass. Commit: 01d7f29

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• dev.azure.com
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)