Serializing JSON as return value from Tool corrupts string resulting in Deserialization failures on client

[brandonh-msft]

Describe the bug

In my implementation I am returning a complex object from my tool, so I JsonSerializer.Serialize(obj) it and return string from my tool.

When I get the value back on the other side, numerous characters in the JSON are escaped (\u\\\....) and so attempting to deserialize the value in .Text blows up.

To Reproduce
Steps to reproduce the behavior:

1. Return a string created from JSON-serializing an object from an McpServerTool implementation.
2. Attempt to deserialize the value of .Text on the client.

Expected behavior
Strings shouldn't get munged by anything from return time to arrival on the client.

Logs
String value upon return from Tool:

{"completion":[{"Role":{"Label":"system"},"Items":[{"$type":"TextContent","Text":"You are an expert data search ass

String value on client side when attempting to deserialize:

{"text":"{\u0022completion\u0022:[{\u0022Role\u0022:{\u0022Label\u0022:\u0022system\u0022},\u0022Items\u0022:[{\u0022$type\u0022:\u0022TextContent\u0022,\u0022Text\u0022:\u0022You are an expert data search 

Additional context
I've tried taking the bytes of the JSON value and wrapping them up in DataContent but this fails as well. Similarly, I've tried returning not just a string but a TextContent object also to no avail, even if I set RawRepresentation on it.

[stephentoub]

Can you please share a repro?

[eiriktsarpalis]

That's the default escaping behaviour in System.Text.Json and the MCP sdk. We disable it by default in MEAI but IIRC we decided to keep it in the MCP sdk because some of the existing client implementations (Claude desktop?) were rejecting unescaped JSON strings.

[PederHP]

That's the default escaping behaviour in System.Text.Json and the MCP sdk. We disable it by default in MEAI but IIRC we decided to keep it in the MCP sdk because some of the existing client implementations (Claude desktop?) were rejecting unescaped JSON strings.

I'd say the client is the problem then. MEAI does this right, I'd say, because there's not a single LLM API I know of that supports structured tool results. It is passed to the model as a string, so the client shouldn't even begin to try parsing the tool result. It should just pass it as-is to the model.

Tools return Text or (Image) Data. Serializing complex types to JSON is a tool design choice - it's equally valid to return xml, markdown or any other format. I expect Claude models would even perform better with (pseudo)xml than JSON for complex tool results.

Edit: I can see with more thought that because the result is actually returned in JSON-RPC it's not entirely unreasonable.

I'd say it's a bug if the SDK takes a string-returning tool and does any kind of escaping on it. We can't assume it's JSON.

I have had bugs in production systems from passing JSON string escaped text into models, due to how tokenization works it can give some really subtle bugs. So while it seems like a reasonable thing to do it means that clients have to treat servers that escape and those that'll don't differently. It's a tricky one because client SDKs must unescape if the server escapes.

[brandonh-msft]

Ok, well, here's how to work around this "non-bug" - for those who stumble across this issue in the future:

When returning data back from your tool, encode the JSON Serialized result and put it in a DataContent object with the application/json content type (just for good measure, not sure this actually affects anything).

var jsonResponseBytes = Encoding.UTF8.GetBytes(toolJsonResponse);

return new DataContent(new ReadOnlyMemory<byte>([.. jsonResponseBytes]), "application/json");

Then, in the MCP Server you'll get this DataContent object back as the response from CallToolAsync with Text populated, prefixed, and base64 encoded magically. (Data will be null 🤷🏻‍♂️). So you do some shenanigans to parse out just the b64 value, decode it, and then deserialize that into your object (in my case a simple ToolCompletion object).

var toolResponse = await _mcpClient!.CallToolAsync(toolName, toolParams, cancellationToken: cancellationToken);

var b64string = JsonSerializer.Deserialize<JsonElement>(toolResponse.Content.Single().Text!).GetProperty("uri").GetString()!;
var json = Encoding.UTF8.GetString(Convert.FromBase64String(b64string[(b64string.IndexOf(',') + 1)..]));
var toolCompletion = JsonSerializer.Deserialize<ToolCompletion>(json)!;

This is the best way I've found to keep the value from being munged.

[eiriktsarpalis]

@brandonh-msft could you share a repro please? We can then provide a relevant recommendation (typically it involves passing a custom JsonSerializerOptions which sets its Encoder property to JavaScriptEncoder.UnsafeRelaxedJsonEscaping which disables escaping withing JSON strings).

[carlos-ferreira]

The same issue happens if you try to use an MCPClient with a Filesystem MCP server like this one: https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem.
When calling the edit_file tool, the json is sent like this:

{
    "Id": "vvyRL797xP5bUSNd5zWIEEmZlZhPHFfG",
    "PluginName": "Files",
    "FunctionName": "edit_file",
    "Arguments": {
        "path": "D:\\AI\\Instructions\\Journals\\tasklist.md",
        "edits": [{\u0022oldText\u0022:\u0022- Go to the bank \u0022,\u0022newText\u0022:\u0022- [ ] Go to the bank \\n\u0022},{\u0022oldText\u0022:\u0022 Send daily standup email\u0022,\u0022newText\u0022:\u0022 - [ ] Send daily standup email\\n\u0022}],
        "dryRun": false
    }
}

Instead of :

{
    "Id": "vvyRL797xP5bUSNd5zWIEEmZlZhPHFfG",
    "PluginName": "Files",
    "FunctionName": "edit_file",
    "Arguments": {
        "path": "D:\\AI\\Instructions\\Journals\\tasklist.md",
        "edits": [{"oldText":"- Go to the bank ","newText":"- [ ] Go to the bank \\n"},{"oldText":" Send daily standup email","newText":" - [ ] Send daily standup email\\n"}],
        "dryRun": false
    }
}

[eiriktsarpalis]

When calling the edit_file tool, the json is sent like this

That seems to be producing invalid JSON. Could you share a repro please?

[carlos-ferreira]

I'm looking into it, the issue might be on Semantic Kernel's side.

The test I'm making is the following, I have a markdown file with the following contents:

# Task List

## Personal

- [ ] Cleanup kitchen
- [ ] Do laundry

## Work

- [ ] Go to the bank 
- [ ] Pay taxes
- [ ] Send daily standup email

Then I'll execute an MCP tool to update the task list and set one or two items as done.

To isolate the problem, I copied the getting started code and tried to repro without semantic kernel.

The code goes something like this:

var currentPath = Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location);
var clientTransport = new StdioClientTransport(new StdioClientTransportOptions
{
    Name = "Filesystem",
    Command = "npx",
    Arguments = ["-y",
    "@modelcontextprotocol/server-filesystem",
    currentPath]
});

var client = await McpClientFactory.CreateAsync(clientTransport);
var serializerOptions = new JsonSerializerOptions(McpJsonUtilities.DefaultOptions)
{
    Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
    AllowTrailingCommas = true,
    WriteIndented = true,
};

Console.WriteLine($"Listing tools:{Environment.NewLine}");
// Print the list of tools available from the server.
foreach (var tool in await client.ListToolsAsync(serializerOptions))
{
    Console.WriteLine($"{tool.Name}"); // These tools have long descriptions, listing only their names
}

Console.WriteLine($"File contents before update:{Environment.NewLine}");
Console.WriteLine(File.ReadAllText($"{currentPath}\\Tasklist.md"));

// The strings in the params below are generated by the LLM, using them staticly just as an example
var toolCallArgs = new Dictionary<string, object?>()
{
    ["path"] = "{currentPath}\\Tasklist.md",
    ["edits"] = "[{\"oldText\":\"- [ ] Cleanup kitchen\",\"newText\":\"- [X] Cleanup kitchen\"},{\"oldText\":\"- [ ] Do laundry\",\"newText\":\"- [X] Do laundry\"}]",
    ["dryRun"] = false
};

// Execute a tool (this would normally be driven by LLM tool invocations).
var result = await client.CallToolAsync(
    "edit_file",
    toolCallArgs,
    serializerOptions: serializerOptions,
    cancellationToken: CancellationToken.None);

Console.WriteLine($"{Environment.NewLine}Executing the tool edit_file...");
Console.WriteLine($"{Environment.NewLine}Tool call arguments:{Environment.NewLine}{JsonSerializer.Serialize(toolCallArgs, serializerOptions)}");

// echo always returns one and only one text content object
Console.WriteLine(result.Content.First(c => c.Type == "text").Text);

Console.WriteLine($"{Environment.NewLine}File contents after the update:{Environment.NewLine}");
Console.WriteLine(File.ReadAllText($"{currentPath}\\Tasklist.md"));


Console.WriteLine($"{Environment.NewLine}Press any key to end.");
Console.ReadKey();

This is the output that I get:

Listing tools:

read_file
read_multiple_files
write_file
edit_file
create_directory
list_directory
directory_tree
move_file
search_files
get_file_info
list_allowed_directories
File contents before update:

# Task List

## Personal

- [ ] Cleanup kitchen
- [ ] Do laundry

## Work

- [ ] Go to the bank
- [ ] Pay taxes
- [ ] Send daily standup email

Executing the tool edit_file...

Tool call arguments:
{
  "path": "{currentPath}\\Tasklist.md",
  "edits": "[{\"oldText\":\"- [ ] Cleanup kitchen\",\"newText\":\"- [X] Cleanup kitchen\"},{\"oldText\":\"- [ ] Do laundry\",\"newText\":\"- [X] Do laundry\"}]",
  "dryRun": false
}
Error: Invalid arguments for edit_file: [
  {
    "code": "invalid_type",
    "expected": "array",
    "received": "string",
    "path": [
      "edits"
    ],
    "message": "Expected array, received string"
  }
]

File contents after the update:

# Task List

## Personal

- [ ] Cleanup kitchen
- [ ] Do laundry

## Work

- [ ] Go to the bank
- [ ] Pay taxes
- [ ] Send daily standup email

Press any key to end.

I see that the tool call fails because the array is wrapped in quotes, but the serialization is not invalid as I mentioned before.
For this reason, I believe this might be a serialization issue from Semantic Kernel's side when invoking the tools during chats with LLMs.

I'll try to dig deeper on this, as I don't see any way to set serialization options on Semantic Kernel's side.

[carlos-ferreira]

@eiriktsarpalis Got a repro on https://github.com/carlos-ferreira/SemanticKernel.MCP.BrokenJson .
Again, I'm not sure if this is an MCP problem or SK problem, more inclined to SK at this point.

[eiriktsarpalis]

I would suggest trying to further minimize the repro until you can isolate it to a specific component.

[eiriktsarpalis]

@carlos-ferreira I took a quick look at your repro, it appears to be using the third-party ModelContextProtocol-SemanticKernel library. I would suggest either

• Creating a repro that does not include that dependency or
• File an issue in the repo of the third-party package.