Skip to main content
Documents saga a2ui 0.11.0-rc.1 (prerelease). This is the SDK guide docs/attach-to-existing-backend.md at source revision fb4126c. It is published as a snapshot: later source changes do not alter it. Licensed under Apache-2.0.
This document is generated. Each snippet is the maintained starter template’s own text, cut from the files CI builds and qualifies, so it cannot drift from a tested file. The setup guide explains the concepts and the order to read them in. Attaching SAGA to a backend you already run is an integration you make in your own source. No command edits an existing application: saga init creates one new directory and nothing else. The Lit and React stacks belong to the public npm release set. These source-based snippets use matched local candidate packages so they can qualify unpublished changes (see Install the packages from a candidate).

Which pairs have a recipe

A pair is listed only while CI qualifies it, and a qualified pair is not automatically offered by saga init: that command offers the pairs in its own list. A recipe is not a claim about any other pair, and no full matrix is claimed.

Required servers without a recipe yet

Every required server target has a qualified template above.

The steps, whichever server you use

  1. Install the SDK packages the recipe lists from one candidate, together, and keep the @a2ui/markdown-it override in your root package.json.
  2. Decide who is asking. Your application authenticates the request (server/verifier.ts is the seam for your identity provider) and gives SAGA the result only through the transport’s per-request auth, as in the identity handoff below. A protected operation that receives no verified identity does not run; a declared public operation needs none and is given none.
  3. Read the built HTML before listening. The preparation snippet defines view from options.html and its actual filename (index.html in the starter); server/main.ts reads that file. Prepare it once and reuse it in each request factory.
  4. Register the operations your backend exposes. The handler makes your own authorization decision for that request’s identity, and the projection copies the public fields out of the record by name.
  5. Build the view with your own catalog and serve it as the operation’s view resource, as the starter does. The view’s address preserves its filename and fingerprints its final bytes, so rebuild the view and restart the server together.
  6. Attach each action to the rendered control it belongs to. The layout names no action; the attachment is application code.
CI qualifies the starter’s listener and operations against real MCP clients. That qualification belongs to the starter: attaching the same lines to your application does not inherit it. Test your own authentication, authorization and refusal paths in your application.

node with lit-mcp

Template: templates/lit-node. Server adapter: @modelcontextprotocol/node 2.1.1. SDK packages: @saga-a2ui/core, @saga-a2ui/lit, @saga-a2ui/components, @saga-a2ui/mcp, @saga-a2ui/lit-mcp-stack. The snippets below call the starter’s own application files, which you read in the template (or in a project saga init created) and adapt: server/authenticate.ts, server/authorization.ts, server/endpoint.ts, server/identity.ts, server/verifier.ts. server/verifier.ts and server/authorization.ts are where your identity provider and your policy go; the starter ships neither.

Prepare the view and endpoint handlers once

From templates/lit-node/server/listener.ts:

Hand the verified identity to the transport

From templates/lit-node/server/listener.ts:

Register a protected operation

From templates/lit-node/server/operations.ts:

Attach an action to a rendered control

From templates/lit-node/src/view.ts:

express with lit-mcp

Template: templates/lit-express. Server adapter: @modelcontextprotocol/express 2.0.2. SDK packages: @saga-a2ui/core, @saga-a2ui/lit, @saga-a2ui/components, @saga-a2ui/mcp, @saga-a2ui/lit-mcp-stack. The snippets below call the starter’s own application files, which you read in the template (or in a project saga init created) and adapt: server/authenticate.ts, server/authorization.ts, server/endpoint.ts, server/identity.ts, server/verifier.ts. server/verifier.ts and server/authorization.ts are where your identity provider and your policy go; the starter ships neither.

Prepare the view and endpoint handlers once

From templates/lit-express/server/listener.ts:

Hand the verified identity to the transport

From templates/lit-express/server/listener.ts:

Register a protected operation

From templates/lit-express/server/operations.ts:

Attach an action to a rendered control

From templates/lit-express/src/view.ts:

fastify with lit-mcp

Template: templates/lit-fastify. Server adapter: @modelcontextprotocol/fastify 2.0.1. SDK packages: @saga-a2ui/core, @saga-a2ui/lit, @saga-a2ui/components, @saga-a2ui/mcp, @saga-a2ui/lit-mcp-stack. The snippets below call the starter’s own application files, which you read in the template (or in a project saga init created) and adapt: server/authenticate.ts, server/authorization.ts, server/endpoint.ts, server/identity.ts, server/verifier.ts. server/verifier.ts and server/authorization.ts are where your identity provider and your policy go; the starter ships neither.

Prepare the view and endpoint handlers once

From templates/lit-fastify/server/listener.ts:

Hand the verified identity to the transport

From templates/lit-fastify/server/listener.ts:

Register a protected operation

From templates/lit-fastify/server/operations.ts:

Attach an action to a rendered control

From templates/lit-fastify/src/view.ts:

hono with lit-mcp

Template: templates/lit-hono. Server adapter: @modelcontextprotocol/hono 2.0.2. SDK packages: @saga-a2ui/core, @saga-a2ui/lit, @saga-a2ui/components, @saga-a2ui/mcp, @saga-a2ui/lit-mcp-stack. The snippets below call the starter’s own application files, which you read in the template (or in a project saga init created) and adapt: server/authenticate.ts, server/authorization.ts, server/endpoint.ts, server/identity.ts, server/verifier.ts. server/verifier.ts and server/authorization.ts are where your identity provider and your policy go; the starter ships neither.

Prepare the view and endpoint handlers once

From templates/lit-hono/server/listener.ts:

Hand the verified identity to the transport

From templates/lit-hono/server/listener.ts:

Register a protected operation

From templates/lit-hono/server/operations.ts:

Attach an action to a rendered control

From templates/lit-hono/src/view.ts:

hapi with lit-mcp

Template: templates/lit-hapi. Server adapter: @modelcontextprotocol/node 2.1.1. SDK packages: @saga-a2ui/core, @saga-a2ui/lit, @saga-a2ui/components, @saga-a2ui/mcp, @saga-a2ui/lit-mcp-stack. The snippets below call the starter’s own application files, which you read in the template (or in a project saga init created) and adapt: server/authenticate.ts, server/authorization.ts, server/bridge.ts, server/identity.ts, server/verifier.ts. server/verifier.ts and server/authorization.ts are where your identity provider and your policy go; the starter ships neither.

Prepare the view and endpoint handlers once

From templates/lit-hapi/server/listener.ts:

Hand the verified identity to the transport

From templates/lit-hapi/server/listener.ts:

Register a protected operation

From templates/lit-hapi/server/operations.ts:

Attach an action to a rendered control

From templates/lit-hapi/src/view.ts:

hono with react-mcp

Template: templates/react-hono. Server adapter: @modelcontextprotocol/hono 2.0.2. SDK packages: @saga-a2ui/core, @saga-a2ui/react, @saga-a2ui/components, @saga-a2ui/mcp, @saga-a2ui/react-mcp-stack. The snippets below call the starter’s own application files, which you read in the template (or in a project saga init created) and adapt: server/authenticate.ts, server/authorization.ts, server/endpoint.ts, server/identity.ts, server/verifier.ts. server/verifier.ts and server/authorization.ts are where your identity provider and your policy go; the starter ships neither.

Prepare the view and endpoint handlers once

From templates/react-hono/server/listener.ts:

Hand the verified identity to the transport

From templates/react-hono/server/listener.ts:

Register a protected operation

From templates/react-hono/server/operations.ts:

Attach an action to a rendered control

From templates/react-hono/src/view.tsx: