How to Build a Fastio MCP Client in C# .NET

The Model Context Protocol (MCP) provides a standardized way for AI applications to communicate with external tools and data sources. When you build a Fastio MCP client in C# .NET, you create a direct bridge between your custom enterprise software and an intelligent file workspace.

This connection goes beyond simple file storage. When Intelligence is enabled for a workspace, uploaded files are indexed for semantic search and Retrieval-Augmented Generation (RAG). By integrating an MCP client, your .NET applications can programmatically search document contents and manage file permissions without relying on fragmented third-party APIs.

Unlike Python or Node.js ecosystems, there is scarce documentation on building custom MCP clients in strongly typed enterprise languages like C#. This guide fills that gap by providing production-ready implementation patterns for .NET environments.

Why Connect .NET to Fastio?

Enterprise development teams often need to connect legacy systems to modern AI capabilities. Instead of building custom integration layers, a C# MCP client allows your application to consume tools exactly as an AI agent would. This means your .NET application can read the same semantic indexes, execute the same workspace operations, and rely on the same granular permissions and file version history as the leading Large Language Models.

Helpful references: Fastio Workspaces, Fastio Collaboration, and Fastio AI.

• How to Build MCP Servers with .NET: A C# Developer's GuideBuilding MCP servers in .NET allows enterprise developers to expose existing business logic and data layers to AI...
• How to Build a Fastio MCP Client in SwiftBuilding a Fastio MCP client in Swift requires establishing an SSE or HTTP connection to the Fastio MCP server to...
• How to Build a Fastio MCP Client in ElixirBuilding a Fastio MCP client in Elixir uses OTP to maintain highly resilient, concurrent agent workspaces that...
• How to Build a Fastio MCP Client in PythonBuilding a Fastio MCP client in Python enables seamless file management capabilities within Python-based AI agent...
• How to Build a Fastio MCP Client in GolangGuide to building fastio mcp client golang: A Fastio MCP client in Golang uses Go's native concurrency model to...
• How to Build a Custom Fastio MCP ToolBuilding a custom Fastio MCP tool lets developers inject proprietary business logic directly into an agent's file...

More on this subject: MCP and Model Context Protocol (238 guides)

Before writing the client connection logic, you need to configure a .NET project with the appropriate dependencies. We recommend using a current .NET release, as recent framework versions include optimized networking components for streaming HTTP responses.

Start by creating a new console application or worker service. You will need to add a few fundamental packages to handle JSON serialization and HTTP resilience. The essential NuGet packages for connecting to an MCP server over Streamable HTTP in .NET are minimal, keeping your dependency tree clean.

dotnet new console -n FastIo.McpClient
cd FastIo.McpClient
dotnet add package System.Text.Json
dotnet add package Microsoft.Extensions.Http
dotnet add package Polly

Defining the Core Data Models

MCP communication relies on JSON-RPC 2.0. You must define C# records that represent the standard message structures. Records are ideal here because they provide immutable data semantics and concise syntax for serialization.

using System.Text.Json.Serialization;

public record JsonRpcRequest(
    [property: JsonPropertyName("jsonrpc")] string JsonRpc = "2.0",
    [property: JsonPropertyName("id")] string Id = "",
    [property: JsonPropertyName("method")] string Method = "",
    [property: JsonPropertyName("params")] object? Params = null
);

public record JsonRpcResponse(
    [property: JsonPropertyName("jsonrpc")] string JsonRpc.
    [property: JsonPropertyName("id")] string Id.
    [property: JsonPropertyName("result")] object? Result.
    [property: JsonPropertyName("error")] JsonRpcError? Error
);

public record JsonRpcError(
    [property: JsonPropertyName("code")] int Code.
    [property: JsonPropertyName("message")] string Message
);

These base models handle the structural requirements of the protocol. When your client receives a message from the server, it will deserialize the payload into these strongly typed records before passing them to your application logic.

Fastio exposes its MCP capabilities via Streamable HTTP at https://mcp.fast.io/mcp/tools. This transport mechanism is highly reliable for cloud environments because it operates over standard HTTPS ports and avoids the proxy complications often associated with WebSockets.

Every JSON-RPC message from your C# client is an HTTP POST to that one URL, with an Accept header that lists both application/json and text/event-stream. The server answers each POST with either a JSON body or a short Server-Sent Events stream that carries the reply. The response to initialize includes an Mcp-Session-Id header. Your client then sends the notifications/initialized notification, and every later request carries that session header plus an MCP-Protocol-Version header with the version the server agreed to. Because this client runs without a browser, it authenticates with a Fastio API key sent as a Bearer token on each request.

