C#: ASP.NET Core and the generic host

​

Requirements

• ModelContextProtocol 1.0.0 or later, on the 1.x or 2.x line. HTTP servers also use ModelContextProtocol.AspNetCore.
• .NET 8 or later. The package also targets .NET Standard 2.0, for stdio servers on .NET Framework 4.7.2 or later.

dotnet add package AgentCat

​

Add WithAgentCat() to the server builder

builder.Services.AddMcpServer()
    .WithHttpTransport(o => o.Stateless = true)
    .WithTools<MyTools>()
    .WithAgentCat("proj_YOUR_PROJECT_ID", options =>
    {
        options.EnableAgentTracking = true;
    });

• Anywhere in the chain. AgentCat installs after every Configure step of the server options, so it sees the tools and handlers that WithTools, WithCallToolHandler and the other builder methods add, before or after it.
• The project ID. null, or no argument, reads it from the AGENTCAT_PROJECT_ID environment variable. An empty string, or no project ID at all, tracks the server but sends no events to AgentCat: your exporters still get them.
• Options. The second argument sets the properties of an AgentCatOptions object (see Options). AgentCat calls it once, when the first server options are built, and reads the options then: later changes have no effect.
• It never throws, except ArgumentNullException for a null builder. When AgentCat cannot track the server, the server runs untracked.
• Once per server. A second WithAgentCat() call on the same server installs nothing, and the first call’s project ID and options stay. Only its ApiBaseUrl applies, because all servers of a process share one event queue.
• IAgentCat. WithAgentCat() also registers IAgentCat as a singleton, unless your app registered one already (see IAgentCat and custom events).

​

Stateless HTTP

using System.ComponentModel;
using ModelContextProtocol.Server;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMcpServer()
    .WithHttpTransport(o => o.Stateless = true)
    .WithTools<MyTools>()
    .WithAgentCat("proj_YOUR_PROJECT_ID");

var app = builder.Build();
app.MapMcp();
app.Run();

[McpServerToolType]
public class MyTools
{
    [McpServerTool, Description("Echoes the message back.")]
    public static string Echo(string message) => $"Echo: {message}";
}

• A new server for every request. In stateless mode the MCP SDK builds new server options and a new server for every POST. AgentCat installs on each of them, and they all share one tracker per WithAgentCat() call, so what AgentCat learns from a tools/list serves the tools/call of a later request.
• A fresh process. When a tools/call reaches a process that has not listed its tools yet, for example a new instance behind a load balancer, AgentCat lists the tools itself (your list handler, then ToolCollection), with a 5-second limit, to learn which parameters it added.
• Sessions. AgentCat adds a session_id parameter to each tool: the agent sends start on its first call, gets a ses_ ID in the result, and sends that ID on its later calls. See Stateless Servers.
• The default transport. On ModelContextProtocol 2.x, WithHttpTransport() without options is already stateless. On 1.x it is stateful.

​

Stateful HTTP

builder.Services.AddMcpServer()
    .WithHttpTransport(o => o.Stateless = false)
    .WithTools<MyTools>()
    .WithAgentCat("proj_YOUR_PROJECT_ID");

​

stdio on the generic host

using System.ComponentModel;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using ModelContextProtocol.Server;

var builder = Host.CreateApplicationBuilder(args);

// stdout carries the MCP messages: write the console logs to stderr
builder.Logging.AddConsole(o => o.LogToStandardErrorThreshold = LogLevel.Trace);

builder.Services.AddMcpServer()
    .WithStdioServerTransport()
    .WithTools<MyTools>()
    .WithAgentCat("proj_YOUR_PROJECT_ID");

await builder.Build().RunAsync();

[McpServerToolType]
public class MyTools
{
    [McpServerTool, Description("Echoes the message back.")]
    public static string Echo(string message) => $"Echo: {message}";
}

​

Request headers and URL

• Every header, as received. AgentCat filters no header: authorization and cookie go out too, and so does x-forwarded-for, like any other header. AgentCat records no IP address of its own. Header names are lower-case, and a header sent several times has one value, joined with , (; for cookie).
• The URL keeps its query string, which can carry an API key or other credentials.
• How AgentCat reads the request. WithAgentCat() registers ASP.NET Core’s HttpContextAccessor when your app has none. AgentCatSdk.Track() registers nothing, so it reads the request only when your app calls AddHttpContextAccessor().
• Legacy SSE. On the legacy SSE transport, the request is the session’s GET /sse, not the POST that carried the call, so the headers and the URL belong to the session.
• No request. On stdio servers, on .NET Framework, with PerSessionExecutionContext = true, and for a tool call whose client opts in to MCP 2.x tasks, AgentCat has no request to read. The event then has no requestInfo, and call.Headers is empty.

using System.Text.Json.Nodes;
using AgentCat;

builder.Services.AddMcpServer()
    .WithHttpTransport(o => o.Stateless = true)
    .WithTools<MyTools>()
    .WithAgentCat("proj_YOUR_PROJECT_ID", options =>
    {
        options.RedactEvent = (e, _) =>
        {
            if (e.Parameters is JsonObject p && p["extra"] is JsonObject x && x["requestInfo"] is JsonObject info)
            {
                if (info["headers"] is JsonObject headers)
                {
                    headers.Remove("authorization");
                    headers.Remove("cookie");
                }

                if (info["url"] is JsonValue url && url.TryGetValue(out string? text) && text.IndexOf('?') is var query and >= 0)
                {
                    info["url"] = text.Substring(0, query);
                }
            }

            return new ValueTask<AgentCatEvent?>(e);
        };
    });

​

IAgentCat and custom events

​

Custom events from a tool

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

[McpServerToolType]
public class BillingTools(IAgentCat agentCat)
{
    [McpServerTool, Description("Upgrades the subscription.")]
    public async Task<string> Upgrade(McpServer server, string plan)
    {
        // ... upgrade the subscription

        await agentCat.PublishCustomEventAsync(server, "proj_YOUR_PROJECT_ID", new CustomEventData
        {
            ResourceName = "subscription_upgraded",
            Parameters = new JsonObject { ["plan"] = plan },
        });

        return $"Upgraded to {plan}";
    }
}

• The server. In stateless HTTP, the McpServer is a new object for every request. AgentCat finds the tracked server through its options, so any of them works.
• The project ID must not be empty, but the event goes to the project that the server was tracked with.
• The session. An event without a SessionId in its CustomEventData has no session. The tool cannot read AgentCat’s session_id: AgentCat removes it from the arguments before your tool runs.
• The task completes when AgentCat has queued the event, not when it has sent it. It faults with an ArgumentException for an empty project ID or a server that AgentCat does not track, unless AgentCat was off when a server was set up in this process: it then logs a warning instead. Other failures never reach your code.

​

Shutdown

• Allow 6 seconds. AgentCat ignores the shutdown token of the host, so a stop can take up to 6 seconds longer than HostOptions.ShutdownTimeout. Set the grace period of your container above that.
• Microsoft.Extensions.Hosting 8 or later runs the flush after the host stops. Older hosts and the legacy WebHost rely on the process-exit handler.
• A service provider without a host runs no flush. If you build and dispose a service provider yourself, call FlushAsync or ShutdownAsync before you dispose it.
• DisableShutdownHandlers = true on the first install of the process turns off the process-exit handler. The flush after the host stops stays on.

​

Options