AgentBack — /mcp Request Lifecycle

A POST flows ①→⑦ through the group-sorted cascade into the route; an OPTIONS preflight short-circuits at ①. Companion to middleware-chain.html.

next() next() next() → router OPTIONS preflight over rate limit guard rejects Client / Browser POST or OPTIONS /mcp Chain front door app.use(toExpressMiddleware) — mounted 1st (constructor) resolves + group-sorts the chain per request ① group: cors stamp Access-Control-* headers POST → next() · OPTIONS preflight → 204 (✗ next) ② group: parseBody express.json() → req.body marks req._body = true ③ group: middleware app.middleware(rateLimiter) under limit → next() POST /mcp route installMcpHttp — mounted before start(), behind the chain ④ ...guards — authenticate → set req.auth { scopes } ⑤ express.json() — req._body set in ② → SKIP ⑥ handler — isInitializeRequest(req.body) ✓ buildServer({ scopes }).connect(transport) ⑦ transport.handleRequest(req, res, req.body) → JSON-RPC initialize result guards (④) come from strategyAuth / OAuth — per-route, not in the chain (MCP auth is session/scope-aware) 200 — SSE / JSON-RPC stream server → client over Streamable HTTP OPTIONS preflight → 204 cascade STOPS at ① — no body, no auth, no transport over limit → 429 short-circuits before the router guard reject → 401 + WWW-Authenticate transport never built Legend chain front door cors / short-circuit parseBody middleware / success install* route (/mcp) next() (cascade continues) short-circuit exit (✗ next)

Resolved order (POST)

  • • Chain is the 1st handler; cascade is group-sorted: cors → parseBody → middleware
  • • Each calls next(); on cascade end, toExpressMiddleware calls Express next() → router
  • • /mcp route (mounted by installMcpHttp) is the destination behind the chain
  • • ⑤ the route's own express.json() no-ops (req._body set in ②)

Short-circuit exits

  • • OPTIONS preflight → cors ends 204 at ①, no next() (cheapest exit)
  • • rate limit exceeded → 429 at ③, before the router
  • • auth guard rejects → 401 at ④, transport never built
  • • A non-preflight POST never short-circuits at ① — cors just stamps headers

Layering

  • • Edge concerns (cors, body, rate-limit) live in the chain — uniform across all routes
  • • Identity (④ req.auth/scopes) lives on the /mcp route — session/scope-aware
  • • Different layers, no collision: that's why the chain-first + per-session changes compose
  • • bodyParser:false → ② skipped, ⑤ becomes the real parser; /mcp still works

@agentback/rest rest.server.ts:128 (chain mount) · @agentback/mcp-http index.ts:356 (/mcp route) · companion: middleware-chain.html