[MCP] Added support for --mcp-stdio flag to dab start (#2983)

## Why make this change?

- Add MCP stdio support to Data API Builder and wire it through both the
engine and CLI so DAB can be used as a Model Context Protocol (MCP)
server.
- Ensures MCP sessions can run under a specific DAB authorization role,
making it possible to test and use MCP tools with permissions from
`dab-config.json`.

## What is this change?

Service entrypoint
- Detects `--mcp-stdio` early, configures stdin/stdout encodings, and
redirects all non‑MCP output to STDERR to keep STDOUT clean for MCP
JSON.
- Parses an optional `role:<name>` argument (e.g. role:anonymous,
role:authenticated) and injects it into configuration as `MCP:Role`,
defaulting to `anonymous` when omitted.
- In MCP stdio mode, forces `Runtime:Host:Authentication:Provider =
"Simulator"` via in‑memory configuration so the requested role is always
available during MCP sessions.
- Starts the full ASP.NET Core host, registers all MCP tools from DI,
and runs the MCP stdio loop instead of the normal HTTP `host.Run(`).

CLI Integration
- Adds `--mcp-stdio` to `dab start` to launch the engine in MCP stdio
mode.
- Adds an optional positional `role` argument (e.g. `role:anonymous`)
captured as `StartOptions.McpRole`.
 - Keeps existing behavior for non‑MCP `dab start` unchanged.

Note
- `ExecuteEntityTool` now looks for MCP tool inputs under arguments (the
standard MCP field) and falls back to the legacy parameters property
only if arguments is missing. This aligns our server with how current
MCP clients (like VS Code) actually send tool arguments, and preserves
backward compatibility for any older clients that still use parameters.

## How was this tested?

Integration-like manual testing via MCP clients against:
- Engine-based MCP server: `dotnet Azure.DataApiBuilder.Service.dll
--mcp-stdio role:authenticated`.
 - CLI-based MCP server: `dab start --mcp-stdio role:authenticated`.

Manual verification of all MCP tools:
- `describe_entities` shows correct entities and effective permissions
for the active role.
- `read_records`, `create_record`, `update_record`, `delete_record`,
`execute_entity` succeed when the role has the appropriate permissions.

## Sample Request(s)

1. MCP server via CLI (dab)

`
{
  "mcpServers": {
    "dab-with-exe": {
"command":
"C:\\DAB\\data-api-builder\\out\\publish\\Debug\\net8.0\\win-x64\\dab\\Microsoft.DataApiBuilder.exe",
      "args": ["start", "--mcp-stdio", "role:authenticated", "--config",
				"C:\\DAB\\data-api-builder\\dab-config.json"],
      "env": {
        "DAB_ENVIRONMENT": "Development"
      }
  }
}
`
2. MCP server via engine DLL

`
{
  "mcpServers": {
    "dab": {
			"command": "dotnet",
			"args": [

"C:\\DAB\\data-api-builder\\out\\publish\\Debug\\net8.0\\win-x64\\dab\\Azure.DataApiBuilder.Service.dll",
				"--mcp-stdio",
				"role:authenticated",
				"--config",
				"C:\\DAB\\data-api-builder\\dab-config.json"
			],
			"type": "stdio"
		}
  }
}
`

Author: anushakolan

src/Azure.DataApiBuilder.Mcp/Core/McpProtocolDefaults.cs

@@ -0,0 +1,30 @@
+using Microsoft.Extensions.Configuration;
+
+namespace Azure.DataApiBuilder.Mcp.Core
+{
+    /// <summary>
+    /// Centralized defaults and configuration keys for MCP protocol settings.
+    /// </summary>
+    public static class McpProtocolDefaults
+    {
+        /// <summary>
+        /// Default MCP protocol version advertised when no configuration override is provided.
+        /// </summary>
+        public const string DEFAULT_PROTOCOL_VERSION = "2025-06-18";
+
+        /// <summary>
+        /// Configuration key used to override the MCP protocol version.
+        /// </summary>
+        public const string PROTOCOL_VERSION_CONFIG_KEY = "MCP:ProtocolVersion";
+
+        /// <summary>
+        /// Helper to resolve the effective protocol version from configuration.
+        /// Falls back to <see cref="DEFAULT_PROTOCOL_VERSION"/> when the key is not set.
+        /// </summary>
+        public static string ResolveProtocolVersion(IConfiguration? configuration)
+        {
+            return configuration?.GetValue<string>(PROTOCOL_VERSION_CONFIG_KEY) ?? DEFAULT_PROTOCOL_VERSION;
+        }
+    }
+}
+

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

@@ -0,0 +1,7 @@
+namespace Azure.DataApiBuilder.Mcp.Core
+{
+    public interface IMcpStdioServer
+    {
+        Task RunAsync(CancellationToken cancellationToken);
+    }
+}

