[MCP] Centralize JSON‑RPC error handling, standardize MCP response envelope, and add default anonymous role for stdio mode. #3035

anushakolan · 2025-12-30T01:23:42Z

Why make this change?

This is a follow up PR for, #2983 to address some of the newer comments.

What is this change?

Centralized JSON‑RPC error handling: all standard JSON‑RPC error codes are now defined in one place and used consistently throughout the MCP server (for things like parse errors, invalid requests, unknown methods, invalid parameters, and internal errors).
Standardized how responses are written: both successful results and errors now go through shared helpers, so every MCP response has a consistent JSON‑RPC envelope and is easy to change or audit.
Added an implicit default role to be anonymous when no role is provided in mcp-stdio mode.

How was this tested?

Tested manually by calling all the CRUD tools and execute tool.

Added an MCP server in VS Code in C:\DAB\data-api-builder\.vscode\mcp.json

"dab-with-exe": { "command": "C:\\DAB\\data-api-builder\\out\\publish\\Debug\\net8.0\\win-x64\\dab\\Microsoft.DataApiBuilder.exe", "args": ["start", "--mcp-stdio", "--config", "C:\\DAB\\data-api-builder\\dab-config.json"], "env": { "DAB_ENVIRONMENT": "Development" } }

When calling tools with Authenticated all tools pass.
When calling tools with Anonymous, all tools except describe-entities fail with permission denied error.
When calling tools without any role parameter, all tools except describe-entities fail with permission denied error.

anushakolan · 2025-12-30T01:23:52Z

/azp run

azure-pipelines · 2025-12-30T01:24:15Z

Azure Pipelines successfully started running 6 pipeline(s).

Copilot

Pull request overview

This PR is a follow-up to #2983 that improves the MCP stdio server implementation by centralizing JSON-RPC error handling, standardizing response writing, and adding an implicit default role when none is provided.

Centralized all JSON-RPC error codes into a single JsonRpcErrorCodes class
Standardized response handling through shared WriteResult and WriteError helper methods
Added implicit default role of "anonymous" when --mcp-stdio is used without a role parameter

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
src/Service/Utilities/McpStdioHelper.cs	Added `[NotNullWhen(true)]` attribute to enforce non-null role guarantee, implemented implicit default role of "anonymous", and removed unnecessary service scope creation since services are singletons
src/Service/Program.cs	Added copyright header (formatting artifact in diff)
src/Azure.DataApiBuilder.Mcp/Core/JsonRpcErrorCodes.cs	New file defining centralized JSON-RPC 2.0 error codes for consistent error handling across the MCP server
src/Azure.DataApiBuilder.Mcp/Core/McpStdioServer.cs	Replaced hardcoded error codes with constants from `JsonRpcErrorCodes`, refactored initialize handler to use standardized `WriteResult`, and updated server name in initialization response

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

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

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

Aniruddh25

Approved, but please fix the title to mention "what" the code changes are. Follow up PR doesnt convey much information unless you look into the changes. The PR titles are seen directly in the Release notes, so they should be more meaningful. For example, in this case, it is refactor to use common JsonRpcErrorCodes

src/Service/Utilities/McpStdioHelper.cs

anushakolan · 2026-01-07T19:55:55Z

/azp run

azure-pipelines · 2026-01-07T19:56:24Z

Azure Pipelines successfully started running 6 pipeline(s).

anushakolan · 2026-01-14T19:06:07Z

/azp run

azure-pipelines · 2026-01-14T19:06:33Z

Azure Pipelines successfully started running 6 pipeline(s).

Aniruddh25 · 2026-01-14T23:07:09Z

/azp run

azure-pipelines · 2026-01-14T23:07:33Z

Azure Pipelines successfully started running 6 pipeline(s).

anushakolan · 2026-01-15T02:00:22Z

/azp run

azure-pipelines · 2026-01-15T02:00:48Z

Azure Pipelines successfully started running 6 pipeline(s).

souvikghosh04

Added some comments for appropriate way of naming and versioning of MCP server and some naming/structuring conventions.

souvikghosh04 · 2026-01-08T12:41:12Z

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

+    /// These values come from the JSON-RPC 2.0 specification and are shared
+    /// so they are not hard-coded throughout the codebase.
+    /// </summary>
+    internal static class JsonRpcErrorCodes


please consider renaming this to something like McpStdioJsonRpcErrorCodes or something to reflect its related to only MCP. also, we should move this inside "../src/Azure.DataApiBuilder.Mcp/Model" where we already have other error codes and enums, specifically for MCP.

souvikghosh04 · 2026-01-08T12:44:36Z

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

+        /// <summary>
+        /// The method does not exist / is not available.
+        /// </summary>
+        public const int METHODNOTFOUND = -32601;


please consider using existing format "SCREAMING_SNAKE_CASE or UPPER_SNAKE_CASE" for all constant variables. refer- ../src/Config/HealthCheck/HealthCheckConstants.cs

souvikghosh04 · 2026-01-08T12:51:36Z

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

