# modelcontextprotocol/csharp-sdk architecture

> Architecture diagram of the GitHub repository modelcontextprotocol/csharp-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/modelcontextprotocol/csharp-sdk
- Repository: https://github.com/modelcontextprotocol/csharp-sdk

## Overview

##### Main Components
- Core SDK Library: Represented by the main source under “src/ModelContextProtocol” which includes:
– Client components (e.g., IMcpClient, McpClient, McpClientFactory) allowing applications to consume MCP servers.
– Server components (e.g., IMcpServer, McpServer, McpServerFactory) that configure, start, and manage an MCP server.
– Protocol definitions: “Protocol/Messages”, “Protocol/Types”, and “Protocol/Transport”. These define the JSON RPC messages, types for tool calls, notifications, error codes, and transport abstraction.
– Shared utilities and logging mechanisms (e.g., “Logging/Log.cs”, “Utils/Json”, “Utils/ProcessHelper.cs”).

- Communication Transports: The SDK supports various transport mechanisms. Under “Protocol/Transport” you see providers for:
– Stdio-based transports (e.g., StdioClientTransport, StdioServerTransport)
– Server-Sent Events (SSE) based transport (e.g., HttpListenerSseServerTransport, SseClientTransport)
– HTTP listeners and other potential modes.

- Polyfills and Common Utilities: Found under “src/Common/Polyfills” demonstrate that compatibility and additional functionality for standard .NET libraries is provided as part of the SDK.

- Samples: Located in the “samples” directory, they offer real applications demonstrating how to:
– Build an ASP.NET Core SSE server.
– Create and use chat clients integrated with available tools.
– Run a “TestServer with Hosting” example.

- Testing: The “tests” folder includes focused tests on the client, server, protocol handling, transport integration, and utilities to validate core protocol behavior.

##### Out Relationships and Interactions
- Client and Server Communication:
– Illustrate the use of different transport channels (Stdio, SSE, HttpListener) which are abstracted by the Protocol/Transport layer.

- Protocol Exchange:
– The “Protocol/Messages” and “Protocol/Types” directories define the schema (e.g., JsonRpcMessage, JsonRpcNotification, RequestId, etc.), which are exchanged between the client and server.

- Tools and Integration Points:
– Highlight that server-side “tools” (registered by tools registration extensions like “WithTools” in the samples) are discovered through reflection (with attributes like [McpTool] and [McpToolType]).
– Emphasize how these tools interface with client calls, thereby forming an extension point for LLM interactions.

##### Architectural Patterns and Design Principles
- Configurability: The presence of builder extension methods (e.g., “WithStdioServerTransport”, “WithTools”) and configuration objects (e.g., McpClientOptions, McpServerConfig) shows that the system is configurable. Represent these configuration objects as connectors or interfaces between client/server and their underlying transport/protocol engine.

