DEV Community: Rahmat Afridi

Expose Your Existing ASP.NET Core APIs to AI Agents with a Secure MCP Server

Rahmat Afridi — Mon, 19 Oct 2026 08:50:28 +0000

Most .NET teams already have solid ASP.NET Core APIs that power their business logic, databases, and workflows. The new challenge is letting AI agents call those same capabilities without giving them unrestricted access or forcing a full rewrite. The Model Context Protocol (MCP) solves this by providing a standard way for agents to discover and invoke tools. With the official ModelContextProtocol C# SDK, you can host an MCP server directly in ASP.NET Core, wrap your existing services as tools, and control exactly what agents can see and do.

This article shows a practical pattern: take a typical order-management API, expose a small set of read-only tools over MCP, lock it down with authentication and authorization, and verify the surface with an MCP client. The approach works for any existing service layer you already trust.

Why a Separate MCP Surface Beats Auto-Exposing Every Endpoint

Agents are not ordinary API clients. They decide which tools to call based on descriptions and schemas, then chain those calls. Exposing every controller action as a tool quickly produces a noisy, dangerous surface. A better design is a thin MCP server that sits beside your application (or inside the same host) and offers only the operations that are safe and useful for agents.

Start with read-only lookups that answer familiar questions: “What is the status of order 12345?” or “List open orders for customer C-789.” Write clear, specific descriptions so the model chooses the right tool. Later you can add carefully guarded write tools that require explicit human approval or elevated roles. The official SDK (ModelContextProtocol.AspNetCore 2.2.0 at the time of writing) makes this straightforward with attribute-based tools and first-class ASP.NET Core integration.

Setting Up the MCP Server

Create or open an ASP.NET Core web project and add the package:

dotnet add package ModelContextProtocol.AspNetCore --version 2.2.0

In Program.cs register the server. The SDK’s HTTP transport is stateless by default in v2, which is ideal for load-balanced deployments:

using ModelContextProtocol.Server;

var builder = WebApplication.CreateBuilder(args);

// Your existing services
builder.Services.AddScoped<IOrderService, OrderService>();

builder.Services.AddMcpServer()
    .WithHttpTransport()
    .AddAuthorizationFilters()
    .WithToolsFromAssembly();

var app = builder.Build();

app.MapMcp("/mcp");

app.Run();

WithToolsFromAssembly discovers every class marked [McpServerToolType] and every method marked [McpServerTool]. You can also register individual types with .WithTools<OrderTools>() if you prefer explicit control.

Wrapping Existing Services as Tools

Keep business logic in the services you already have. The tool methods simply call them and return results the agent can use. Inject the service (or any other DI-registered dependency) directly:

using Microsoft.AspNetCore.Authorization;
using ModelContextProtocol.Server;
using System.ComponentModel;
using System.Security.Claims;

[McpServerToolType]
public class OrderTools
{
    private readonly IOrderService _orders;

    public OrderTools(IOrderService orders) => _orders = orders;

    [McpServerTool, Description(
        "Gets the current status and key details of a single order by its ID. " +
        "Use this when the user asks about a specific order number.")]
    public async Task<string> GetOrderStatus(
        [Description("The unique order identifier")] string orderId)
    {
        var order = await _orders.GetByIdAsync(orderId);
        if (order is null)
            return $"Order {orderId} was not found.";

        return $"Order {order.Id}: Status={order.Status}, Total={order.Total:C}, Customer={order.CustomerId}";
    }

    [McpServerTool, Description(
        "Lists open orders for a given customer. Returns at most 20 recent open orders.")]
    public async Task<string> ListOpenOrders(
        [Description("The customer identifier")] string customerId)
    {
        var orders = await _orders.GetOpenOrdersAsync(customerId, limit: 20);
        if (orders.Count == 0)
            return $"No open orders found for customer {customerId}.";

        return string.Join("\n", orders.Select(o =>
            $"{o.Id}: {o.Status} - {o.Total:C}"));
    }
}

The [Description] attributes become the tool descriptions the agent sees. Write them the way you would write a good API comment—clear purpose, expected inputs, and any limits. The SDK generates the JSON schema from the method signature automatically.

Adding Authentication and Authorization

Treat the MCP endpoint as a protected API. Configure JWT bearer authentication the same way you already do for your other APIs, then require authorization on the MCP mapping:

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.AspNetCore.Authorization;

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = builder.Configuration["Auth:Authority"];
        options.Audience = builder.Configuration["Auth:Audience"];
        options.TokenValidationParameters.ValidateIssuer = true;
        options.TokenValidationParameters.ValidateAudience = true;
    });

