DEV Community

Ali Süleyman TOPUZ
Ali Süleyman TOPUZ

Posted on Originally published at topuzas.medium.com on

I Read the New MCP Apps Spec So You Don’t Have To: Here’s What Changes for .NET Developers

MCP stopped being a tool-calling protocol somewhere this year. Here is what that means for the C# server you are about to write.

I have been building MCP servers in C# for a while, and until recently my mental model was simple: an MCP server is a typed wrapper around some backend calls, and the model picks which wrapper to invoke. Tools in, text out. That model is now out of date, and I only noticed because I read three things in the same week and they kept describing the same shift from different angles.

The first was the MCP Apps extension spec. The second was Andrii Tkachuk’s Towards AI series on MCP servers, specifically Part 4 (security) and Part 7 (the “server as platform” argument). The third was the Microsoft Agent Framework devblog post on channels. Put together, they say something I did not expect to be writing: an MCP server in 2026 is closer to a small application platform than to a tool list, with its own UI, its own policy layer, its own discovery mechanism, and its own lifecycle.

One correction before we start, because I would rather tell you now than let you find out at 11pm. The channels packages in that devblog post (agent-framework-hosting and agent-framework-hosting-mcp, with AgentMCPTool and WorkflowMCPTool) are Python packages. The post is explicitly about the Python framework and even has a comment asking where .NET is. So I will show you the Python shape briefly, and then the .NET route that actually exists today. I would rather give you code that maps to real packages than a C# example for a Python API that I invented.

Nothing below is compiled against a live SDK. I wrote it from the docs, and several of the .NET pieces are marked experimental or preview by their own maintainers. Treat every snippet as a starting point and let the compiler have the last word.

What MCP Apps actually is

The idea is small. A tool can point at a UI resource. The host fetches that resource, renders it in a sandboxed iframe inside the conversation, and the UI can call back into your MCP server through the host. That is the whole trick. Instead of returning a JSON blob that the model summarizes into a markdown table nobody wanted, you return something a user can click.

The timeline is short and it moves fast, so here it is in one place:

WHEN WHAT HAPPENED
--------------------------------------------------------------------------
Nov 2025 SEP-1865 proposed. Builds on MCP-UI and the OpenAI
                  Apps SDK.
Jan 26, 2026 First official MCP extension announced. Claude, VS Code
                  and ChatGPT named as hosts, Goose mentioned as well.
                  Launch partner apps included Figma, Slack, Asana,
                  Box, Canva, Amplitude, Hex, monday.com and Clay.
Jul 28, 2026 2026-07-28 spec goes GA. Extensions become a formal
                  framework, and MCP Apps sits inside it next to Tasks
                  and Enterprise Managed Authorization.
Enter fullscreen mode Exit fullscreen mode

