Stateless & serverless servers

Two things break when your server does not keep session state between requests: session identity (calls stop lining up into one session) and delivery (the platform freezes your process before background events are sent). This page applies to you if either of these is true:

You deploy to serverless (Vercel, Lambda, Cloud Run scaled to zero), so initialize and each tool call land on different instances.
You set stateless_http=True, or the equivalent in your SDK, even when you run a single long-lived container or process.

How to tell you need this

Open your Sessions page. Without the two steps below, you will see:

Sessions don’t line up. Calls arrive with no session identity, so Armature falls back to heuristic grouping: separate conversations from the same caller can merge into one session, and others land as fallback sessions instead of one session per conversation.
Client shown as Unknown. The client name and version never reach us.

Both symptoms come from the same cause, and step 2 below fixes both at once. Both fixes are one-liners. They cover clients on the classic handshake protocol, which is still most agent traffic today. Requests on the 2026-07-28 protocol revision carry no initialize handshake and are attributed automatically.

1. Use `await` delivery

Background delivery relies on the process staying alive after the response. In serverless, send events before returning instead:

createMcpAnalyticsServer(buildServer, {
  armature: { delivery: "await" },
});

instrument_fastmcp(mcp, {"armature": {"delivery": "await"}})

config.Delivery = armatureanalytics.DeliveryAwait

2. Resolve the session per request

The SDK mints identity-bearing session IDs (mcp_<client>_v_<version>_<uuid>) on initialize and reads them back on later requests, so client attribution survives across instances.

TypeScript
Python
Go

Call resolveStatelessHttpSession per request and pass the results to the transport and dispatch context:

import { resolveStatelessHttpSession } from "@armature-tech/mcp-analytics";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

const session = resolveStatelessHttpSession({
  body: requestBody,
  headers: requestHeaders,
});

const transport = new StreamableHTTPServerTransport({
  sessionIdGenerator: session.sessionIdGenerator,
  enableJsonResponse: true,
});

// with a custom dispatcher:
await analytics.dispatch(name, args, { ...context, ...session.dispatchContext });

Wrap your ASGI app in the dependency-free middleware. It handles minting and echoing automatically:

from armature_mcp_analytics import StatelessHttpSessionMiddleware

# standalone FastMCP
app = StatelessHttpSessionMiddleware(
    mcp.http_app(stateless_http=True, json_response=True)
)

# official MCP Python SDK
# mcp = FastMCP("Customer MCP", stateless_http=True, json_response=True)
# app = StatelessHttpSessionMiddleware(mcp.streamable_http_app())

On go-sdk v1.7.0, StreamableHTTPHandler{Stateless: true} ignores Mcp-Session-Id entirely (GetSessionID is never consulted), so wrap the HTTP handler with the analytics middleware. This is required for legacy-client attribution:

rec, err := official.NewRecorder(config)
if err != nil {
	return err
}
http.Handle("/mcp", rec.WrapStatelessHTTPHandler(mcpHandler))

On mark3labs/mcp-go (and official go-sdk ≤ v1.6), resolve the session per request, then hand it to the transport options (mark3labs) or the server options (official):

session := armatureanalytics.ResolveStatelessHTTPSession(armatureanalytics.StatelessHTTPInput{
	Body:    body,
	Headers: r.Header,
})

// mark3labs/mcp-go: the manager goes on the HTTP transport, not the server
s, shutdown := armatureanalytics.NewMCPServer(name, version,
	server.WithToolCapabilities(true),
)
defer shutdown(r.Context())

handler := server.NewStreamableHTTPServer(s,
	server.WithSessionIdManager(session.Mark3labsSessionIDManager()),
)
handler.ServeHTTP(w, r)

// official go-sdk <= v1.6
s, shutdown := official.NewMCPServer(impl, &mcp.ServerOptions{
	GetSessionID: session.SessionIDGenerator(),
})
// serve with &mcp.StreamableHTTPOptions{Stateless: true, JSONResponse: true}

Session IDs are attribution metadata, not a security boundary. Clients echo them back unsigned. Keep authorization on your own auth layer.

Getting started

Analytics

Evaluation

SDKs

Armature MCP

Privacy & security

Stateless & serverless servers

How to tell you need this

1. Use `await` delivery

2. Resolve the session per request

​How to tell you need this

​1. Use await delivery

​2. Resolve the session per request

How to tell you need this

1. Use `await` delivery

2. Resolve the session per request