Building the Transport Class

The following implementation demonstrates how to post JSON-RPC messages and read either response format using HttpClient in C#.

using System;
using System.IO;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Json;
using System.Text.Json;
using System.Threading;
using System.Threading.Tasks;

public class FastIoMcpTransport : IDisposable
{
    private readonly HttpClient _httpClient;
    private readonly string _serverUrl;
    private string? _sessionId;
    private string? _protocolVersion;

public FastIoMcpTransport(string serverUrl, string apiKey)
    {
        _serverUrl = serverUrl; // https://mcp.fast.io/mcp/tools
        _httpClient = new HttpClient();
        _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");
        _httpClient.DefaultRequestHeaders.Add("Accept", "application/json, text/event-stream");
    }

public async Task<JsonRpcResponse?> SendPostRequestAsync(
        JsonRpcRequest request,
        CancellationToken cancellationToken = default)
    {
        using var message = new HttpRequestMessage(HttpMethod.Post, _serverUrl)
        {
            Content = JsonContent.Create(request)
        };
        AddSessionHeaders(message);

using var response = await _httpClient.SendAsync(
            message,
            HttpCompletionOption.ResponseHeadersRead,
            cancellationToken);

response.EnsureSuccessStatusCode();

if (response.Headers.TryGetValues("Mcp-Session-Id", out var values))
        {
            _sessionId = values.First();
        }

if (response.Content.Headers.ContentType?.MediaType == "text/event-stream")
        {
            using var stream = await response.Content.ReadAsStreamAsync(cancellationToken);
            using var reader = new StreamReader(stream);

while (!reader.EndOfStream && !cancellationToken.IsCancellationRequested)
            {
                var line = await reader.ReadLineAsync(cancellationToken);
                if (line != null && line.StartsWith("data: "))
                {
                    return JsonSerializer.Deserialize<JsonRpcResponse>(line.Substring(6));
                }
            }
            return null;
        }

return await response.Content.ReadFromJsonAsync<JsonRpcResponse>(
            cancellationToken: cancellationToken);
    }

public async Task SendNotificationAsync(
        string method,
        CancellationToken cancellationToken = default)
    {
        using var message = new HttpRequestMessage(HttpMethod.Post, _serverUrl)
        {
            Content = JsonContent.Create(new { jsonrpc = "2.0", method })
        };
        AddSessionHeaders(message);

// The server answers a notification with 202 Accepted and no body
        using var response = await _httpClient.SendAsync(message, cancellationToken);
        response.EnsureSuccessStatusCode();
    }

private void AddSessionHeaders(HttpRequestMessage message)
    {
        if (_sessionId != null)
        {
            message.Headers.Add("Mcp-Session-Id", _sessionId);
        }
        if (_protocolVersion != null)
        {
            message.Headers.Add("MCP-Protocol-Version", _protocolVersion);
        }
    }

public void Dispose()
    {
        _httpClient.Dispose();
    }
}

Notice the HttpCompletionOption.ResponseHeadersRead parameter. This modifier stops the HttpClient from buffering a streamed response, so your application can read the event that carries the reply as soon as it arrives.

After the initialize call returns, your client stores the Mcp-Session-Id value and the negotiated protocol version and sends both with every later request. All outbound JSON-RPC requests from your .NET application go to the same URL, https://mcp.fast.io/mcp/tools, as HTTP POST requests.

Give Your AI Agents Persistent Storage

Get generous storage and access to a consolidated MCP toolset. Built for building fast mcp client net workflows.

Try the MCP Server

With the transport layer established, your client can begin interacting with the workspace. According to the Fastio MCP Documentation, the platform provides a consolidated MCP toolset covering files, shares, metadata, and activity.

Sending the Initialization Request

Before calling any specific tools, the MCP specification requires the client to send an initialize request. This message announces the client's capabilities and protocol version to the server. Add the following method to the transport class: it records the version the server returns and then sends the notifications/initialized notification, which must come before any other call.

public async Task<JsonRpcResponse?> SendInitializeAsync()
{
    var request = new JsonRpcRequest
    {
        Id = Guid.NewGuid().ToString(),
        Method = "initialize",
        Params = new
        {
            protocolVersion = "2025-06-18",
            capabilities = new { },
            clientInfo = new
            {
                name = "DotNetEnterpriseClient",
                version = "1.0.0"
            }
        }
    };

var response = await SendPostRequestAsync(request);

// Send the negotiated version on every later request, then confirm initialization
    var result = (JsonElement)response!.Result!;
    _protocolVersion = result.GetProperty("protocolVersion").GetString();
    await SendNotificationAsync("notifications/initialized");

return response;
}

