[MCP] Added the update-record tool implementation. #2888

anushakolan · 2025-09-26T17:06:50Z

Why make this change?

This PR,

Adds the tool implementation for the update-record MCP tool in Azure.DataApiBuilder.Mcp to support updating records via MCP using keys and field payloads with full validation and authorization.
Adds a README to guide contributors on how to test MCP tools using the MCP Inspector.
Improves predicate construction logic in SqlUpdateQueryStructure.cs to support mapped column fields.

What is this change?

Adds docs/Testing/mcp-inspector-testing.md with step-by-step instructions for running MCP Inspector locally, bypassing TLS, and connecting to MCP endpoints.
Introduces UpdateRecordTool.cs under BuiltInTools, enabling record updates via MCP with full validation, authorization, and mutation engine integration.
Updates SqlUpdateQueryStructure.cs to construct predicates using parameterized values for safer and more flexible SQL generation.

Exceptions are thrown when:

Entity is null or empty.
Keys and Fields are not JSON objects.
Failed to parse Keys and Fields.
0 keys provided.
0 fields provided.
Key value is null or empty
field value is null or empty.

Error:

PermissionDenied - No permssions to execute.
InvalidArguments - No arguments provided.
InvalidArguments - Some missing arguments.
EntityNotFound - Entity not defined in the configuration.
InvalidArguments - No entity found with given key.
UnexpectedError - Any other UnexpectedError.

How was this tested?

Manual testing via MCP Inspector
Integration Tests
Unit Tests

These scenarios were manually tested using MCP Inspector, as automated tests are not yet implemented.

Valid Cases

Successful Update

Provided valid entity, keys, and fields.
Verified that values were correctly updated in the database.
Confirmed that the response includes all the column values similar to REST API calls.

Permission Enforcement

Modified role permissions and verified that access control is enforced correctly.

Composite Key Handling

Tested entities requiring multiple keys.
Verified correct update behavior and response formatting.

Alias Mapping

Used mapped field name (e.g., order instead of position) and confirmed that only mapped names are accepted.

Failure Cases

Empty Keys

Provided an empty keys object.
Received appropriate error indicating missing key values.

Empty Fields

Provided an empty fields object.
Received error indicating that at least one field is required.

Invalid Entity Name

Used a non-existent entity name.
Received EntityNotFound error.

Empty Entity String

Provided an empty string for entity.
Received InvalidArguments error.

Entity Not Configured

Used an entity not present in the configuration (e.g., Todos).
Received EntityNotFound error.

Null Entity

Provided null for the entity field.
Received InvalidArguments error.

Valid Key Format but Not in DB

Used correct key structure but no matching record exists.
Received error indicating no entity found with the given key.

Invalid or Null Key Values

Provided null or malformed key values.
Received InvalidArguments error.

Unauthorized Role Context

Removed or misconfigured role header.
Received PermissionDenied error.

Sample Request(s)

{ "id": "00000000-0000-0000-0000-000000000001" }
{ "title": "New Title", "order": 7 }

anushakolan · 2025-10-01T05:06:22Z

/azp run

azure-pipelines · 2025-10-01T05:06:45Z

Azure Pipelines successfully started running 6 pipeline(s).

Copilot

Pull Request Overview

This PR implements the update-record MCP tool to enable updating database records via the Model Context Protocol (MCP). It includes validation, authorization, and proper error handling for various edge cases.

Adds a complete UpdateRecordTool implementation with comprehensive validation and error handling
Improves SQL predicate construction to use mapped column fields instead of exposed field names
Provides testing documentation for MCP Inspector usage

Reviewed Changes

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

File	Description
`src/Azure.DataApiBuilder.Mcp/BuiltInTools/UpdateRecordTool.cs`	New MCP tool implementation for updating database records with full validation and authorization
`src/Core/Resolvers/Sql Query Structures/SqlUpdateQueryStructure.cs`	Enhanced predicate construction to use backing column names for safer SQL generation
`docs/Testing/mcp-inspector-testing.md`	Testing guide for using MCP Inspector with local development setup

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

docs/Testing/mcp-inspector-testing.md

Copilot · 2025-10-01T05:23:22Z

src/Azure.DataApiBuilder.Mcp/BuiltInTools/UpdateRecordTool.cs