builder.Services.AddAuthorization();

// ... AddMcpServer as before ...

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.MapMcp("/mcp").RequireAuthorization();

For finer control, apply [Authorize] attributes to individual tools. Because we called AddAuthorizationFilters(), the SDK honors them: unauthorized tools disappear from tools/list results, and direct calls return a forbidden error.

[McpServerTool, Description("Cancels an order. Admin role required.")]
[Authorize(Roles = "Admin")]
public async Task<string> CancelOrder(
    ClaimsPrincipal user,
    [Description("The order to cancel")] string orderId,
    [Description("Reason for cancellation")] string reason)
{
    // Audit who called it
    var caller = user.Identity?.Name ?? "unknown";
    await _orders.CancelAsync(orderId, reason, caller);
    return $"Order {orderId} cancelled by {caller}.";
}

The SDK injects ClaimsPrincipal automatically when the parameter is present; it never appears in the tool schema the agent sees. This gives you both declarative role checks and the ability to log or further filter inside the method.

You can also set a policy on the endpoint itself:

app.MapMcp("/mcp").RequireAuthorization("McpToolsPolicy");

where the policy requires an authenticated user plus a specific scope claim:

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("McpToolsPolicy", policy => policy
        .RequireAuthenticatedUser()
        .RequireClaim("scope", "mcp.tools"));
});

Limiting What Agents Can Call

Several complementary techniques keep the surface small:

Only mark the methods you want with [McpServerTool]. Everything else stays private to your normal API.
Prefer read-only tools first. Write operations should carry [Authorize] and, for high-risk actions, an extra confirmation step or human-in-the-loop flow.
Use precise descriptions and parameter constraints so the model is less likely to invent calls.
Consider separate MCP endpoints or tool groups for different agent roles if your organization needs stronger isolation.
Log every tool invocation (the SDK’s request filters or ordinary ASP.NET Core logging make this easy) so you can audit what agents actually did.

Because the MCP server calls your existing service layer, all of the validation, business rules, and database constraints you already trust remain in force.

Testing with an MCP Client

You can verify the server without an LLM by using the SDK’s client. In a separate console project (or a test):

using ModelContextProtocol.Client;
using ModelContextProtocol.Protocol;

var transport = new HttpClientTransport(new HttpClientTransportOptions
{
    Endpoint = new Uri("http://localhost:5000/mcp")
    // Add authentication headers here if required
});

await using var client = await McpClient.CreateAsync(transport);

var tools = await client.ListToolsAsync();
foreach (var tool in tools)
{
    Console.WriteLine($"{tool.Name}: {tool.Description}");
}

var result = await client.CallToolAsync(
    "GetOrderStatus",
    new Dictionary<string, object?> { ["orderId"] = "ORD-1001" });

var text = result.Content.OfType<TextContentBlock>().FirstOrDefault()?.Text;
Console.WriteLine(text);

If you configured authentication, supply a valid bearer token on the HttpClient used by the transport. The tools returned by ListToolsAsync are AIFunction instances, so you can pass them to an IChatClient (Microsoft.Extensions.AI) through ChatOptions.Tools and let an agent invoke them automatically.

Production Notes

Keep the MCP server stateless unless you specifically need server-to-client notifications.
Place it behind the same reverse proxy, rate limits, and WAF you use for the rest of your APIs.
Start with an internal-only deployment so you can observe real agent behavior before opening it more widely.
Monitor tool call volume and latency; agents can be chatty.
Version your tool contracts carefully—agents cache schemas and descriptions.

The combination of a thin, explicitly curated tool surface, ordinary ASP.NET Core authentication, and per-tool authorization gives you a controlled way to let AI agents work with systems you already run. You do not need to rebuild your APIs; you only need to decide which capabilities are safe to describe and expose.

About the author

Rahmat Afridi is an AI Integration Developer & Senior .NET Developer based in Islamabad, Pakistan, with experience since 2016 building practical systems in C#, ASP.NET Core, Azure, and modern AI integration patterns.

https://rahmatafridi.com

https://github.com/rahmatafridi

Human-in-the-Loop AI Drafts in ASP.NET Core: Approval Queues, Audit Trails, and Safe Sending

Rahmat Afridi — Tue, 06 Oct 2026 16:18:38 +0000

When I add AI to an existing support, ERP, or CRM application, my first release boundary is simple: the model drafts; an authorized person decides what leaves the system. That keeps a model mistake from immediately becoming an external action.