Calling Workspace Tools

Once initialized, your application can execute specific tools. If your .NET application needs to query the semantic index of a workspace, it can call the storage tool with the search action.

The workflow requires packaging the tool name and its arguments into a call_tool JSON-RPC method. This enables strict type-safe interactions with Fastio API endpoints.

public async Task ExecuteToolAsync(string workspaceId, string query)
{
    var request = new JsonRpcRequest
    {
        Id = Guid.NewGuid().ToString(),
        Method = "tools/call",
        Params = new
        {
            name = "storage",
            arguments = new
            {
                action = "search",
                profile_type = "workspace",
                profile_id = workspaceId,
                query = query,
                limit = 5
            }
        }
    };

var response = await SendPostRequestAsync(request);
    
    if (response.Error != null)
    {
        Console.WriteLine($"Tool execution failed: {response.Error.Message}");
        return;
    }

Console.WriteLine($"Search Results: {response.Result}");
}

This pattern applies to all available capabilities. Whether you are generating secure sharing links, retrieving file metadata, or managing access controls, the C# client standardizes the interaction. Because the Fastio workspace is inherently intelligent, uploading a file through the client automatically triggers indexing. The content becomes immediately available for subsequent searches or RAG queries.

Once the JSON-RPC response is received from the Fastio server, your application needs to map that dynamic JSON structure back into strongly typed C# objects. Because MCP tools return highly varied payloads, ranging from simple text summaries to complex arrays of semantic search results, handling serialization efficiently is essential. In current .NET versions, the System.Text.Json namespace provides powerful parsing capabilities. Rather than treating tool results as arbitrary object types, you can define specific response records for the tools you use most frequently.

public record SearchResultItem( [property: JsonPropertyName("file_id")] string FileId, [property: JsonPropertyName("score")] double Score, [property: JsonPropertyName("snippet")] string Snippet
); public record SearchWorkspaceResult( [property: JsonPropertyName("results")] List<SearchResultItem> Results, [property: JsonPropertyName("total_found")] int TotalFound
);

When handling the tool execution response, you inspect the tool name and cast the result accordingly. For high-performance enterprise applications, implementing source-generated JSON serializers reduces the memory allocation overhead associated with parsing large file indexes. This approach ensures that your C# business logic remains clean, type-safe, and decoupled from raw protocol implementation details.

Building a reliable integration requires more than just successful network calls. Enterprise applications must handle transient failures, manage state safely, and secure credentials when interacting with external workspaces.

Resilience and Retries

Network connections can drop. When integrating Fastio over Streamable HTTP, your C# client must automatically detect failed requests and send them again. Using the Polly library provides a clean way to implement exponential backoff policies.

using Polly;
using System.Net.Sockets;

var retryPolicy = Policy
    .Handle<HttpRequestException>()
    .Or<SocketException>()
    .WaitAndRetryAsync(
        retryCount: 5,
        sleepDurationProvider: attempt => TimeSpan.FromSeconds(Math.Pow(2, attempt)),
        onRetry: (exception, timeSpan, context) =>
        {
            Console.WriteLine($"Request failed. Retrying in {timeSpan.TotalSeconds}s...");
        }
    );

await retryPolicy.ExecuteAsync(async () => 
{
    await transport.SendPostRequestAsync(request, cancellationToken);
});

Dependency Injection Setup

Dependency injection is a core architectural pattern in modern .NET applications. Instead of instantiating the MCP transport manually, register it as a scoped service within the IServiceCollection. This pattern allows your controllers or background workers to inject the connected client directly.

builder.Services.AddHttpClient<FastIoMcpTransport>(client => 
{
    client.BaseAddress = new Uri("https://mcp.fast.io/mcp/tools");
});

Security and Authentication Never hardcode

Fastio API keys in your C# source code. In a .NET environment, use the IConfiguration framework and Secret Manager during development, transitioning to Azure Key Vault or AWS Secrets Manager in production.

The barrier to entry for building these integrations is low. Monthly plans can start with a 14-day Business Trial with a credit card, which ends early if the trial credits run out; annual plans have no trial. See the pricing page for current plan details. After the trial, Starter costs $9.99 per month and includes 3 seats, 250 GB of storage, and 100,000 credits per month. For the full authentication and endpoint reference that applies regardless of client language, see Fastio's MCP server integration guide for developers.