The wire format is worth knowing because it is boring in a good way. A tool declares its UI in _meta:

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "_meta": {
    "ui": {
      "resourceUri": "ui://weather-server/dashboard-template",
      "visibility": ["model", "app"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

The ui:// resource is served like any other MCP resource, with a specific MIME type, text/html;profile=mcp-app, and optional metadata about what the page is allowed to reach:

{
  "uri": "ui://weather-server/dashboard-template",
  "name": "weather_dashboard",
  "mimeType": "text/html;profile=mcp-app",
  "_meta": {
    "ui": {
      "csp": { "connectDomains": ["https://api.openweathermap.org"] },
      "prefersBorder": true
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Inside the iframe, the page talks to the host with JSON-RPC 2.0 over postMessage. It initializes with ui/initialize, receives the tool's input as a notification, and can call your tools with a plain tools/call. From your server's point of view, a UI click is just another tool call arriving through the host. Keep that sentence in mind, because the whole security discussion hangs off it.

The .NET side

The official C# SDK has a package for this, ModelContextProtocol.Extensions.Apps, and it is marked experimental. Every type carries [Experimental("MCPEXP003")], so you have to suppress that diagnostic on purpose. I like that. It tells you that you are building on something that can still move.

dotnet add package ModelContextProtocol.Extensions.Apps
Enter fullscreen mode Exit fullscreen mode

From the SDK docs, the shape is an attribute on the tool method plus a builder call:

#pragma warning disable MCPEXP003

[McpServerToolType]
public class WeatherTools
{
    [McpServerTool, Description("Get current weather for a location")]
    [McpAppUi(ResourceUri = "ui://weather/view.html")]
    public static string GetWeather(string location) => $"Weather for {location}";
}

builder.Services.AddMcpServer()
    .WithHttpTransport(o => o.Stateless = true)
    .WithTools<WeatherTools>()
    .WithMcpApps();
Enter fullscreen mode Exit fullscreen mode

Then you serve the HTML itself as a resource with the constant the SDK gives you, McpApps.HtmlMimeType, which is the text/html;profile=mcp-app string. The SDK also exposes McpUiToolMeta, McpUiToolVisibility (Model or App) and McpUiResourceMeta for CSP and permissions, plus a McpApps.GetUiCapability(...) helper so a tool can check whether the connected client can render UI at all. That last one matters more than it sounds. Plenty of hosts will not, and your tool still has to return something useful as plain text.

I did not find a documented property for setting visibility directly on [McpAppUi], so check IntelliSense on your SDK version before assuming one. The JSON above is the contract, and the C# types are a convenience over it.

The security model, without the hand waving

Here is the framing I now use, and I think it is the only one that survives contact with a real deployment: the UI is untrusted, the host is a referee, and your backend is the trust boundary.

The spec gives hosts four layers to work with. The iframe is sandboxed with minimal permissions. The host builds a Content Security Policy from the domains your resource declares, and undeclared origins are blocked. Every message between the view and the host is auditable JSON-RPC. And templates are predeclared, so a host can inspect the HTML at connection time, before any tool runs.

That is a decent design. It is also not your authorization system. The MCP core maintainers say as much in the launch post: users should keep vetting MCP servers before connecting them, and you are still running code you did not write. A reasonable person can look at this and say the jury is out, and I am one of them.

Visibility is a UX feature, not a permission

The most useful detail in the spec, for me, is _meta.ui.visibility:

VISIBILITY VALUE WHO CAN CALL IT LISTED TO THE MODEL?
--------------------------------------------------------------------------
["model", "app"] agent and UI (default) yes
["model"] agent only yes
["app"] UI only no
Enter fullscreen mode Exit fullscreen mode

App-only tools are how you build the plumbing a UI needs, like refresh_chart_data or submit_form_step, without polluting the model's tool list. That is a real win for context size and for reducing accidental calls.

But do not read ["app"] as "the model cannot reach this, so it is safe". It means the model is not shown the tool. The UI can still call it, and the UI is untrusted code served by a server you may not fully control, running inside a host you do not control at all. Tkachuk's Part 4 has a line I keep repeating to people: tags and annotations are metadata, they are not authorization. Visibility belongs in the same bucket.

So every tool, including the app-only ones, does its own checks. Here is what that looks like in a .NET server. The tool is hidden from the model, and it still refuses to trust its caller:

[McpServerToolType]
public class InvoiceTools(IHttpContextAccessor http, IInvoiceStore store, IAuditLog audit)
{
    [McpServerTool, Description("Approve an invoice. Called from the review UI only.")]
    [McpAppUi(ResourceUri = "ui://invoices/review.html")]
    public async Task<string> ApproveInvoiceAsync(
        string invoiceId, CancellationToken ct)
    {
        var user = http.HttpContext!.User;

        // 1. Tool-level: does this caller hold the scope at all?
        if (!user.HasClaim("scope", "invoices:approve"))
            throw new McpException("Forbidden: missing scope invoices:approve");

        // 2. Argument-level: is THIS invoice inside THIS caller's tenant?
        var tenantId = user.FindFirst("tid")?.Value;
        var invoice = await store.GetAsync(invoiceId, ct);
        if (invoice is null || invoice.TenantId != tenantId)
            throw new McpException("Invoice not found.");

        // 3. Destructive action gets an audit record with the full lineage.
        await audit.WriteAsync(new AuditEntry(
            Actor: user.Identity!.Name!,
            Tool: "approve_invoice",
            Target: invoiceId,
            Tenant: tenantId!), ct);

        await store.ApproveAsync(invoiceId, ct);
        return $"Invoice {invoiceId} approved.";
    }
}
Enter fullscreen mode Exit fullscreen mode

Three checks, three different questions. Scope answers “may this caller use the tool”. The tenant comparison answers “may they use it on this argument”, which is the one people skip. The audit entry answers “can I reconstruct who did what later”. Notice that I return “not found” for a cross-tenant invoice instead of “forbidden”, so the tool does not confirm which ids exist in other tenants.

MCP servers as platforms

Now the second half of the story, and the reason I think the Apps extension is a symptom rather than the main event. Tkachuk’s Part 7 argues that mature MCP servers stop exposing raw backend APIs and start shaping the capability surface itself. His line that stuck with me: a good agent architecture does not only optimize the model’s reasoning, it optimizes what the model is asked to reason about.

Part 4 supplies the security half and Part 7 the platform half. Between them, here is the vocabulary, mapped to the problem each item solves:

TECHNIQUE THE PROBLEM IT SOLVES
--------------------------------------------------------------------------
Dynamic tool filtering Different callers should see different tools,
                           resolved server-side from identity
Policy registry One place that says which tool is allowed
                           for which role, and what needs auditing
Meta-tools / Code Mode Large tool surfaces: expose search + execute
                           instead of 500 schemas in the context window
Argument-level authz "May call the tool" is not "may call it on
                           this tenant / project / record"
Token exchange Scoped credentials per boundary, instead of
                           forwarding the user's token blindly downstream
Audit trails user -> agent -> MCP -> tool -> data lineage
Tool Search Retrieval over the catalog, so schemas load
                           on demand (BM25-style ranking is the usual
                           implementation)
Namespacing Identity and provenance when composing servers
Component visibility Show or hide capabilities per context
MCP Proxy One server composing several others into a
                           single governed surface
Skills as Resources Ship procedural knowledge next to the tools
Elicitation A tool asks the user for input mid-workflow
Background Tasks Protocol-native lifecycle for long operations
Versioning Serve v1 and v2 of a tool to different callers
Enter fullscreen mode Exit fullscreen mode

I am not going to walk through all fourteen. Two of them changed how I design, and one deserves a caveat.

Token exchange over blind forwarding. If your MCP server receives the user’s bearer token and passes it straight to a downstream API, you have made the MCP server a confused deputy. Any tool, including a compromised or badly prompted one, can now do anything the user can do downstream. Exchanging the incoming token for a narrowly scoped one per downstream boundary (RFC 8693 is the standard shape) means a leaked or misused token has a small blast radius. In ASP.NET terms, this is an IDownstreamTokenProvider you write once and inject everywhere, instead of HttpContext.Request.Headers.Authorization copied into an HttpClient.

Meta-tools for big surfaces. When the tool list gets long, the model spends its attention choosing among schemas instead of solving the task. Exposing a search_tools and an execute_tool pair moves that choice out of the context window and into code you control. It also gives you one chokepoint where authorization and audit happen, which is the security argument from Part 4 arriving from a different direction. The same idea that helps tokens also helps security. I did not expect those two to line up so cleanly.

Now the caveat. Part 7 lists Logging as a platform technique, meaning client-facing status messages separated from real observability. The 2026–07–28 spec marks Logging as deprecated, with a minimum twelve month off-ramp, alongside Roots and Sampling. That does not make the advice wrong, since keeping user-facing status apart from production telemetry is still sound, but if you plan a design around protocol-level logging notifications, check the current spec first. The same spec release also makes the core protocol stateless, moves method and tool names into Mcp-Method and Mcp-Name headers so gateways can route without parsing bodies, and replaces server-initiated requests with a multi round-trip pattern where a server returns input_required and the client retries with the answers attached. That last change is how elicitation works over a stateless transport, and it is the one I would read closely if you use elicitation today. Tasks, meanwhile, moved out of experimental core into a proper extension.

The testing discipline most MCP writeups skip

This is the part of Part 7 I would keep even if I threw away the rest. Tkachuk’s point is that most people test the C# method behind the tool and call it done. The method is not the product. The product is what a real MCP client sees over the wire. His four layers:

LAYER WHAT YOU ASSERT FAILS WHEN
--------------------------------------------------------------------------
Contract Schemas, descriptions, _meta are what someone renames a
             you promised parameter
Discovery Each caller sees exactly the tools a filter or policy
             they should, and no others change leaks a tool
Execution Bad input and forbidden input return an exception escapes
             clean errors, good input returns data or a check is missing
Lifecycle Long tasks start, report progress, a task never leaves
             finish, and can be cancelled "working"
Enter fullscreen mode Exit fullscreen mode

In .NET the practical version is a WebApplicationFactory hosting your real server and a real McpClient talking to it. No mocks between the client and your tools. Something like this, and again, verify the constructor shapes on your SDK version, since the client API has been renamed a couple of times across previews:

public class InvoiceServerSurfaceTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly WebApplicationFactory<Program> _factory;
    public InvoiceServerSurfaceTests(WebApplicationFactory<Program> f) => _factory = f;

    private Task<McpClient> ConnectAsync(string? bearer = null)
    {
        var http = _factory.CreateClient();
        if (bearer is not null)
            http.DefaultRequestHeaders.Authorization = new("Bearer", bearer);

        var transport = new HttpClientTransport(
            new HttpClientTransportOptions { Endpoint = new Uri("http://localhost/mcp") },
            http);
        return McpClient.CreateAsync(transport);
    }

    [Fact] // CONTRACT
    public async Task Approve_tool_declares_its_ui_and_required_args()
    {
        await using var client = await ConnectAsync(TestTokens.Approver);
        var tool = (await client.ListToolsAsync())
            .Single(t => t.Name == "approve_invoice");

        Assert.Contains("invoiceId", tool.JsonSchema.GetRawText());
        Assert.False(string.IsNullOrWhiteSpace(tool.Description));
    }

    [Fact] // DISCOVERY
    public async Task Anonymous_caller_does_not_see_approve_tool()
    {
        await using var client = await ConnectAsync(bearer: null);
        var names = (await client.ListToolsAsync()).Select(t => t.Name);

        Assert.DoesNotContain("approve_invoice", names);
    }

    [Fact] // EXECUTION
    public async Task Cross_tenant_invoice_is_rejected_not_leaked()
    {
        await using var client = await ConnectAsync(TestTokens.ApproverTenantA);
        var result = await client.CallToolAsync(
            "approve_invoice",
            new Dictionary<string, object?> { ["invoiceId"] = "inv-belongs-to-tenant-b" });

        Assert.True(result.IsError);
        Assert.DoesNotContain("tenant", result.Content.OfType<TextContentBlock>()
            .First().Text, StringComparison.OrdinalIgnoreCase);
    }
}
Enter fullscreen mode Exit fullscreen mode

The lifecycle layer is the one I have not seen a tidy .NET pattern for yet, mostly because the Tasks extension is new and the C# package for it is itself an extension. The shape of the test is easy to describe, though: start the long operation, poll until it reports a terminal state with a timeout, then assert on the result, and in a second test cancel it mid-flight and assert the server actually stopped work. If you only write one lifecycle test, make it the cancel one. Cancellation is where servers lie to you.

One more thing on discovery tests. If you use _meta.ui.visibility, add a test that asserts app-only tools are absent from the model-facing list, and a separate execution test that calls them without the right scope and expects a refusal. The first test proves the UX. The second proves the security. They are not the same test.

Exposing agents as MCP tools: Python channels, .NET reality

Back to the correction from the top. The Agent Framework channels post describes hosting a single agent or workflow behind several transports, with separate packages per channel: agent-framework-hosting as the base, plus responses, Telegram, A2A and MCP variants. For MCP specifically, the post says AgentMCPTool and WorkflowMCPTool derive native tools from Agent Framework targets. The only code the post gives for the state layer is this, in Python:

from agent_framework_hosting import AgentState, WorkflowState

agent_state = AgentState(agent)
workflow_state = WorkflowState(workflow_builder, cache_target=False)
Enter fullscreen mode Exit fullscreen mode

I am not going to guess at the rest of that API. If you work in Python, read the post and the package docs.

In .NET, the route that exists today is one layer lower and more explicit. Microsoft Agent Framework for .NET lets you convert an agent into an AIFunction, and the C# MCP SDK lets you turn an AIFunction into an McpServerTool. Chain them and your agent becomes a tool any MCP client can call. The pattern comes from community write-ups against preview packages, so pin versions and expect drift:

dotnet add package Microsoft.Agents.AI --prerelease
dotnet add package ModelContextProtocol
dotnet add package ModelContextProtocol.AspNetCore
dotnet add package OllamaSharp

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using ModelContextProtocol.Server;
using OllamaSharp;

// Local model, no API key. Any IChatClient works here.
IChatClient chat = new OllamaApiClient(new Uri("http://localhost:11434"), "llama3.1");

AIAgent invoiceAgent = chat.AsAIAgent(
    instructions: "You summarize invoices for a reviewer. Never approve anything.",
    name: "InvoiceSummarizer",
    description: "Summarizes an invoice for human review.",
    tools: [AIFunctionFactory.Create(InvoiceLookup.GetInvoiceAsync)]);

// Agent -> AIFunction -> McpServerTool -> MCP server
McpServerTool agentTool = McpServerTool.Create(invoiceAgent.AsAIFunction());

var builder = WebApplication.CreateBuilder(args);
builder.Services
    .AddMcpServer()
    .WithHttpTransport(o => o.Stateless = true)
    .WithTools([agentTool]);

var app = builder.Build();
app.MapMcp("/mcp");
await app.RunAsync();
Enter fullscreen mode Exit fullscreen mode

Run ollama pull llama3.1 first, and swap the IChatClient for a hosted model when you are ready. A small local model is flaky at tool calling, so this is for validating the plumbing, not for judging agent quality.

My opinion, after thinking about this alongside the platform material: exposing an agent as a tool is the point where the earlier sections stop being optional. An agent behind an MCP tool is a tool that can decide things. Argument-level authorization, token exchange, audit lineage and a contract test that pins the tool’s description are what keep a summarizer agent from quietly becoming an approver. Notice that my instructions above say “never approve anything”, and I would still not rely on that sentence. Prompt is not policy.

If you just want to get started safely

Everything above is for people building servers. Most readers first need to use them, and that is where I see the most avoidable damage. My rule of thumb is three lines:

1. Keep it to 5 to 7 servers. Past that, tool selection degrades and
   you cannot remember what each one can touch.
2. Treat every server like a stranger's code. It runs with your
   credentials and its tool descriptions go straight into the model.
3. Never point one at a production database. Use a copy, a read-only
   replica, or a sandbox project.
Enter fullscreen mode Exit fullscreen mode

The number is a rule of thumb from experience and from the tool-surface arguments in the sources above, not a measured limit. The principle behind it is the useful part.

Here are real setup commands for four common servers, each with the scoping option I would turn on first.

Filesystem. Give it one sandbox directory, not your home folder:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/mcp-sandbox
Enter fullscreen mode Exit fullscreen mode

If you prefer Docker, the server’s README shows read-only mounts with an ro suffix, which is what I would use for anything you only need to read:

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--mount", "type=bind,src=/Users/me/docs,dst=/projects/docs,ro",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Context7. Library docs for the model. It is low risk since it only reads public documentation, and an API key is optional:

claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp
Enter fullscreen mode Exit fullscreen mode

GitHub. Use a fine-grained token limited to the repos you need, and turn on read-only mode and a narrow toolset:

claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_PAT \
  -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN \
  -e GITHUB_TOOLSETS="repos,issues" \
  ghcr.io/github/github-mcp-server --read-only
Enter fullscreen mode Exit fullscreen mode

GitHub also hosts a remote server at https://api.githubcopilot.com/mcp/ if you would rather not run a container. Check the README for where --read-only goes on your version.

Notion. Create an internal integration, restrict it to read content unless you truly need writes, and share only the pages it should see:

claude mcp add notion -e NOTION_TOKEN=ntn_your_token_here \
  -- npx -y @notionhq/notion-mcp-server
Enter fullscreen mode Exit fullscreen mode

Notion’s own docs point toward their hosted remote MCP server with OAuth as the easier option, and the local package is the fallback.

None of this is exotic. It is the same least privilege thinking you would apply to any service account, applied to something that reads instructions in natural language.

Where I landed

I started that week thinking of MCP as plumbing. I finished it thinking of MCP as a place where your organization’s policy lives, because the server is the one component in the chain that you actually control. The model reasons, the host renders, the UI is untrusted, and the server decides. If I had to boil the whole reading list into one habit for .NET developers, it would be this: design the surface before you write the tools, enforce at execution time and not only at discovery time, and test the wire, not the method.

I am still unsure about two things. MCP Apps is still young, and I am not convinced that iframe sandboxing plus host approvals is enough once UIs get ambitious, a doubt the maintainers themselves leave open. And I do not yet know how much of the “platform” vocabulary will survive as the protocol goes stateless, since the July spec already reshapes elicitation and deprecates logging. Build on the parts that are stable, isolate the parts that are experimental, and put the experimental ones behind a test that will tell you when they move.

Sources:

  • MCP Core Maintainers, “MCP Apps: Bringing UI Capabilities To MCP Clients” (Jan 26, 2026), blog.modelcontextprotocol.io
  • MCP Apps specification, SEP-1865, modelcontextprotocol/ext-apps, spec version 2026–01–26
  • “The 2026–07–28 Specification,” Model Context Protocol Blog
  • MCP C# SDK documentation, “MCP Apps” (package ModelContextProtocol.Extensions.Apps, experimental)
  • Andrii Tkachuk, “Stop Building AI Apps for Every Idea. Start Building MCP Servers, Part #4” and “Part #7,” Towards AI
  • Microsoft DevBlogs (Agent Framework), “Introducing agent and workflow channels” (Python packages)
  • Jamie Maguire, “Microsoft Agent Framework: Exposing an Existing AI Agent as an MCP Tool” (preview-era .NET pattern)
  • Server READMEs: modelcontextprotocol/servers (filesystem), github/github-mcp-server, makenotion/notion-mcp-server, Context7 docs

Tags: mcp, dotnet, csharp, ai-agents, security, model-context-protocol, microsoft-agent-framework

Top comments (0)