Real MCP Tools — JSON-RPC 2.0 over stdio

1 What Is Real MCP?

The problem in one sentence: Claude is brilliant at reading and reasoning, but it lives in a text bubble — it cannot open a database connection, cannot call your REST API, cannot look at your file system.

MCP (Model Context Protocol) is the standardised solution. It is a protocol — like HTTP, but for AI tools — that defines how a client (your web app) discovers and calls tools exposed by a server (a separate process hosting the tool implementations).

This project uses the official ModelContextProtocol v1.3.0 NuGet package with real JSON-RPC 2.0 communication over stdin/stdout (stdio). That means:

• The tool server (NexaFlowDemo.McpServer) is a separate console app that reads JSON-RPC requests from stdin and writes responses to stdout.
• The client (RealMcpClientService in the web app) spawns McpServer as a subprocess and talks to it through StdioClientTransport.
• Claude never sees any of this — it only sees the tool list and JSON results, same as before.

2 Writing a Real MCP Tool — Attributes Replace Interfaces

In the previous (simulated) approach, a tool implemented IMcpTool with a Definition property and an InvokeAsync method. In the real MCP approach, you just write a static class with attributes. The SDK discovers and registers everything automatically.

Three attributes do the work:

• [McpServerToolType] on the class — marks the class as a container of MCP tools
• [McpServerTool(Name = "...", ReadOnly = true)] on each method — names the tool and marks read-only operations
• [Description("...")] on the method and each parameter — generates the JSON Schema Claude reads to understand the tool

using System.ComponentModel;
using System.Text.Json;
using ModelContextProtocol.Server;

namespace NexaFlowDemo.McpServer.Tools;

[McpServerToolType]
public static class InventoryTools
{
    [McpServerTool(Name = "inventory_lookup", ReadOnly = true)]
    [Description("Look up current stock level and reorder threshold for a SKU.")]
    public static string LookupInventory(
        [Description("The product SKU code, e.g. NF-SKU-001")] string sku)
    {
        // ... look up in-memory data ...
        return JsonSerializer.Serialize(new
        {
            success = true,
            result  = new { sku, quantity = 250, reorder_threshold = 50, status = "In Stock" }
        });
    }
}

Compare this to the old IMcpTool approach: no interface, no McpToolDefinition object, no McpInvokeResponse wrapper, no Dictionary<string,string> input parsing. The SDK generates the JSON schema from [Description] and handles all the request/response serialisation.

3 Tool Registration in McpServer — WithToolsFromAssembly

All 9 tool classes are discovered automatically — you do not register them one by one. The McpServer's Program.cs is minimal:

var host = Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services
            .AddMcpServer()
            .WithStdioServerTransport()
            .WithToolsFromAssembly(Assembly.GetExecutingAssembly(), jsonOptions);

        // Services the tool methods may need (e.g. embedding service for RAG)
        services.AddSingleton<IEmbeddingService>(new SimulatedDenseEmbeddingService(384));
        services.AddSingleton<IVectorStore, InMemoryVectorStore>();
        // ... IDocumentStore, KnowledgeBaseSeeder ...
    })
    .Build();

await host.RunAsync();

WithToolsFromAssembly scans the assembly for all classes marked [McpServerToolType] and registers their methods as MCP tools. Adding a new tool is: create a class with the right attributes → the SDK registers it automatically on next startup.

4 Every Tool in This Project

This project has 9 tools (no agent_delegation tool — that simulated approach is replaced by the real subprocess model):

5 RealMcpClientService — The Bridge

RealMcpClientService implements IMcpServerService — the same interface ReactAgent has always used. The agent doesn't know or care that tool calls now cross a subprocess boundary. The service handles:

1. Lazy init: The McpServer subprocess is started the first time any tool is called (protected by SemaphoreSlim to avoid races on concurrent requests).
2. Auto-detect path: ResolveServerCommand() walks from the Web project's binary to the sibling NexaFlowDemo.McpServer bin output, finding the server DLL automatically without hard-coded paths.
3. ListTools: Calls McpClient.ListToolsAsync() → converts McpClientTool objects into McpToolDefinition for the system prompt by parsing tool.JsonSchema.
4. InvokeAsync: Calls McpClient.CallToolAsync(toolName, args) → reads result.Content[0].Text → wraps in McpInvokeResponse.

// Initialise once — spawns the McpServer process
private async Task EnsureInitializedAsync(CancellationToken ct)
{
    if (_client != null) return;
    await _initLock.WaitAsync(ct);
    try
    {
        if (_client != null) return;
        var transport = new StdioClientTransport(new StdioClientTransportOptions
        {
            Command          = "dotnet",
            Arguments        = ["exec", ResolveServerCommand()],
            Name             = "NexaFlowDemoMcpServer",
            WorkingDirectory = Path.GetDirectoryName(ResolveServerCommand())
        });
        _client = await McpClient.CreateAsync(transport, cancellationToken: ct);
    }
    finally { _initLock.Release(); }
}

// List tools — called when building the system prompt
public IReadOnlyList<McpToolDefinition> ListTools()
{
    // McpClient.ListToolsAsync() returns ValueTask<IList<McpClientTool>>
    var mcpTools = _client!.ListToolsAsync().GetAwaiter().GetResult();
    return mcpTools.Select(t => ConvertToDefinition(t)).ToList();
}

// Invoke a tool — called from the agent loop
public async Task<McpInvokeResponse> InvokeAsync(string toolName, ...)
{
    var result = await _client!.CallToolAsync(toolName, args, cancellationToken: ct);
    var text   = result.Content.OfType<TextContentBlock>().FirstOrDefault()?.Text ?? "";
    return new McpInvokeResponse { Success = !result.IsError, Result = text };
}

6 How Tools Appear in the System Prompt

The agent calls _mcp.ListTools() and formats each tool into the system prompt — exactly the same XML format as before. Claude never knows whether the tools came from a simulated in-process registry or a real subprocess. It only sees this:

<tools>
  <tool name="inventory_lookup">
    <description>Look up current stock level and reorder threshold for a SKU.</description>
    <param name="sku" type="string" required="True">The product SKU code, e.g. NF-SKU-001</param>
  </tool>
  <tool name="erp_connector">
    <description>SAP-compatible ERP actions: create_po, get_po, post_gr, get_financials. Pass action param to choose.</description>
    <param name="action" type="string" required="True">ERP action to perform</param>
    <param name="supplier_id" type="string" required="False">Supplier ID for create_po</param>
    ...
  </tool>
  ...
</tools>

The parameters are extracted by RealMcpClientService.ExtractParameters(), which walks the tool.JsonSchema JsonElement to find the properties and required arrays that the SDK generated from the [Description] attributes.

7 Tool Descriptions — Good vs Bad

The [Description("...")] on a tool method is what Claude reads to decide whether to call this tool. It cannot see your code — the description is its only guide.

8 ErpTools — Multi-Action Tool

Most tools do one thing. ErpTools exposes a single erp_connector tool that routes by an action parameter:

[McpServerToolType]
public class ErpTools
{
    [McpServerTool(Name = "erp_connector", ReadOnly = false)]
    [Description("SAP-compatible ERP connector. Actions: create_po, get_po, post_gr, get_financials.")]
    public string ExecuteErpAction(
        [Description("Action: create_po | get_po | post_gr | get_financials")] string action,
        [Description("Supplier ID for create_po")] string? supplier_id = null,
        [Description("PO number for get_po / post_gr")] string? po_number = null,
        [Description("Period for get_financials, e.g. Q1-2026")] string? period = null)
    {
        return action switch
        {
            "create_po"    => CreatePurchaseOrder(supplier_id),
            "get_po"       => GetPurchaseOrder(po_number),
            "post_gr"      => PostGoodsReceipt(po_number),
            "get_financials" => GetFinancials(period),
            _              => JsonSerializer.Serialize(new { success = false, error = $"Unknown action: {action}" })
        };
    }
    // ... private methods for each action ...
}

9 Summary

• Real MCP uses JSON-RPC 2.0 over stdio. The McpServer is a separate console process; the web app is the client.
• Write tools with [McpServerToolType] on the class and [McpServerTool] + [Description] on each method — no interface, no manual schema.
• WithToolsFromAssembly scans and registers all tool classes automatically — adding a new tool is just adding a new class with the right attributes.
• RealMcpClientService spawns the McpServer subprocess lazily (on first use), auto-detects its path, and bridges IMcpServerService to the real MCP client API.
• Key API: McpClient.ListToolsAsync() → direct list; McpClient.CallToolAsync(name, args) → CallToolResult; read text from result.Content[0].Text.
• The agent's system prompt XML format is unchanged — Claude still sees <tool name="..."><description>...</description></tool>.
• This project has 9 tools (no agent_delegation — the subprocess model itself provides the separation that delegation was simulating).