That is the starting point in SupportAgent.NET, the ASP.NET Core and React support copilot I am building (source on GitHub). The assistant prepares replies for human review. Here is how I would build the approval, audit, and delivery workflow around that boundary.

An Approve button is not enough. Approval must cover a specific revision, recipient, and set of attachments, and remain valid when a background worker eventually sends them.

1. Model the lifecycle explicitly

The main path is Generated â†’ In Review â†’ Edited â†’ Approved â†’ Sent. Editing is optional: an unchanged draft can move from In Review to Approved. Rejection branches from In Review or Edited; Sent is not a precursor to Rejected.

Generated  -> In Review
In Review  -> Edited | Approved | Rejected
Edited     -> Approved | Rejected
Approved   -> Sent

Generated means a candidate exists. In Review means a reviewer has opened it. Edited means a new immutable revision exists, still awaiting approval.

I freeze approved content. A changed body, subject, recipient, or attachment requires a new review. Regeneration creates a new draft with its own provenance, rather than overwriting approved evidence.

Only server-side workflow methods can transition states. The model receives neither an approval tool nor a sending tool. A prompt saying "never send" is not the enforcement mechanism.

2. Store revisions and decisions separately

These examples use .NET 8/9-compatible C# and SQL Server. I keep workflow state and generation provenance on Draft:

using System.ComponentModel.DataAnnotations;
using Microsoft.EntityFrameworkCore;

public enum DraftStatus
{
    Generated, InReview, Edited, Approved, Sent, Rejected
}

public sealed class Draft
{
    public Guid Id { get; set; }
    public Guid TenantId { get; set; }
    public int TicketId { get; set; }
    public DraftStatus Status { get; set; }
    public int CurrentRevision { get; set; }
    public required string PromptVersion { get; set; }
    public required string ModelName { get; set; }
    public required string SourceIdsJson { get; set; }
    public required string ToolCallsJson { get; set; }
    [Timestamp] public byte[] RowVersion { get; set; } = [];
}

On SQL Server, [Timestamp] maps this property to a database-generated concurrency token, not a date.

public sealed class DraftRevision
{
    public Guid Id { get; set; }
    public Guid TenantId { get; set; }
    public Guid DraftId { get; set; }
    public int Number { get; set; }
    public required string Text { get; set; }
    public required string EnvelopeJson { get; set; }
    public required string ActorId { get; set; }
    public DateTimeOffset AtUtc { get; set; }
}

public sealed class ApprovalDecision
{
    public Guid Id { get; set; }
    public Guid TenantId { get; set; }
    public Guid DraftId { get; set; }
    public int Revision { get; set; }
    public bool Approved { get; set; }
    public required string ActorId { get; set; }
    public string? Reason { get; set; }
    public DateTimeOffset AtUtc { get; set; }
}

EnvelopeJson captures the reviewed recipient, subject, and immutable attachment references. Revisions are append-only through application services; public setters do not enforce immutability.

I configure tenant-consistent foreign keys and unique revision numbers per draft. Each edit also increments the parent's revision, updating its row version. Decision and outbox uniqueness prevent duplicate approval or delivery intents for that revision.

Source IDs include document versions. Tool evidence contains validated arguments, minimal results, timestamps, and correlation IDs, stored in protected storage rather than ordinary logs.

The JSON properties are logical fields, not encryption. I encrypt sensitive payloads or replace them with protected object references. I also retain the exact prompt template and evidence versions: a source ID that later points to changed content cannot reconstruct the original decision.

3. Generate and expose workflow operations

For the final drafting call, authorized retrieval and read-only tools have already gathered evidence. IChatClient supplies the provider abstraction; the server, not generated text, chooses the persisted state.

using Microsoft.Extensions.AI;

public static async Task<ChatResponse> GenerateAsync(
    IChatClient client, string prompt, string evidence,
    CancellationToken ct)
{
    var response = await client.GetResponseAsync(
        [new(ChatRole.System, prompt), new(ChatRole.User, evidence)],
        new ChatOptions { Tools = [], ToolMode = ChatToolMode.None }, ct);

    if (response.FinishReason != ChatFinishReason.Stop ||
        string.IsNullOrWhiteSpace(response.Text))
        throw new InvalidOperationException("No complete draft returned.");

    return response;
}

This client has no sending capability. I persist the response text as revision one, capture the returned model ID alongside configured model information, and create the draft as Generated. This checks completion, not correctness; provider refusals need separate handling before persistence.

Generation happens outside a database transaction; saving the draft and evidence happens together.

