Expose your backend's endpoints to an agent

The ASP.NET Core and NestJS SDKs turn the endpoints you already wrote into a searchable tool catalog. An agent finds an endpoint, reads its schema and calls it through your own authorization pipeline, with no second service to keep in sync.

You work inside this repository's sample backend, so the SDK is already referenced. To add the package to your own ASP.NET Core project instead, the install steps are in sdks/dotnet/README.md.

1. Register the SDK

builder.Services.AddSezzlee();

var app = builder.Build();

app.UseSezzleeCapture();

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

app.MapControllers();
app.MapSezzlee("/mcp");

On ASP.NET Core this is DemoApi's Program.cs, and it is the whole integration. AddSezzlee() registers discovery, UseSezzleeCapture() takes a handle on the pipeline, and MapSezzlee("/mcp") serves the MCP endpoint. Put UseSezzleeCapture() before UseRouting, UseAuthentication and UseAuthorization. Agent calls are replayed into the pipeline from that point on.

On NestJS this is the demo-api sample's app.module.ts. forRoot takes a callback that mutates an options object, not an options literal.

2. Mount /mcp

ASP.NET Core did this already with MapSezzlee. Skip to step 3.

NestJS does not map the endpoint for you. You write the controller, because a module cannot add a route to a class you own:

@Controller()
export class McpController {
  private readonly serve: SezzleeRequestHandler;

  constructor(
    private readonly streamableHttp: SezzleeStreamableHttp,
    private readonly catalog: SezzleeCatalog,
    private readonly dispatcher: SezzleeDispatcher,
    private readonly visibility: CallerVisibilityProvider,
    @Inject(extensionTokens.invokeResultMapper)
    private readonly mapper: InvokeResultMapper,
    @Inject(extensionTokens.callerScopeResolver)
    private readonly scopes: CallerScopeResolver,
    @Inject(SEZZLEE_OPTIONS) private readonly options: SezzleeOptions,
  ) {
    this.serve = this.streamableHttp.serve(() => {
      const server = new McpServer({ name: "demo-api", version: "0.0.0" });
      registerSezzleeTools(server, {
        catalog: this.catalog,
        dispatcher: this.dispatcher,
        mapper: this.mapper,
        visibility: this.visibility,
        scopes: this.scopes,
        options: this.options,
      });
      return server;
    });
  }

  @All("mcp")
  async handle(@Req() req: Request, @Res() res: Response): Promise<void> {
    await this.serve(req, res);
  }
}

SezzleeModule is global, so the providers need no extra import. Bind the handler once, in the constructor. Then bootstrap in this order in src/main.ts:

import "reflect-metadata";
// ...
const app = await NestFactory.create(AppModule);
app.useGlobalPipes(new ValidationPipe({ transform: true }));

await app.init();

app.use(mcpAuthRouter({ provider: app.get(DemoOAuthProvider), ... }));
await app.listen(3000);

3. Describe one endpoint

Nothing is exposed by default. [McpTool] or @McpTool() on a class opts the controller in. A description on the method is what an agent searches against.

[HttpGet("/orders/{id:int}")]
[Authorize(Policy = "OrdersRead")]
[Description("Fetches one order by id.")]
public IActionResult GetOrder([Description("Order id")] int id) =>
    Orders.TryGetValue(id, out var order) ? Ok(order) : NotFound();

sezzlee reads ASP.NET's own [Description] metadata, so there is no second copy to write. On NestJS the class-validator decorators on CreateOrderDto become the input schema. In both, the authorization line is untouched and runs when the agent calls.

4. Run it

dotnet run --project sdks/dotnet/samples/DemoApi

The backend reports what it found:

info: Sezzlee.AspNetCore.SezzleeCatalogProvider[0]
      sezzlee catalog: 16 discovered, 9 selected, 9 tools, 0 diagnostic(s)

On ASP.NET Core, sixteen endpoints exist and nine were selected, because only the decorated ones come through. Leave the backend running.

5. Call it as an agent

In a second terminal, run the repository's example client:

node sdks/nestjs/samples/agent-client/dist/main.js --scenario smoke --query "get order"

step                      ok    detail
tools/list                ok    load_tool, search_tools, invoke_tool
search_tools "get order"  ok    8/8 results
load_tool get_order       ok    {"type":"object","properties":{"id":{"type":"integer","description":"Order id"}},"required":["id"],"additionalProperties":false}
invoke_tool get_order     ok    {"status":200,"body":{"id":1,"item":"mechanical keyboard","quantity":2,"owner":"alice"}}

That is the whole product in four lines. tools/list returned three tools, not the whole catalog. search_tools matched your description and returned a compact card. load_tool built the input schema from your code. invoke_tool reached the handler through your own authorization and returned its answer. The client authenticated as alice.

On NestJS, SEZZLEE_AUTH=token uses the sample's POST /auth/token shortcut, and the order id increments on each run. The NestJS sample shows 7/8 rather than 8/8 because its guards are imperative code, so sezzlee falls back to probing; Declare visibility for a NestJS guard is the fix. Its schema also carries no property descriptions, because NestJS has no equivalent of ASP.NET's description metadata. You supply them with @McpTool({ description }) per method.

Where to go next

• Expose a whole backend without decorating each endpoint: Choose which endpoints become tools.
• Make bob see less than alice: Control what a caller can see.
• Fix the 7/8 on NestJS: Declare visibility for a NestJS guard.
• The exact wire shape: Meta-tool contract.

For the normative rules, read the spec in packages/http/spec. These pages describe; the spec binds.

MapSezzlee() requires app.UseSezzleeCapture() earlier in the pipeline, before UseRouting(),
UseAuthentication() and UseAuthorization(). Add app.UseSezzleeCapture() near the top of the pipeline.