What's the intended usage for IMcpClient.ServerCapabilities?

[raffaeler]

Pre-submission Checklist

• I have checked that this question would not be more appropriate as an issue in a specific repository
• I have searched existing discussions and documentation for answers

Question Category

• Protocol Specification
• SDK Usage
• Server Implementation
• General Implementation
• Documentation
• Other

Your Question

I am creating a generic McpClient and I am not sure what is the intended usage for IMcpClient.ServerCapabilities.
I expect the ServerCapabilities to be used by the MCP Server but this object is also available on the client side where most of the properties of PromptsCapability, ToolsCapability, etc. are tagged with JsonIgnore.

Are the ServerCapabilities being refactored into a smaller object representing only the info that is exchanged during the iniitalization with the MCP Server?

[PederHP]

You generally don't need to manipulate the ServerCapabilities directly. It is used by the server during the init handshake to tell the client the servers capabilities. There's a similar object, ClientCapabilities, being passed by the client to the server. For example, if a server doesn't support tools, it doesn't make sense for the client to call ListTools. If the client doesn't support roots, the server shouldn't try to list those. There's a bit more complexity, as it also includes stuff like whether there's support for subscriptions and such, but you really don't need to concern yourself with it for your first server - and perhaps not ever - at least not implementation-wise.

Unless you're working at a very low level where you're manually creating handlers, you can just focus on adding the tools, prompts, resources, etc. that you want to expose, and the SDK will then handle providing the right capabilities to the client.

[raffaeler]

Thanks @PederHP , what you say looks reasonable.
Anyway, the class is declared serializable and exposed on IMcpClient which implies it should be used to list the server capabilities.

IMO the property IMcpClient.ServerCapabilities should only expose something that is usable on the client side.

[PederHP]

Well it is used to list server capabilities, I am sorry if that was unclear. And if you're doing the raw protocol handling yourself, you have to set the requisite capabilities on it (server-side). It's serializable because it's the type defined in the protocol as having this role. See: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle and https://github.com/modelcontextprotocol/modelcontextprotocol/blob/09998fe1ad2e48349682af8c92e0ed25c90e87c0/schema/2025-06-18/schema.ts#L243-L287

But yeah, I can see how the naming can seem counterintuitive at first glance. But once it's really not something to worry about for the vast majority of use cases, as the SDK takes care of things.

[raffaeler]

I understand the goal, but this makes sense in dynamic languages where the type is shaped by the serialization message.
In C# instead, we have a type that expose all the handlers that will be always null on the client side. This leads to confusion because it is exposed as a client property while it only makes sense when used on the server side.

BTW My primary goal here is to understand what are the capabilities of each server before enumerating the resources/prompts/tools which is a time-expensive operation. At the very end, these capabilities on the client side are just 4 Booleans which is why I believe it's worth changing the way they are shaped on the client-side.

[PederHP]

Ah got it, thanks for the elaboration. Yeah I can see how the way the capabilities type also acts as the carrier of handlers makes it a very ambiguous type. That's true. It's a good point that the shape on the client side does not need to correspond to the internal object. However there's also value to matching the other languages - and it's more than just four booleans, as there's also the ListChanged flags etc, and there are some protocol spec proposals that add further flags.

But sorry, I was misunderstanding you earlier. The client side SDK should arguably short-circuit if you enumerate a capability not present on the server as advertised in capabilities. A client is not supposed to actually send the list messages to a server which did not advertise that capability. But the SDK actually doesn't do this.

csharp-sdk/src/ModelContextProtocol.Core/Client/McpClientExtensions.cs

Lines 92 to 124 in 52b1ed5

	public static async ValueTask<IList<McpClientTool>> ListToolsAsync(
	this IMcpClient client,
	JsonSerializerOptions? serializerOptions = null,
	CancellationToken cancellationToken = default)
	{
	Throw.IfNull(client);
	serializerOptions ??= McpJsonUtilities.DefaultOptions;
	serializerOptions.MakeReadOnly();
	List<McpClientTool>? tools = null;
	string? cursor = null;
	do
	{
	var toolResults = await client.SendRequestAsync(
	RequestMethods.ToolsList,
	new() { Cursor = cursor },
	McpJsonUtilities.JsonContext.Default.ListToolsRequestParams,
	McpJsonUtilities.JsonContext.Default.ListToolsResult,
	cancellationToken: cancellationToken).ConfigureAwait(false);
	tools ??= new List<McpClientTool>(toolResults.Tools.Count);
	foreach (var tool in toolResults.Tools)
	{
	tools.Add(new McpClientTool(client, tool, serializerOptions));
	}
	cursor = toolResults.NextCursor;
	}
	while (cursor is not null);
	return tools;
	}

@halter73 What do you think, should this short-circuit if the capability isn't present? I seem to recall it is required by the server to advertise the capability, so it's always an error to send the request it if it isn't.

[raffaeler]

You are welcome @PederHP.
The 4 booleans are:

• Prompts.ListChanged
• Resources.Subscribe
• Resources.ListChanged
• Tools.ListChanged

Beyond that, there is only the Experimental dicitionary.

I would personally create a separate type to represent these values.
Another possibility would be to create a base class with just those values. The server instead could derive these types to add the handlers that are currently marked with the JsonIgnoreAttribute.

HTH