With Identity already configured, I register policies and routes:

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("Drafts.Edit", p => p.RequireAuthenticatedUser()
        .RequireRole("SupportAgent", "Admin"));
    options.AddPolicy("Drafts.Approve", p => p.RequireAuthenticatedUser()
        .RequireRole("SupportAgent", "Admin")
        .RequireClaim("permission", "drafts.approve"));
});
var app = builder.Build();

var drafts = app.MapGroup("/drafts").RequireAuthorization("Drafts.Edit");
drafts.MapGet("/", DraftEndpoints.List);
drafts.MapPost("/generate", DraftEndpoints.Generate);
drafts.MapPost("/{id:guid}/review", DraftEndpoints.StartReview);
drafts.MapPut("/{id:guid}", DraftEndpoints.Edit);
drafts.MapPost("/{id:guid}/approve", DraftEndpoints.Approve)
    .RequireAuthorization("Drafts.Approve");
drafts.MapPost("/{id:guid}/reject", DraftEndpoints.Reject)
    .RequireAuthorization("Drafts.Approve");

DraftEndpoints delegates to scoped application services. Named policies enforce role and permission requirements; services additionally authorize the ticket, customer, and tenant. Identity never comes from request DTOs.

For cookie-authenticated mutations, I explicitly validate antiforgery tokens; route authorization alone is not CSRF protection.

The queue is a tenant-filtered, paginated query over reviewable states. Its detail view returns the exact revision and row version displayed to the reviewer.

I use request DTOs rather than binding EF entities. Edit accepts content and concurrency fields; approve accepts only concurrency fields; reject adds a reason. None accepts a tenant, approver identity, timestamp, or target status. I never interpret approval-like language inside a draft as an application command.

Prevent stale approvals

An approval request carries that revision number and row version, not replacement text. After resource authorization and loading the tenant-scoped revision, the service performs:

if (draft.CurrentRevision != request.Revision ||
    draft.Status is not (DraftStatus.InReview or DraftStatus.Edited))
    return Results.Conflict("Refresh the draft before approving.");

db.Entry(draft).Property(x => x.RowVersion).OriginalValue =
    request.RowVersion;
var decision = new ApprovalDecision
{
    Id = Guid.NewGuid(), TenantId = tenantId, DraftId = draft.Id,
    Revision = draft.CurrentRevision, Approved = true,
    ActorId = userId, AtUtc = DateTimeOffset.UtcNow
};
draft.Status = DraftStatus.Approved;
db.ApprovalDecisions.Add(decision);
db.Outbox.Add(CreateOutbox(draft, revision, decision));
try
{
    await db.SaveChangesAsync(ct);
    return Results.Accepted();
}
catch (DbUpdateConcurrencyException)
{
    return Results.Conflict("Another agent changed this draft.");
}

This fragment assumes validated request fields and server-resolved identities. CreateOutbox copies the approved delivery payload and decision reference; it does not send.

One SaveChangesAsync call commits the draft, decision, and outbox together. A concurrent edit or approval makes the stale update fail. Return HTTP 409 and refresh; never automatically approve the newer revision. Handle known unique-key collisions as conflicts too.

I apply equivalent concurrency checks to review, edit, and reject operations. The UI labels the button "Approve and queue for sending", making the external effect explicit.

4. Keep an audit trail without creating a data leak

I record the actor, server timestamp, transition, revision, decision reason, and correlation ID. Immutable revisions support both incremental diffs and the original-AI-versus-final-text comparison.

The reviewer sees sources, tool failures, recipient details, and financial values beside the draft. A stored difference alone does not show whether an edit corrected a factual error.

For ERP and CRM replies, I highlight changed amounts and account references. Totals still come from business services, not the model or an edit-distance score. The reviewer must be able to inspect evidence without searching a separate logging system.

Sensitive text belongs in encrypted, access-controlled evidence storage. Operational logs contain identifiers, timings, and outcome codes, not prompts, customer details, access tokens, or secrets. OWASP's logging guidance explicitly distinguishes useful audit events from sensitive data that should be excluded or protected.

I also avoid production Trace logging on LoggingChatClient, which can include message contents and options.

I restrict audit writes and reads separately and define retention and deletion for revisions, evidence snapshots, exports, and backups. Keeping everything forever is not an audit strategy.

5. Send through a transactional outbox

A transactional outbox separates durable approval from unreliable network delivery. The worker sends only an immutable payload attached to a valid Approved draft and matching decision.