+                    name = "SQL MCP Server",
+                    version = "1.0.0"


can you please also update the name and version in ../src/Azure.DataApiBuilder.Mcp/Core/McpServerConfiguration.cs? for consistency, try to refactor it and use the same name and version through a configurable value or use the DAB version as the version will keep changing.
tagging @Aniruddh25 to confirm if we can use the DAB version itself or have a separate versioning for MCP server.

souvikghosh04 · 2026-01-08T14:17:56Z

src/Service/Utilities/McpStdioHelper.cs

-        /// <param name="mcpRole"> The role for MCP stdio mode, if specified.</param>
-        /// <returns></returns>
-        public static bool ShouldRunMcpStdio(string[] args, out string? mcpRole)
+        /// <param name="mcpRole"> The role for MCP stdio mode. When this method returns true, the role is guaranteed to be non-null.</param>


nit: should mention mcpRole defaults to anonymous

souvikghosh04 · 2026-01-08T14:19:05Z

src/Service/Utilities/McpStdioHelper.cs

+            // Ensure that when MCP stdio is enabled, mcpRole is always non-null.
+            // This matches the NotNullWhen(true) contract and avoids nullable warnings
+            // for callers while still allowing an implicit default when no role is provided.
+            mcpRole ??= "anonymous";


is this necessary? can we instead just initialize as mcpRole = "anonymous"; instead of mcpRole = null; in the beginning at line: 26?

Addressed comments

b783c73

anushakolan marked this pull request as ready for review December 30, 2025 01:43

Copilot AI review requested due to automatic review settings December 30, 2025 01:43

anushakolan requested review from Alekhya-Polavarapu, Aniruddh25, RubenCerna2079, aaronburtle, neeraj-sharma2592, rusamant, sourabh1007, souvikghosh04 and vadeveka as code owners December 30, 2025 01:43

Copilot started reviewing on behalf of anushakolan December 30, 2025 01:43 View session

anushakolan changed the title ~~Addressed comments~~ Follow up PR for mcp-stdio mode code changes. Dec 30, 2025

Copilot AI reviewed Dec 30, 2025

View reviewed changes

src/Azure.DataApiBuilder.Mcp/Core/JsonRpcErrorCodes.cs Show resolved Hide resolved

src/Azure.DataApiBuilder.Mcp/Core/McpStdioServer.cs Show resolved Hide resolved

Aniruddh25 approved these changes Dec 30, 2025

View reviewed changes

Aniruddh25 reviewed Dec 30, 2025

View reviewed changes

src/Service/Utilities/McpStdioHelper.cs Show resolved Hide resolved

Added copyright header for McpStdioHelper

6979a8d

anushakolan changed the title ~~Follow up PR for mcp-stdio mode code changes.~~ Centralize JSON‑RPC error handling, standardize MCP response envelope, and add default anonymous role for stdio mode. Dec 30, 2025

anushakolan changed the title ~~Centralize JSON‑RPC error handling, standardize MCP response envelope, and add default anonymous role for stdio mode.~~ [MCP] Centralize JSON‑RPC error handling, standardize MCP response envelope, and add default anonymous role for stdio mode. Dec 30, 2025

Merge branch 'main' into dev/anushakolan/mcp-stdio-followup

d634f8e

Merge branch 'main' into dev/anushakolan/mcp-stdio-followup

264af55

anushakolan enabled auto-merge (squash) January 14, 2026 19:06

Merge branch 'main' into dev/anushakolan/mcp-stdio-followup

a2d3b68

Aniruddh25 approved these changes Jan 14, 2026

View reviewed changes

Merge branch 'main' into dev/anushakolan/mcp-stdio-followup

f642960

souvikghosh04 requested changes Jan 15, 2026

View reviewed changes

[MCP] Centralize JSON‑RPC error handling, standardize MCP response envelope, and add default anonymous role for stdio mode. #3035

Are you sure you want to change the base?

[MCP] Centralize JSON‑RPC error handling, standardize MCP response envelope, and add default anonymous role for stdio mode. #3035

Uh oh!

Conversation

anushakolan commented Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why make this change?

What is this change?

How was this tested?

Uh oh!

anushakolan commented Dec 30, 2025

Uh oh!

azure-pipelines bot commented Dec 30, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Aniruddh25 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

anushakolan commented Jan 7, 2026

Uh oh!

azure-pipelines bot commented Jan 7, 2026

Uh oh!

anushakolan commented Jan 14, 2026

Uh oh!

azure-pipelines bot commented Jan 14, 2026

Uh oh!

Aniruddh25 commented Jan 14, 2026

Uh oh!

azure-pipelines bot commented Jan 14, 2026

Uh oh!

anushakolan commented Jan 15, 2026

Uh oh!

azure-pipelines bot commented Jan 15, 2026

Uh oh!

souvikghosh04 left a comment

Choose a reason for hiding this comment

Uh oh!

souvikghosh04 Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

souvikghosh04 Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

souvikghosh04 Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

souvikghosh04 Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

souvikghosh04 Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

anushakolan commented Dec 30, 2025 •

edited

Loading