src/Azure.DataApiBuilder.Mcp/IMcpStdioServer.cs

@@ -19,12 +19,14 @@ public class StartOptions : Options
     {
         private const string LOGLEVEL_HELPTEXT = "Specifies logging level as provided value. For possible values, see: https://go.microsoft.com/fwlink/?linkid=2263106";
 
-        public StartOptions(bool verbose, LogLevel? logLevel, bool isHttpsRedirectionDisabled, string config)
+        public StartOptions(bool verbose, LogLevel? logLevel, bool isHttpsRedirectionDisabled, bool mcpStdio, string? mcpRole, string config)
             : base(config)
         {
             // When verbose is true we set LogLevel to information.
             LogLevel = verbose is true ? Microsoft.Extensions.Logging.LogLevel.Information : logLevel;
             IsHttpsRedirectionDisabled = isHttpsRedirectionDisabled;
+            McpStdio = mcpStdio;
+            McpRole = mcpRole;
         }
 
         // SetName defines mutually exclusive sets, ie: can not have
@@ -38,14 +40,21 @@ public StartOptions(bool verbose, LogLevel? logLevel, bool isHttpsRedirectionDis
         [Option("no-https-redirect", Required = false, HelpText = "Disables automatic https redirects.")]
         public bool IsHttpsRedirectionDisabled { get; }
 
+        [Option("mcp-stdio", Required = false, HelpText = "Run Data API Builder in MCP stdio mode while starting the engine.")]
+        public bool McpStdio { get; }
+
+        [Value(0, MetaName = "role", Required = false, HelpText = "Optional MCP permissions role, e.g. role:anonymous. If omitted, defaults to anonymous.")]
+        public string? McpRole { get; }
+
         public int Handler(ILogger logger, FileSystemRuntimeConfigLoader loader, IFileSystem fileSystem)
         {
             logger.LogInformation("{productName} {version}", PRODUCT_NAME, ProductInfo.GetProductVersion());
             bool isSuccess = ConfigGenerator.TryStartEngineWithOptions(this, loader, fileSystem);
 
             if (!isSuccess)
             {
-                logger.LogError("Failed to start the engine.");
+                logger.LogError("Failed to start the engine{mode}.",
+                    McpStdio ? " in MCP stdio mode" : string.Empty);
             }
 
             return isSuccess ? CliReturnCode.SUCCESS : CliReturnCode.GENERAL_ERROR;

src/Cli/Commands/StartOptions.cs

@@ -2359,6 +2359,17 @@ public static bool TryStartEngineWithOptions(StartOptions options, FileSystemRun
                 args.Add(Startup.NO_HTTPS_REDIRECT_FLAG);
             }
 
+            // If MCP stdio was requested, append the stdio-specific switches.
+            if (options.McpStdio)
+            {
+                string effectiveRole = string.IsNullOrWhiteSpace(options.McpRole)
+                    ? "anonymous"
+                    : options.McpRole;
+
+                args.Add("--mcp-stdio");
+                args.Add(effectiveRole);
+            }
+
             return Azure.DataApiBuilder.Service.Program.StartEngine(args.ToArray());
         }
 

src/Cli/ConfigGenerator.cs

@@ -110,7 +110,13 @@ private static async Task ExportGraphQL(
             }
             else
             {
-                StartOptions startOptions = new(false, LogLevel.None, false, options.Config!);
+                StartOptions startOptions = new(
+                    verbose: false,
+                    logLevel: LogLevel.None,
+                    isHttpsRedirectionDisabled: false,
+                    config: options.Config!,
+                    mcpStdio: false,
+                    mcpRole: null);
 
                 Task dabService = Task.Run(() =>
                 {

src/Cli/Exporter.cs

@@ -1,20 +1,20 @@
-// Copyright (c) Microsoft Corporation.
-// Licensed under the MIT License.
-
 using System;
 using System.CommandLine;
 using System.CommandLine.Parsing;
 using System.Runtime.InteropServices;
+using System.Text;
 using System.Text.RegularExpressions;
 using System.Threading.Tasks;
 using Azure.DataApiBuilder.Config;
 using Azure.DataApiBuilder.Service.Exceptions;
 using Azure.DataApiBuilder.Service.Telemetry;
+using Azure.DataApiBuilder.Service.Utilities;
 using Microsoft.ApplicationInsights;
 using Microsoft.AspNetCore;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Hosting;
 using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Logging.ApplicationInsights;
@@ -33,27 +33,41 @@ public class Program
 
         public static void Main(string[] args)
         {
+            bool runMcpStdio = McpStdioHelper.ShouldRunMcpStdio(args, out string? mcpRole);
+
+            if (runMcpStdio)
+            {
+                Console.OutputEncoding = new UTF8Encoding(encoderShouldEmitUTF8Identifier: false);
+                Console.InputEncoding = new UTF8Encoding(encoderShouldEmitUTF8Identifier: false);
+            }
+
             if (!ValidateAspNetCoreUrls())
             {
                 Console.Error.WriteLine("Invalid ASPNETCORE_URLS format. e.g.: ASPNETCORE_URLS=\"http://localhost:5000;https://localhost:5001\"");
                 Environment.ExitCode = -1;
                 return;
             }
 
-            if (!StartEngine(args))
+            if (!StartEngine(args, runMcpStdio, mcpRole))
             {
                 Environment.ExitCode = -1;
             }
         }
 
-        public static bool StartEngine(string[] args)
+        public static bool StartEngine(string[] args, bool runMcpStdio, string? mcpRole)
         {
-            // Unable to use ILogger because this code is invoked before LoggerFactory
-            // is instantiated.
             Console.WriteLine("Starting the runtime engine...");
             try
             {
-                CreateHostBuilder(args).Build().Run();
+                IHost host = CreateHostBuilder(args, runMcpStdio, mcpRole).Build();
+
+                if (runMcpStdio)
+                {
+                    return McpStdioHelper.RunMcpStdioHost(host);
+                }
+
+                // Normal web mode
+                host.Run();
                 return true;
             }
             // Catch exception raised by explicit call to IHostApplicationLifetime.StopApplication()
@@ -72,17 +86,28 @@ public static bool StartEngine(string[] args)
             }
         }
 
-        public static IHostBuilder CreateHostBuilder(string[] args)
+        // Compatibility overload used by external callers that do not pass the runMcpStdio flag.
+        public static bool StartEngine(string[] args)
+        {
+            bool runMcpStdio = McpStdioHelper.ShouldRunMcpStdio(args, out string? mcpRole);
+            return StartEngine(args, runMcpStdio, mcpRole: mcpRole);
+        }
+
+        public static IHostBuilder CreateHostBuilder(string[] args, bool runMcpStdio, string? mcpRole)
         {
             return Host.CreateDefaultBuilder(args)
                 .ConfigureAppConfiguration(builder =>
                 {
                     AddConfigurationProviders(builder, args);
+                    if (runMcpStdio)
+                    {
+                        McpStdioHelper.ConfigureMcpStdio(builder, mcpRole);
+                    }
                 })
                 .ConfigureWebHostDefaults(webBuilder =>
                 {
                     Startup.MinimumLogLevel = GetLogLevelFromCommandLineArgs(args, out Startup.IsLogLevelOverriddenByCli);
-                    ILoggerFactory loggerFactory = GetLoggerFactoryForLogLevel(Startup.MinimumLogLevel);
+                    ILoggerFactory loggerFactory = GetLoggerFactoryForLogLevel(Startup.MinimumLogLevel, stdio: runMcpStdio);
                     ILogger<Startup> startupLogger = loggerFactory.CreateLogger<Startup>();
                     DisableHttpsRedirectionIfNeeded(args);
                     webBuilder.UseStartup(builder => new Startup(builder.Configuration, startupLogger));
@@ -140,7 +165,14 @@ private static ParseResult GetParseResult(Command cmd, string[] args)
         /// <param name="appTelemetryClient">Telemetry client</param>
         /// <param name="logLevelInitializer">Hot-reloadable log level</param>
         /// <param name="serilogLogger">Core Serilog logging pipeline</param>
-        public static ILoggerFactory GetLoggerFactoryForLogLevel(LogLevel logLevel, TelemetryClient? appTelemetryClient = null, LogLevelInitializer? logLevelInitializer = null, Logger? serilogLogger = null)
+        /// <param name="stdio">Whether the logger is for stdio mode</param>
+        /// <returns>ILoggerFactory</returns>
+        public static ILoggerFactory GetLoggerFactoryForLogLevel(
+            LogLevel logLevel,
+            TelemetryClient? appTelemetryClient = null,
+            LogLevelInitializer? logLevelInitializer = null,
+            Logger? serilogLogger = null,
+            bool stdio = false)
         {
             return LoggerFactory
                 .Create(builder =>
@@ -229,7 +261,19 @@ public static ILoggerFactory GetLoggerFactoryForLogLevel(LogLevel logLevel, Tele
                         }
                     }
 
-                    builder.AddConsole();
+                    // In stdio mode, route console logs to STDERR to keep STDOUT clean for MCP JSON
+                    if (stdio)
+                    {
+                        builder.ClearProviders();
+                        builder.AddConsole(options =>
+                        {
+                            options.LogToStandardErrorThreshold = LogLevel.Trace;
+                        });
+                    }
+                    else
+                    {
+                        builder.AddConsole();
+                    }
                 });
         }
 

src/Service/Program.cs

@@ -348,7 +348,16 @@ public void ConfigureServices(IServiceCollection services)
                     return handler;
                 });
 
-            if (runtimeConfig is not null && runtimeConfig.Runtime?.Host?.Mode is HostMode.Development)
+            bool isMcpStdio = Configuration.GetValue<bool>("MCP:StdioMode");
+
+            if (isMcpStdio)
+            {
+                // Explicitly force Simulator when running in MCP stdio mode.
+                services.AddAuthentication(
+                        defaultScheme: SimulatorAuthenticationDefaults.AUTHENTICATIONSCHEME)
+                    .AddSimulatorAuthentication();
+            }
+            else if (runtimeConfig is not null && runtimeConfig.Runtime?.Host?.Mode is HostMode.Development)
             {
                 // Development mode implies support for "Hot Reload". The V2 authentication function
                 // wires up all DAB supported authentication providers (schemes) so that at request time,
@@ -456,6 +465,8 @@ public void ConfigureServices(IServiceCollection services)
 
             services.AddDabMcpServer(configProvider);
 
+            services.AddSingleton<IMcpStdioServer, McpStdioServer>();
+
             services.AddControllers();
         }
 

src/Service/Startup.cs

@@ -0,0 +1,97 @@
+using System;
+using System.Collections.Generic;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+
+namespace Azure.DataApiBuilder.Service.Utilities
+{
+    /// <summary>
+    /// Helper methods for configuring and running MCP in stdio mode.
+    /// </summary>
+    internal static class McpStdioHelper
+    {
+        /// <summary>
+        /// Determines if MCP stdio mode should be run based on command line arguments.
+        /// </summary>
+        /// <param name="args"> The command line arguments.</param>
+        /// <param name="mcpRole"> The role for MCP stdio mode, if specified.</param>
+        /// <returns></returns>
+        public static bool ShouldRunMcpStdio(string[] args, out string? mcpRole)
+        {
+            mcpRole = null;
+
+            bool runMcpStdio = Array.Exists(
+                args,
+                a => string.Equals(a, "--mcp-stdio", StringComparison.OrdinalIgnoreCase));
+
+            if (!runMcpStdio)
+            {
+                return false;
+            }
+
+            string? roleArg = Array.Find(
+                args,
+                a => a != null && a.StartsWith("role:", StringComparison.OrdinalIgnoreCase));
+
+            if (!string.IsNullOrEmpty(roleArg))
+            {
+                string roleValue = roleArg[(roleArg.IndexOf(':') + 1)..];
+                if (!string.IsNullOrWhiteSpace(roleValue))
+                {
+                    mcpRole = roleValue;
+                }
+            }
+
+            return true;
+        }
+
+        /// <summary>
+        /// Configures the IConfigurationBuilder for MCP stdio mode.
+        /// </summary>
+        /// <param name="builder"></param>
+        /// <param name="mcpRole"></param>
+        public static void ConfigureMcpStdio(IConfigurationBuilder builder, string? mcpRole)
+        {
+            builder.AddInMemoryCollection(new Dictionary<string, string?>
+            {
+                ["MCP:StdioMode"] = "true",
+                ["MCP:Role"] = mcpRole ?? "anonymous",
+                ["Runtime:Host:Authentication:Provider"] = "Simulator"
+            });
+        }
+
+        /// <summary>
+        /// Runs the MCP stdio host.
+        /// </summary>
+        /// <param name="host"> The host to run.</param>
+        public static bool RunMcpStdioHost(IHost host)
+        {
+            host.Start();
+
+            Mcp.Core.McpToolRegistry registry =
+                host.Services.GetRequiredService<Mcp.Core.McpToolRegistry>();
+            IEnumerable<Mcp.Model.IMcpTool> tools =
+                host.Services.GetServices<Mcp.Model.IMcpTool>();
+
+            foreach (Mcp.Model.IMcpTool tool in tools)
+            {
+                _ = tool.GetToolMetadata();
+                registry.RegisterTool(tool);
+            }
+
+            IServiceScopeFactory scopeFactory =
+                host.Services.GetRequiredService<IServiceScopeFactory>();
+            using IServiceScope scope = scopeFactory.CreateScope();
+            IHostApplicationLifetime lifetime =
+                scope.ServiceProvider.GetRequiredService<IHostApplicationLifetime>();
+            Mcp.Core.IMcpStdioServer stdio =
+                scope.ServiceProvider.GetRequiredService<Mcp.Core.IMcpStdioServer>();
+
+            stdio.RunAsync(lifetime.ApplicationStopping).GetAwaiter().GetResult();
+            host.StopAsync().GetAwaiter().GetResult();
+
+            return true;
+        }
+    }
+}