I store a stable idempotency key per tenant, draft, and revision, plus attempt count, next-attempt time, lease ownership, and provider receipt. Multiple workers claim entries atomically with expiring leases, not a read-then-update race.

Before dispatch, the worker verifies approval, recipient association, evidence freshness, and cancellation status. Cancelling pending delivery must compete atomically with claiming it. After dispatch begins, cancellation is not a promise of recall.

If relevant account data changed after approval, I pause delivery for renewed review. The worker never silently regenerates a reply. A server-side kill switch stops new dispatches while receipt processing and reconciliation continue.

The worker resolves a fresh service scope and tenant-specific database context per operation. A BackgroundService registered through AddHostedService is a singleton; it must not hold a request-scoped DbContext (Microsoft documents the scoped-service pattern for this).

After provider acceptance, it records the receipt, completes the outbox entry, and marks Sent in one local transaction. Here, Sent means provider-accepted, not confirmed delivery; bounces and delivery events are separate.

Retries are not exactly-once delivery

A worker can crash after provider acceptance but before recording success. Retrying must reuse the same key and identical payload. Provider-side deduplication, such as Resend's idempotency keys, is necessary for that ambiguous window; its retention period (24 hours for Resend) limits safe retries.

Without that guarantee, an outbox cannot promise duplicate-free external sending. Uncertain outcomes go to reconciliation rather than blind retries. Transient failures get bounded backoff; permanent failures go to operator review without generating a new key.

Delivery failure belongs to outbox status, not rejection of the approved text.

6. Measure review effort and correctness separately

I would track normalized edit distance between the generated revision and the actual sent text: character-level Levenshtein distance divided by the longer text length, with two empty strings defined as zero. Keep normalization consistent across evaluations.

A small distance is not proof of quality: changing one amount can correct a serious error. I pair it with factual-correction labels and rejection reasons such as unsupported claim, wrong account, missing evidence, or inappropriate tone.

For approval rate, I use approved drafts divided by approved plus rejected drafts in a defined cohort. Pending drafts remain separate, as do subsequent delivery failures.

I compare these outcomes by prompt version, model, and retrieval configuration. High acceptance alone might indicate superficial review. I review samples before changing prompts, and treat tenant-scoped feedback as protected data rather than automatically turning it into training material.

7. Mistakes I avoid

Auto-send "just for simple cases." I do not let model confidence bypass the approval workflow.
Keeping text without provenance. A polished reply is not explainable without the prompt version, source versions, and tool evidence that produced it.
Exposing a send tool to the LLM. Sending credentials and execution belong to the delivery worker, not the model's tool registry.

I also test approval-versus-edit races, cross-tenant access, duplicate worker claims, and crashes immediately after provider acceptance. Those tests exercise the boundary that matters: an unapproved or superseded message must never become a customer communication.

Conclusion

When I am adding AI to existing ASP.NET Core apps, my default is not merely "put a human somewhere in the loop." It is a versioned draft, an authorized decision, an immutable delivery payload, and a recoverable sending workflow.

That lets an existing ASP.NET Core application benefit from AI drafting without handing the model authority over customer communication.

Rahmat Afridi is a Senior .NET Developer and AI Integration Specialist who adds AI to existing ASP.NET Core applications. More at rahmatafridi.com.

Adding RAG to an Existing ASP.NET Core App: SQL Server Chunks, Embeddings and Hybrid Ranking

Rahmat Afridi — Thu, 01 Oct 2026 15:46:26 +0000

When I add AI to an existing business application, my first concern is not the chat interface. It is whether the assistant can access something the current user cannot.

That is the starting point for my RAG ASP.NET Core implementation in SupportAgent.NET, an ASP.NET Core and React customer-support copilot.

The internal assistant uses native tool calling to look up permitted customer and order records through normal .NET services. It also retrieves company documents and drafts replies, which a human agent reviews before sending. Identity roles and tenant filters remain application rules, not instructions I expect the model to obey.

Here, I focus on the document-retrieval path: SQL Server chunks and embeddings, hybrid ranking, and the checks that must happen before context reaches the model.

Why I use RAG instead of fine-tuning for business documents

RAG supplies retrieved information at request time. Fine-tuning changes model weights. For changing policies and procedures, I want to update searchable documents without retraining the answering model. Fine-tuning can help with specialized behavior, but it is not my document-refresh mechanism.

I also keep transactional data separate. An order's current status belongs behind GetOrderStatus, not in an embedding generated from yesterday's database export. Documents provide policy context; application services provide current facts.

Neither approach replaces authorization. A model knowing a fact does not establish that the current user may read it.