##### Technologies and Frameworks to Highlight
- .NET's Host and Dependency Injection: Samples show usage of “Host.CreateEmptyApplicationBuilder” and built-in dependency injection to set up the server.
- JSON and RPC Handling: The project defines converters and utilities for JSON RPC (e.g., JsonRpcMessageConverter, McpJsonUtilities), which are integral in serializing and deserializing protocol messages.
- HTTP and SSE: In the samples (e.g., AspNetCoreSseServer) and in the transport implementations (HTTP/SSE clients), there is integration with ASP.NET Core frameworks and HTTP listeners.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Level Core SDK
    CoreSDK["Core SDK Library"]:::core
    click CoreSDK "https://github.com/modelcontextprotocol/csharp-sdk/tree/main/src/ModelContextProtocol"

    %% Client Side Subgraph
    subgraph "Client Side"
        MCPClient["MCP Client (McpClientFactory, IMcpClient)"]:::client
        click MCPClient "https://github.com/modelcontextprotocol/csharp-sdk/tree/main/src/ModelContextProtocol/Client"
        ClientConf["McpClientOptions (Configuration)"]:::client
    end

    %% Transport/Protocol Layer Subgraph
    subgraph "Transport/Protocol Layer"
        ProtoMessages["Protocol Messages (JSON RPC)"]:::protocol
        click ProtoMessages "https://github.com/modelcontextprotocol/csharp-sdk/tree/main/src/ModelContextProtocol/Protocol/Messages"
        ProtoTypes["Protocol Types"]:::protocol
        click ProtoTypes "https://github.com/modelcontextprotocol/csharp-sdk/tree/main/src/ModelContextProtocol/Protocol/Types"
        Transport["Transport Abstraction (Stdio, SSE, HttpListener)"]:::transport
        click Transport "https://github.com/modelcontextprotocol/csharp-sdk/tree/main/src/ModelContextProtocol/Protocol/Transport"
    end

    %% Server Side Subgraph
    subgraph "Server Side"
        MCPServer["MCP Server (McpServerFactory, IMcpServer)"]:::server
        click MCPServer "https://github.com/modelcontextprotocol/csharp-sdk/tree/main/src/ModelContextProtocol/Server"
        ToolReg["Tool Registration & Execution"]:::server
        ServerConf["McpServerConfig (Configuration)"]:::server
    end

    %% Common Utilities & Polyfills Subgraph
    subgraph "Common Utilities & Polyfills"
        Logging["Logging"]:::util
        click Logging "https://github.com/modelcontextprotocol/csharp-sdk/blob/main/src/ModelContextProtocol/Logging/Log.cs"
        JSONUtil["JSON & Process Utilities"]:::util
        click JSONUtil "https://github.com/modelcontextprotocol/csharp-sdk/tree/main/src/ModelContextProtocol/Utils/Json"
        ProcessHelper["Process Helper"]:::util
        click ProcessHelper "https://github.com/modelcontextprotocol/csharp-sdk/blob/main/src/ModelContextProtocol/Utils/ProcessHelper.cs"
        Polyfills["Polyfills"]:::util
        click Polyfills "https://github.com/modelcontextprotocol/csharp-sdk/tree/main/src/Common/Polyfills"
    end

    %% Samples & Testing Subgraph
    subgraph "Samples & Testing"
        Samples["Samples (AspNetCoreSseServer, ChatWithTools, TestServerWithHosting)"]:::samples
        click Samples "https://github.com/modelcontextprotocol/csharp-sdk/tree/main/samples"
        Testing["Testing (Protocol, Client, Server, Transport)"]:::test
        click Testing "https://github.com/modelcontextprotocol/csharp-sdk/tree/main/tests"
    end

    %% Connections from Core SDK to Client and Server
    CoreSDK --> MCPClient
    CoreSDK --> MCPServer

    %% Client to Transport/Protocol connections
    MCPClient -->|"JSON_RPC_Request"| Transport
    Transport -->|"JSON_RPC_Request"| MCPServer
    MCPServer -->|"JSON_RPC_Response"| Transport
    Transport -->|"JSON_RPC_Response"| MCPClient

    %% Internal Protocol Layer connection
    ProtoMessages -->|"defines_types"| ProtoTypes

    %% Server internal connection for tool registration
    MCPServer -->|"calls"| ToolReg

    %% Configuration connections
    ClientConf --- MCPClient
    ServerConf --- MCPServer

    %% Utilities connections from Client and Server (dashed arrows)
    MCPClient --- Logging
    MCPClient --- JSONUtil
    MCPClient --- Polyfills
    MCPServer --- Logging
    MCPServer --- ProcessHelper
    MCPServer --- Polyfills

    %% Samples & Testing connections
    Samples --- CoreSDK
    Testing --- CoreSDK

    %% Style Definitions
    classDef core fill:#f99,stroke:#333,stroke-width:2px;
    classDef client fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef server fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef protocol fill:#fce8cf,stroke:#333,stroke-width:2px;
    classDef transport fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef util fill:#e2e3e5,stroke:#333,stroke-width:2px;
    classDef samples fill:#d1ecf1,stroke:#333,stroke-width:2px;
    classDef test fill:#f8d7da,stroke:#333,stroke-width:2px;
```