+            {
+                if (kv.Value is null || (kv.Value is string str && string.IsNullOrWhiteSpace(str)))
+                {
+                    throw new ArgumentException("Keys are required to update an entity");


Error message is not specific enough. Should indicate which key has the null/empty value, e.g., 'Key value for '{kv.Key}' cannot be null or empty.'

Suggested change

throw new ArgumentException("Keys are required to update an entity");

throw new ArgumentException($"Key value for '{kv.Key}' cannot be null or empty.");

Copilot · 2025-10-01T05:23:22Z

src/Azure.DataApiBuilder.Mcp/BuiltInTools/UpdateRecordTool.cs

+                    if (kvp.Value is null)
+                    {
+                        return BuildErrorResult("InvalidArguments", $"Primary key value for '{kvp.Key}' cannot be null.", logger);
+                    }
+


Duplicate validation logic. The null check for key values is performed twice - once in TryParseArguments (lines 286-292) and again here. Consider consolidating this validation to avoid duplication.

Suggested change

if (kvp.Value is null)

{

return BuildErrorResult("InvalidArguments", $"Primary key value for '{kvp.Key}' cannot be null.", logger);

}

this suggestion from copilot is valid and should be addressed

Co-authored-by: Copilot <[email protected]>

anushakolan · 2025-10-01T06:26:09Z

/azp run

azure-pipelines · 2025-10-01T06:26:30Z

Azure Pipelines successfully started running 6 pipeline(s).

Aniruddh25 · 2025-10-07T19:08:55Z

docs/Testing/mcp-inspector-testing.md

+
+### 4. **How to use the tool**
+- Set the transport type "Streamable HTTP".
+- Set the URL "http://localhost:5000/mcp" and hit connect.


Mention as pre-requisite that dab mcp-server should be running before hitting connect here.

Aniruddh25 · 2025-10-07T19:09:06Z

docs/Testing/mcp-inspector-testing.md

+set NODE_TLS_REJECT_UNAUTHORIZED=0
+
+### 3. ** Open the inspector with pre-filled token.**
+http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<token>


what is this token used for?

Aniruddh25 · 2025-10-07T19:09:23Z

docs/Testing/mcp-inspector-testing.md

+Steps to run and test MCP tools using the https://www.npmjs.com/package/@modelcontextprotocol/inspector.
+
+### 1. **Install MCP Inspector** 
+npx @modelcontextprotocol/inspector


is nodejs a pre-requisite to be installed?

Aniruddh25 · 2025-10-07T21:02:37Z

src/Azure.DataApiBuilder.Mcp/BuiltInTools/UpdateRecordTool.cs

+            {
+                Name = "update_record",
+                Description = "Updates an existing record in the specified entity. Requires 'keys' to locate the record and 'fields' to specify new values.",
+                InputSchema = JsonSerializer.Deserialize<JsonElement>(


#2829 - please update all the references of update-entity in the issue to update_record

Aniruddh25 · 2025-10-09T14:47:32Z

src/Core/Resolvers/Sql Query Structures/SqlUpdateQueryStructure.cs

                predicate = new(
                    new PredicateOperand(
-                        new Column(tableSchema: DatabaseObject.SchemaName, tableName: DatabaseObject.Name, param.Key)),
+                        new Column(tableSchema: DatabaseObject.SchemaName, tableName: DatabaseObject.Name, backingColumn)),


this seems to have been a bug here. Good catch!

Aniruddh25 · 2025-10-09T14:48:50Z

src/Azure.DataApiBuilder.Mcp/BuiltInTools/UpdateRecordTool.cs

+                return BuildErrorResult(
+                    "UnexpectedError",
+                    ex.Message ?? "An unexpected error occurred during the update operation.",
+                    logger: null);


why pass a null to the logger here? why not pass the logger obtained on line 85

src/Azure.DataApiBuilder.Mcp/BuiltInTools/UpdateRecordTool.cs

aaronburtle · 2025-10-09T15:28:11Z

src/Azure.DataApiBuilder.Mcp/BuiltInTools/UpdateRecordTool.cs

+                    return BuildErrorResult("PermissionDenied", "Permission denied: unable to resolve a valid role context for update operation.", logger);
+                }
+
+                if (!TryResolveAuthorizedRole(httpContext, authResolver, entityName, out string? effectiveRole, out string authError))


What is effectiveRole being used for here?

Aniruddh25 · 2025-10-09T16:40:10Z

src/Azure.DataApiBuilder.Mcp/BuiltInTools/UpdateRecordTool.cs

+                    return BuildErrorResult("EntityNotFound", $"Entity '{entityName}' is not defined in the configuration.", logger);
+                }
+
+                // 4) Authorization after we have a known entity


We need to ensure the ClientRoleHeaderAuthenticationHeaderMiddleware is invoked

data-api-builder/src/Core/AuthenticationHelpers/ClientRoleHeaderAuthenticationMiddleware.cs

Line 26 in a86996d

public class ClientRoleHeaderAuthenticationMiddleware

before Authorization resolver kicks in here.

You should perform some testing using the simulator to check what happens for authenticated roles. anonymous role is by default.

Aniruddh25 · 2025-10-09T16:55:19Z

src/Azure.DataApiBuilder.Mcp/BuiltInTools/UpdateRecordTool.cs

+
+            if (string.IsNullOrWhiteSpace(roleHeader))
+            {
+                error = "Client role header is missing or empty.";


If the ClientRoleHeaderAuthenticationMiddleware isn't invoked, the roleheader here will be empty. Please test that out.

Aniruddh25 · 2025-10-09T16:56:52Z

src/Azure.DataApiBuilder.Mcp/BuiltInTools/UpdateRecordTool.cs

+            return true;
+        }
+
+        private static bool TryResolveAuthorizedRole(


Suggested change

private static bool TryResolveAuthorizedRole(

private static bool TryResolveAuthorizedRoleHasPermission(

Aniruddh25 · 2025-10-09T17:51:11Z

src/Azure.DataApiBuilder.Mcp/BuiltInTools/UpdateRecordTool.cs

+                    context.PrimaryKeyValuePairs[kvp.Key] = kvp.Value;
+                }
+
+                if (context.DatabaseObject.SourceType is EntitySourceType.Table)


Why is this validation restricted to entity type of Table?

Aniruddh25 · 2025-10-09T18:01:51Z

src/Azure.DataApiBuilder.Mcp/BuiltInTools/UpdateRecordTool.cs

+                    insertPayloadRoot: upsertPayloadRoot,
+                    operationType: EntityActionOperation.UpdateIncremental);
+
+                context.UpdateReturnFields(keys.Keys.Concat(fields.Keys).Distinct().ToList());


I thought we decided to return the entire record in the response to align with what we have in REST. In REST, do we only return the keys?

Aniruddh25 · 2025-10-09T19:55:05Z

src/Azure.DataApiBuilder.Mcp/BuiltInTools/UpdateRecordTool.cs

+                    {
+                        return BuildErrorResult(
+                            "InvalidArguments",
+                            "No entity found with the given key.",


Suggested change

"No entity found with the given key.",

"No record found with the given key.",

src/Azure.DataApiBuilder.Mcp/BuiltInTools/UpdateRecordTool.cs

Aniruddh25 · 2025-10-09T20:05:12Z

src/Azure.DataApiBuilder.Mcp/BuiltInTools/UpdateRecordTool.cs

+                valueArray.ValueKind == JsonValueKind.Array &&
+                valueArray.GetArrayLength() > 0)
+            {
+                JsonElement firstItem = valueArray[0];


This is assuming there will only be one element in the Value Array.

Aniruddh25 · 2025-10-09T20:07:20Z

src/Azure.DataApiBuilder.Mcp/BuiltInTools/UpdateRecordTool.cs

+            Dictionary<string, object?> normalized = new()
+            {
+                ["status"] = "success",
+                ["result"] = filteredResult // only requested values


We are no longer sending back only the requested values. The comment should be updated.

Aniruddh25 · 2025-10-09T20:10:21Z

src/Azure.DataApiBuilder.Mcp/BuiltInTools/UpdateRecordTool.cs

+                IActionResult? mutationResult = null;
+                try
+                {
+                    mutationResult = await mutationEngine.ExecuteAsync(context).ConfigureAwait(false);


This ExecuteAsync is specifically creating the response as expected in a Rest Request. We should understand it is an MCP response and craft it as per the MCP endpoint needs instead of deserializing and serializing again.

We should use the SqlResponseHelper to create a response that MCP endpoint needs to avoid the duplicate serialization and deserialization.

Aniruddh25 · 2025-10-09T20:30:54Z

src/Azure.DataApiBuilder.Mcp/BuiltInTools/UpdateRecordTool.cs

+            {
+                Content = new List<ContentBlock>
+                {
+                    new TextContentBlock { Type = "text", Text = output }


Should the tool call result be of Type text or json?

Aniruddh25

Some comments can be addressed as a followup - e.g. testing with authenticated, using SqlResponseHelper to create the McpResponse.

But some need to be addressed now - e.g. what are the expected output fields? only keys or all the fields?

Aniruddh25 · 2025-10-09T23:06:52Z

src/Azure.DataApiBuilder.Mcp/BuiltInTools/UpdateRecordTool.cs

+            IServiceProvider serviceProvider,
+            CancellationToken cancellationToken = default)
+        {
+            ILogger<UpdateRecordTool>? logger = serviceProvider.GetService<ILogger<UpdateRecordTool>>();


How do we ensure the configuration check to enable the tool is propagated to whether we expose the tool or not?

anushakolan added 3 commits September 26, 2025 10:05

[MCP] Added the update-record tool implementation.

7b92adb

Addedread.me and some cleanups

8d347b5

Format issues fix

4c591fc

anushakolan marked this pull request as ready for review October 1, 2025 05:22

anushakolan requested review from Aniruddh25 and aaronburtle as code owners October 1, 2025 05:22

Copilot AI review requested due to automatic review settings October 1, 2025 05:22

anushakolan requested review from RubenCerna2079, souvikghosh04, akashkumar58, neeraj-sharma2592, sourabh1007, vadeveka, Alekhya-Polavarapu and rusamant as code owners October 1, 2025 05:22

anushakolan self-assigned this Oct 1, 2025

anushakolan added the mcp-server label Oct 1, 2025

anushakolan added this to Data API builder Oct 1, 2025

github-project-automation bot moved this to Todo in Data API builder Oct 1, 2025

anushakolan linked an issue Oct 1, 2025 that may be closed by this pull request

[Enh]: Add DML tool: update_record #2829

Open

6 tasks

Copilot AI reviewed Oct 1, 2025

View reviewed changes

anushakolan and others added 2 commits September 30, 2025 23:22

Update docs/Testing/mcp-inspector-testing.md

2391c19

Co-authored-by: Copilot <[email protected]>

Update docs/Testing/mcp-inspector-testing.md

0750824

Co-authored-by: Copilot <[email protected]>

Aniruddh25 reviewed Oct 7, 2025

View reviewed changes

Aniruddh25 reviewed Oct 9, 2025

View reviewed changes

src/Azure.DataApiBuilder.Mcp/BuiltInTools/UpdateRecordTool.cs Show resolved Hide resolved

aaronburtle reviewed Oct 9, 2025

View reviewed changes

Aniruddh25 reviewed Oct 9, 2025

View reviewed changes

src/Azure.DataApiBuilder.Mcp/BuiltInTools/UpdateRecordTool.cs Show resolved Hide resolved

Aniruddh25 reviewed Oct 9, 2025

View reviewed changes

Aniruddh25 requested changes Oct 9, 2025

View reviewed changes

github-project-automation bot moved this from Todo to Review In Progress in Data API builder Oct 9, 2025

Aniruddh25 reviewed Oct 9, 2025

View reviewed changes

	throw new ArgumentException("Keys are required to update an entity");
	throw new ArgumentException($"Key value for '{kv.Key}' cannot be null or empty.");

	private static bool TryResolveAuthorizedRole(
	private static bool TryResolveAuthorizedRoleHasPermission(

	"No entity found with the given key.",
	"No record found with the given key.",

[MCP] Added the update-record tool implementation. #2888

Are you sure you want to change the base?

[MCP] Added the update-record tool implementation. #2888

Conversation

anushakolan commented Sep 26, 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?

Valid Cases

Failure Cases

Sample Request(s)

Uh oh!

anushakolan commented Oct 1, 2025

Uh oh!

azure-pipelines bot commented Oct 1, 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!

Uh oh!

Copilot AI Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

Aniruddh25 Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anushakolan commented Oct 1, 2025

Uh oh!

azure-pipelines bot commented Oct 1, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Aniruddh25 Oct 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

aaronburtle Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Aniruddh25 Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

anushakolan commented Sep 26, 2025 •

edited

Loading

Aniruddh25 Oct 9, 2025 •

edited

Loading

Aniruddh25 Oct 7, 2025 •

edited

Loading

aaronburtle Oct 9, 2025 •

edited

Loading

Aniruddh25 Oct 9, 2025 •

edited

Loading