Chunking documents and storing them in SQL Server

SupportAgent.NET stores chunk embeddings as JSON in SQL Server. That keeps the initial retrieval path within the existing data layer, without requiring a separate vector store.

These are reduced .NET 8 examples, not verbatim repository files. The methods belong in the existing services, and they rely on these namespaces:

using System.Net.Http.Json;
using System.Security.Claims;
using System.Text.Json;
using System.Text.RegularExpressions;
using Microsoft.AspNetCore.Authorization;
using Microsoft.EntityFrameworkCore;

public sealed class KnowledgeChunk
{
    public long Id { get; set; }
    public Guid OrganizationId { get; set; }
    public Guid DocumentId { get; set; }
    public int Ordinal { get; set; }
    public required string Content { get; set; }
    public required string Source { get; set; }
    public string? EmbeddingJson { get; set; }
    public string? EmbeddingSpace { get; set; }
}

I merge this mapping into the existing context, preserving its Identity configuration and other mappings:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    base.OnModelCreating(modelBuilder); // Preserve Identity mappings.

    var chunks = modelBuilder.Entity<KnowledgeChunk>();
    chunks.Property(c => c.EmbeddingJson).HasColumnType("nvarchar(max)");
    chunks.HasIndex(c => new
        { c.OrganizationId, c.DocumentId, c.Ordinal }).IsUnique();
}

You'll need a migration for this. EmbeddingSpace is a schema-hardening suggestion in this example rather than a description of the repository's current metadata.

The following method belongs inside the authorized ingestion service. trustedOrganizationId comes from server-side identity, never an upload field.

public static async Task StoreAsync(
    DbContext db, IEmbeddingProvider embeddings,
    Guid trustedOrganizationId, Guid documentId,
    string source, string text, int size, int overlap,
    CancellationToken ct)
{
    ArgumentException.ThrowIfNullOrWhiteSpace(text);
    ArgumentException.ThrowIfNullOrWhiteSpace(source);

    if (trustedOrganizationId == Guid.Empty || documentId == Guid.Empty)
        throw new ArgumentException("Missing document scope.");

    if (size <= 0 || overlap < 0 || overlap >= size)
        throw new ArgumentOutOfRangeException(nameof(overlap));

    int ordinal = 0;
    for (int start = 0; start < text.Length; start += size - overlap)
    {
        int length = Math.Min(size, text.Length - start);
        string content = text.Substring(start, length);
        if (string.IsNullOrWhiteSpace(content)) continue;

        var vector = await embeddings.EmbedAsync(
            content, EmbeddingPurpose.Document, ct);

        db.Set<KnowledgeChunk>().Add(new KnowledgeChunk
        {
            OrganizationId = trustedOrganizationId,
            DocumentId = documentId,
            Ordinal = ordinal++,
            Source = source,
            Content = content,
            EmbeddingJson = JsonSerializer.Serialize(vector),
            EmbeddingSpace = embeddings.SpaceKey
        });

        if (start + length == text.Length) break;
    }

    await db.SaveChangesAsync(ct);
}

This intentionally simple character-window splitter makes overlap visible. It can cut sentences, and a character count is not a token budget. For varied documents, I would adapt splitting to headings, paragraphs, tables, and the embedding model's tokenizer.

This method inserts a new document's chunks. In production, I handle replacements transactionally so obsolete chunks are removed, authorize the parent document before writing, and generate replacement vectors before opening the database transaction so it is never held across network requests.

Generating embeddings behind an interface

The answering model and embedding model are separate choices. Switching the chat provider does not inherently require rebuilding document vectors; switching embedding spaces does.

public enum EmbeddingPurpose { Document, Query }

public interface IEmbeddingProvider
{
    string SpaceKey { get; }

    Task<float[]> EmbedAsync(string text,
        EmbeddingPurpose purpose, CancellationToken ct);
}

