Programmatic MCP Server

Programmatic MCP Server is a .NET library for building MCP servers that are meant to be used through generated code, not only through direct tool calls.

The library is built around one idea: an agent should be able to discover a focused capability surface, generate code against that surface, run the code in a constrained runtime, and keep large intermediate results out of model context whenever possible.

References

• https://www.anthropic.com/engineering/code-execution-with-mcp
• https://blog.cloudflare.com/code-mode-mcp/

What The Repository Provides Today

The current implementation provides:

• capability registration and progressive discovery
• read-only MCP resource registration through resources/list and resources/read
• dedicated sampling-tool registration for live MCP sampling loops
• generated JavaScript and TypeScript-facing API surface
• constrained JavaScript execution through Jint
• artifact storage and paged artifact reads
• preview, list, apply, and cancel mutation approval flows
• caller binding for HTTP MCP clients
• ASP.NET Core integration on top of the C# MCP SDK
• a runnable sample server that exercises the end-to-end loop

Why It Exists

Traditional MCP usage is tool-call-first: clients load tools, pick one, call it, and repeat. This repository supports a different model:

1. discover a narrow set of capabilities
2. generate code against a predictable API surface
3. execute that code in a bounded runtime
4. spill large outputs into artifacts
5. require explicit approval-aware mutation flows for writes

In this model, MCP is still the protocol, but the client experience is code-first.

How It Works

At a high level, the implemented flow is:

1. call initialize
2. call tools/list
3. optionally call resources/list and resources/read for read-only supplemental context
4. use capabilities.search to discover relevant capabilities
5. fetch the generated declarations from /types when the client wants stronger code generation support
6. generate JavaScript against globalThis.programmatic
7. execute that JavaScript through code.execute
8. when the server is stateful and the connected client advertises MCP sampling, use programmatic.client.sample(...) inside explicitly scoped read-only executions
9. read large results through artifact.read
10. preview and apply writes through mutation.list, mutation.apply, and mutation.cancel

For a fuller explanation of the execution model, artifact flow, approval flow, transport model, and supported scope, see docs/overview.md.

Package Layout

The repository currently ships three library packages and one sample server:

• ProgrammaticMcp Core abstractions, capability metadata, resource and sampling-tool registration, schema generation, hashing, approvals, artifacts, and shared contracts.
• ProgrammaticMcp.Jint The Jint-backed execution runtime, generated namespace bootstrap including programmatic.client.sample(...), bridge logic, and runtime diagnostics.
• ProgrammaticMcp.AspNetCore ASP.NET Core and C# MCP SDK integration, MCP tool and resource exposure, live sampling integration, caller binding, HTTP-specific behavior, and /types.
• samples/ProgrammaticMcp.SampleServer A reference host used to prove the full loop end to end.

Package-specific notes live under docs/packages.

Minimal Host Example

The smallest useful host wires the builder, registers a read-only capability, and maps the MCP route:

using ProgrammaticMcp;
using ProgrammaticMcp.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddProgrammaticMcpServer(options =>
{
    options.Builder
        .AddCapability<WeatherInput, WeatherResult>(
            "weather.current",
            capability => capability
                .WithDescription("Returns the current weather.")
                .UseWhen("You need a read-only weather lookup.")

... [View full README on GitHub](https://github.com/tonyredondo/programmatic-mcp-server#readme)