public sealed class HttpEmbeddingProvider(
    HttpClient http, string model, string spaceKey,
    bool ollama, string documentPrefix, string queryPrefix)
    : IEmbeddingProvider
{
    public string SpaceKey => spaceKey;

    public async Task<float[]> EmbedAsync(string text,
        EmbeddingPurpose purpose, CancellationToken ct)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(text);

        string input = (purpose == EmbeddingPurpose.Query
            ? queryPrefix : documentPrefix) + text;

        object body = ollama
            ? new { model, input, truncate = false }
            : new { model, input, encoding_format = "float" };

        using var response = await http.PostAsJsonAsync(
            ollama ? "api/embed" : "v1/embeddings", body, ct);
        response.EnsureSuccessStatusCode();

        using var json = JsonDocument.Parse(
            await response.Content.ReadAsStringAsync(ct));

        var values = ollama
            ? json.RootElement.GetProperty("embeddings")[0]
            : json.RootElement.GetProperty("data")[0]
                .GetProperty("embedding");

        var vector = values.EnumerateArray()
            .Select(x => x.GetSingle()).ToArray();

        if (vector.Length == 0 || vector.All(x => x == 0) ||
            vector.Any(x => !float.IsFinite(x)))
            throw new InvalidOperationException("Invalid embedding.");

        return vector;
    }
}

The adapter handles OpenAI's /v1/embeddings and Ollama's /api/embed response shapes. Ollama's truncate = false makes oversized input fail instead of silently discarding text.

Register a configured HttpClient with the provider's origin as its base address, a timeout, and server-side authentication where required. Supply the model and prefixes through configuration, and use empty prefixes when the selected model does not require them. Nomic's nomic-embed-text-v1.5, for example, distinguishes search_document: from search_query:.

SpaceKey should identify the pinned model/version, dimensions, and preprocessing. Matching array lengths alone does not make vectors compatible. On an embedding-model change, re-embed the corpus; do not compare old and new spaces.

Hybrid ranking in a RAG ASP.NET Core application

I want semantic matches without losing literal terms such as product names or error codes. This example combines cosine similarity with distinct query-token coverage. It is deliberately not BM25 or SQL Server full-text search.

public static class HybridRank
{
    public static HashSet<string> Tokens(string text) =>
        Regex.Matches(text.ToLowerInvariant(), @"[\p{L}\p{N}]+")
            .Select(m => m.Value).ToHashSet();

    public static double Score(KnowledgeChunk chunk,
        HashSet<string> terms, float[] queryVector, string spaceKey)
    {
        var words = Tokens(chunk.Content);
        double lexical = terms.Count == 0 ? 0
            : terms.Count(words.Contains) / (double)terms.Count;

        var vector = chunk.EmbeddingSpace == spaceKey &&
                     chunk.EmbeddingJson is not null
            ? JsonSerializer.Deserialize<float[]>(chunk.EmbeddingJson)
            : null;

        // Missing or incompatible vectors use lexical matching.
        if (vector is null) return lexical;

        double semantic = Math.Max(0, Cosine(queryVector, vector));
        return 0.75 * semantic + 0.25 * lexical;
    }

    private static double Cosine(float[] a, float[] b)
    {
        if (a.Length == 0 || a.Length != b.Length)
            throw new InvalidOperationException("Embedding mismatch.");

        double dot = 0, aa = 0, bb = 0;
        for (int i = 0; i < a.Length; i++)
        {
            dot += (double)a[i] * b[i];
            aa += (double)a[i] * a[i];
            bb += (double)b[i] * b[i];
        }

        return aa == 0 || bb == 0 ? 0
            : Math.Clamp(dot / Math.Sqrt(aa * bb), -1, 1);
    }
}

Cosine measures vector alignment. I clamp negative similarity to zero and combine it with lexical coverage, which already lies between zero and one. The weights mirror the project's configurable semantic/lexical starting point, not a measured optimum, so thresholds and weights need evaluation against representative questions, including questions that should return nothing.

For a larger keyword-search workload, SQL Server's FREETEXTTABLE or CONTAINSTABLE can supply ranked candidates after a full-text index is configured. Their ranks are not directly interchangeable with cosine scores, so I would normalize deliberately or combine rank positions instead.

Enforcing tenant and role permissions before retrieval

I authorize the operation first, then constrain the database query, then rank the permitted chunks. Filtering after retrieval risks exposing text through prompts, logs, or intermediate results.

In Program.cs, with Identity already configured:

builder.Services.AddAuthorization(options =>
    options.AddPolicy("Knowledge.Read", policy => policy
        .RequireAuthenticatedUser()
        .RequireRole("Admin", "SupportAgent")));

This policy allows either named role. It does not make an administrator a cross-tenant administrator.

Inside the scoped retrieval service:

public sealed record RankedChunk(KnowledgeChunk Chunk, double Score);

public static async Task<RankedChunk[]> SearchAsync(
    DbContext db, IAuthorizationService authorization,
    ClaimsPrincipal user, Guid trustedOrganizationId,
    IEmbeddingProvider embeddings, string query,
    int limit, double minimumScore, CancellationToken ct)
{
    ArgumentException.ThrowIfNullOrWhiteSpace(query);

    if (trustedOrganizationId == Guid.Empty || limit <= 0 ||
        !double.IsFinite(minimumScore) ||
        minimumScore < 0 || minimumScore > 1)
        throw new ArgumentException("Invalid retrieval settings.");

    var allowed = await authorization.AuthorizeAsync(
        user, null, "Knowledge.Read");
    if (!allowed.Succeeded) throw new UnauthorizedAccessException();

    // Scope in SQL before loading any chunk text.
    var chunks = await db.Set<KnowledgeChunk>().AsNoTracking()
        .Where(c => c.OrganizationId == trustedOrganizationId)
        .ToListAsync(ct);

    if (chunks.Count == 0) return [];

    var vector = await embeddings.EmbedAsync(
        query, EmbeddingPurpose.Query, ct);
    var terms = HybridRank.Tokens(query);

    return chunks.Select(c => new RankedChunk(c,
            HybridRank.Score(c, terms, vector, embeddings.SpaceKey)))
        .Where(x => x.Score > 0 && x.Score >= minimumScore)
        .OrderByDescending(x => x.Score).ThenBy(x => x.Chunk.Id)
        .Take(limit).ToArray();
}

user and trustedOrganizationId must come from the same authenticated server context, including when a model invokes SearchKnowledgeBase. Neither belongs in the model's tool arguments, and authorization failures should map to appropriate HTTP responses.

I retain the application's tenant query filters as defense in depth. EF Core global filters can apply tenant conditions automatically, but they can be bypassed deliberately, so custom SQL paths need their own tenant predicates. Any future full-text or vector candidate query needs the same scope before results leave the database.

This example grants knowledge access at tenant-and-role level. When an existing application has document-specific permissions, I add those grants to the SQL predicate before materialization, not after ranking. I've written more about AI integration for existing .NET applications.

Passing retrieved chunks with source references

I pass selected passages as the SearchKnowledgeBase tool result, preserving document identity, chunk identity, source, and text. Request-local labels such as S1 map to those server-selected records; the model must not invent source URLs.

public static string BuildEvidence(IReadOnlyList<RankedChunk> hits) =>
    JsonSerializer.Serialize(new
    {
        sources = hits.Select((hit, index) => new
        {
            sourceId = $"S{index + 1}",
            documentId = hit.Chunk.DocumentId,
            chunkId = hit.Chunk.Id,
            source = hit.Chunk.Source,
            text = hit.Chunk.Content
        })
    });

The tool executor returns that JSON using the provider's native tool-result format before requesting the draft. I would not concatenate document content into the system instructions.

The model instructions require policy claims to cite those labels, treat document text as evidence rather than commands, and acknowledge missing evidence. An empty result should produce an honest limitation, not a policy assembled from general knowledge. In production, I also validate returned labels against the retrieved set and enforce a token budget that leaves room for instructions, conversation history, and the answer.

Retrieved documents can contain prompt-injection instructions. Delimiters help organize context, but they are not an authorization boundary. Tool permissions stay enforced in .NET regardless of what retrieved text says.

Limits and lessons learned

JSON storage is simple; scanning has a ceiling

The sample loads every authorized chunk and calculates similarity in application memory. Its comparison work grows with candidate count and vector dimensions, and JSON adds transfer and deserialization overhead. This is not indexed vector search. I would measure retrieval separately from generation before choosing a different search backend, rather than hiding scaling problems by ranking an arbitrary subset.

Retrieval quality and operational reliability are separate

Overlap can return near-duplicates, simple token matching lacks stemming and stopword handling, and a relevant passage can still be summarized incorrectly. Human review remains necessary.

For production, I add bounded retries, ingestion batching, cancellation checks during ranking, and explicit provider-outage behavior. The sample fails on provider errors rather than pretending a semantic search succeeded. Local Ollama avoids a hosted embedding request but still needs hardware and operational care, and a hosted provider requires an explicit decision about which document text may leave the application environment.

My evaluation set includes expected-source questions, unknown-answer questions, cross-tenant access attempts, and denied-role requests.

Conclusion

My approach to RAG ASP.NET Core work is to keep retrieval inside the application's existing rules: authorized services for live records, permission-scoped document chunks, compatible embeddings, and inspectable hybrid ranking.

The model receives limited evidence and produces a draft. It does not become the database, the permission system, or the person responsible for sending the reply.

I'm Rahmat Afridi, a senior .NET developer who adds AI to existing business applications. The full working example is in SupportAgent.NET and on GitHub.