Stateless MCP Spec: How 2026 Model Context Protocol Enables Scale

flowchart TD
    subgraph Legacy Stateful MCP Workflow
        A1["AI Agent Client"] -- "1. Persistent Session Handshake" --> B1["Sticky Load Balancer"]
        B1 -- "Pinned Session" --> C1["MCP Server Instance 1 (Stateful Node)"]
        A1 -- "2. Tool Call Request" --> B1
        B1 -- "Must Route to Instance 1" --> C1
    end
    
    subgraph Modern 2026 Stateless MCP Workflow
        A2["AI Agent Client"] -- "1. Self-Contained Request + JWT" --> B2["Standard HTTP Load Balancer"]
        B2 -- "Round-Robin / Any Available Node" --> C2["MCP Container Instance A"]
        A2 -- "2. Subsequent Request" --> B2
        B2 -- "Stateless Dispatch" --> C3["MCP Container Instance B"]
    end

sequenceDiagram
    autonumber
    participant Client as AI Agent Client
    participant Gateway as Cloud API Gateway / Load Balancer
    participant Server as Stateless MCP Node
    participant DB as Postgres / Cache

    Client->>Gateway: POST /mcp/v2/tools/execute (Bearer JWT + Payload)
    Gateway->>Server: Route Request to Any Idle Worker Node
    Server->>DB: Fetch Tenant Scope / Verify Permissions
    DB-->>Server: Scope Granted
    Server->>Server: Execute Tool Logic (e.g., query database or API)
    Server-->>Gateway: 200 OK (Structured JSON Result)
    Gateway-->>Client: Return Execution Output to Agent

import express, { Request, Response } from "express";
import { StatelessMcpServer } from "@modelcontextprotocol/sdk/server/stateless";
import { z } from "zod";

const app = express();
app.use(express.json());

// Initialize stateless server core
const mcpServer = new StatelessMcpServer({
  name: "enterprise-customer-tools",
  version: "2.0.0",
});

// Register tool handler with Zod validation
mcpServer.registerTool(
  "get_customer_metrics",
  "Retrieves operational metrics for a specific customer ID",
  {
    customerId: z.string().describe("The unique customer account identifier"),
    timeframeDays: z.number().default(30).describe("Analysis window in days"),
  },
  async ({ customerId, timeframeDays }, context) => {
    // Access tenant claims directly from stateless authorization context
    const tenantId = context.auth?.tenantId;
    
    // Perform database query without relying on server-side session memory
    const metrics = await fetchCustomerMetricsFromDb(tenantId, customerId, timeframeDays);

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(metrics, null, 2),
        },
      ],
    };
  }
);

// Expose standard HTTP POST endpoint
app.post("/mcp/v2/execute", async (req: Request, res: Response) => {
  try {
    const response = await mcpServer.handleHttpRequest(req.body, {
      authHeader: req.headers.authorization,
    });
    res.status(200).json(response);
  } catch (error: any) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(8080, () => {
  console.log("Stateless MCP Server running on port 8080");
});

import os
from fastapi import FastAPI, Header, HTTPException, Request
from mcp.server.fastmcp import FastMCP, Context

# Initialize FastMCP core in stateless mode
mcp = FastMCP("enterprise-financial-tools", stateless=True)

@mcp.tool()
async def get_account_balance(account_id: str, ctx: Context) -> str:
    """Retrieves account balance without keeping in-memory session state."""
    # Extract auth claims attached to request context
    tenant_id = ctx.request_context.get("tenant_id")
    
    # Query database or backend REST microservice
    balance_info = await db_query_balance(tenant_id=tenant_id, account_id=account_id)
    return f"Account {account_id} balance: ${balance_info['amount']} {balance_info['currency']}"

# Bind FastMCP stateless runner to FastAPI web server
app = FastAPI(title="Stateless MCP API Gateway")

@app.post("/mcp/v2/execute")
async def execute_mcp_request(request: Request, authorization: str = Header(None)):
    if not authorization or not authorization.startswith("Bearer "):
        raise HTTPException(status_code=401, detail="Missing or invalid bearer token")
        
    payload = await request.json()
    # Process stateless payload and pass tenant claims
    result = await mcp.handle_stateless_request(payload, auth_token=authorization)
    return result

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-tool-server
  namespace: ai-infrastructure
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mcp-tool-server
  template:
    metadata:
      labels:
        app: mcp-tool-server
    spec:
      containers:
      - name: mcp-node
        image: ghcr.io/enterprise/mcp-tool-server:2.0.0
        ports:
        - containerPort: 8080
        resources:
          limits:
            cpu: "1000m"
            memory: "512Mi"
          requests:
            cpu: "250m"
            memory: "128Mi"
        livenessProbe:
          httpGet:
            path: /healthz
            port: 8080
---
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: mcp-tool-server-hpa
  namespace: ai-infrastructure
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: mcp-tool-server
  minReplicas: 3
  maxReplicas: 25
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"strings"

	"github.com/modelcontextprotocol/sdk-go/mcp"
)

type ToolRequest struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      string          `json:"id"`
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params"`
}

type BalanceParams struct {
	AccountID string `json:"accountId"`
}

func main() {
	// Initialize stateless MCP router
	server := mcp.NewStatelessServer("go-financial-tools", "2.0.0")

	// Register tool handler
	server.RegisterTool("get_account_balance", "Fetch balance in Go", func(ctx mcp.Context, rawParams json.RawMessage) (interface{}, error) {
		var params BalanceParams
		if err := json.Unmarshal(rawParams, &params); err != nil {
			return nil, fmt.Errorf("invalid parameters: %w", err)
		}

		// Retrieve tenant claims attached to stateless context
		tenantID := ctx.Value("tenant_id").(string)
		balance := queryDatabase(tenantID, params.AccountID)

		return map[string]interface{}{
			"accountId": params.AccountID,
			"balance":   balance,
			"status":    "active",
		}, nil
	})

	http.HandleFunc("/mcp/v2/execute", func(w http.ResponseWriter, r *http.Request) {
		if r.Method != http.MethodPost {
			http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
			return
		}

		authHeader := r.Header.Get("Authorization")
		if !strings.HasPrefix(authHeader, "Bearer ") {
			http.Error(w, "Unauthorized", http.StatusUnauthorized)
			return
		}

		// Process request statelessly without pinning thread memory
		var req ToolRequest
		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
			http.Error(w, "Malformed JSON", http.StatusBadRequest)
			return
		}

		resp, err := server.HandleStateless(r.Context(), req.Method, req.Params, authHeader)
		if err != nil {
			http.Error(w, err.Error(), http.StatusInternalServerError)
			return
		}

		w.Header().Set("Content-Type", "application/json")
		json.NewEncoder(w).Encode(resp)
	})

	log.Println("Go Stateless MCP Server listening on :8080")
	log.Fatal(http.ListenAndServe(":8080", nil))
}

func queryDatabase(tenantID, accountID string) float64 {
	return 14502.50 // Simulated DB result
}

POST /mcp/v2/execute HTTP/2
Host: mcp-gateway.enterprise.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
X-MCP-Correlation-ID: req_99482-a72f-4c12-b912

{
  "jsonrpc": "2.0",
  "id": "msg_88192301",
  "method": "tools/call",
  "params": {
    "name": "get_customer_metrics",
    "arguments": {
      "customerId": "cust_99214",
      "timeframeDays": 30
    },
    "_meta": {
      "clientVersion": "2026.8.0",
      "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
    }
  }
}

HTTP/2 200 OK
Content-Type: application/json
X-MCP-Execution-Time-MS: 42

{
  "jsonrpc": "2.0",
  "id": "msg_88192301",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"customerId\": \"cust_99214\",\n  \"activeSubscriptions\": 4,\n  \"mrr\": 12500\n}"
      }
    ],
    "isError": false
  }
}

static_resources:
  listeners:
  - name: mcp_ingress
    address:
      socket_address:
        address: 0.0.0.0
        port_value: 443
    filter_chains:
    - filters:
      - name: envoy.filters.network.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          stat_prefix: mcp_http
          route_config:
            name: mcp_route
            virtual_hosts:
            - name: mcp_services
              domains: ["mcp.enterprise.com"]
              routes:
              - match:
                  prefix: "/mcp/v2/execute"
                route:
                  cluster: mcp_cluster
                  timeout: 15s
                  retry_policy:
                    retry_on: "5xx,connect-failure,reset"
                    num_retries: 3
          http_filters:
          - name: envoy.filters.http.router
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router

  clusters:
  - name: mcp_cluster
    type: STRICT_DNS
    lb_policy: ROUND_ROBIN
    load_assignment:
      cluster_name: mcp_cluster
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: mcp-k8s-service.ai-infrastructure.svc.cluster.local
                port_value: 8080

// Middleware enforcing tool-level scopes
export function enforceMcpToolScope(requiredScope: string) {
  return (req: Request, res: Response, next: NextFunction) => {
    const token = req.headers.authorization?.split(" ")[1];
    if (!token) return res.status(401).json({ error: "Missing bearer token" });

    try {
      const decoded: any = jwt.verify(token, process.env.JWT_SECRET!);
      const userScopes: string[] = decoded.scopes || [];

      if (!userScopes.includes(requiredScope)) {
        return res.status(403).json({
          error: `Insufficient permissions. Tool requires scope: ${requiredScope}`,
        });
      }

      req.tenantContext = { tenantId: decoded.tenantId, userId: decoded.sub };
      next();
    } catch (err) {
      return res.status(401).json({ error: "Invalid or expired authorization token" });
    }
  };
}

// Cloudflare Worker Stateless MCP Handler
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    if (request.method !== "POST") {
      return new Response("Method Not Allowed", { status: 405 });
    }

    const payload = await request.json();
    
    // Execute tool directly on V8 edge isolate
    if (payload.method === "tools/call" && payload.params.name === "calculate_tax_rate") {
      const { zipCode, amount } = payload.params.arguments;
      const taxAmount = amount * 0.0825; // Edge computation

      return new Response(JSON.stringify({
        jsonrpc: "2.0",
        id: payload.id,
        result: {
          content: [{ type: "text", text: `Tax: $${taxAmount.toFixed(2)}` }]
        }
      }), {
        headers: { "Content-Type": "application/json" }
      });
    }

    return new Response("Tool Not Found", { status: 404 });
  }
};

import { trace, context, SpanStatusCode } from "@opentelemetry/api";

const tracer = trace.getTracer("mcp-stateless-tracer", "2.0.0");

export async function traceMcpExecution(reqPayload: any, authHeader: string, handler: Function) {
  const toolName = reqPayload.params?.name || "unknown_tool";
  const correlationId = reqPayload._meta?.traceId || reqPayload.id;

  return tracer.startActiveSpan(`mcp.tool.execute:${toolName}`, async (span) => {
    span.setAttribute("mcp.tool.name", toolName);
    span.setAttribute("mcp.correlation_id", correlationId);
    span.setAttribute("mcp.spec_version", "2026.1");

    try {
      const result = await handler(reqPayload, authHeader);
      span.setStatus({ code: SpanStatusCode.OK });
      return result;
    } catch (error: any) {
      span.setStatus({
        code: SpanStatusCode.ERROR,
        message: error.message,
      });
      span.recordException(error);
      throw error;
    } finally {
      span.end();
    }
  });
}

import Redis from "ioredis";

const redis = new Redis(process.env.REDIS_URL!);

export async function enforceRateLimit(tenantId: string, maxRequestsPerMinute: number = 60): Promise<boolean> {
  const key = `ratelimit:mcp:${tenantId}`;
  const currentTimestamp = Date.now();
  const windowStart = currentTimestamp - 60000;

  // Use Redis multi transaction for atomic sliding window
  const multi = redis.multi();
  multi.zremrangebyscore(key, 0, windowStart);
  multi.zadd(key, currentTimestamp, `${currentTimestamp}:${Math.random()}`);
  multi.zcard(key);
  multi.expire(key, 60);

  const results = await multi.exec();
  const requestCount = results?.[2][1] as number;

  return requestCount <= maxRequestsPerMinute;
}

import { describe, it, expect } from "vitest";
import { handleStatelessRequest } from "../src/mcpHandler";

describe("Stateless MCP Handler - get_customer_metrics", () => {
  it("should return customer metrics when valid Bearer token is provided", async () => {
    const mockPayload = {
      jsonrpc: "2.0",
      id: "test_1",
      method: "tools/call",
      params: {
        name: "get_customer_metrics",
        arguments: { customerId: "cust_123", timeframeDays: 30 }
      }
    };

    const mockAuthHeader = "Bearer valid_test_jwt_token";
    const response = await handleStatelessRequest(mockPayload, mockAuthHeader);

    expect(response.jsonrpc).toBe("2.0");
    expect(response.id).toBe("test_1");
    expect(response.result.isError).toBe(false);
    expect(response.result.content[0].text).toContain("cust_123");
  });

  it("should return 401 Unauthorized when Bearer token is missing", async () => {
    const mockPayload = {
      jsonrpc: "2.0",
      id: "test_2",
      method: "tools/call",
      params: { name: "get_customer_metrics", arguments: { customerId: "cust_123" } }
    };

    await expect(handleStatelessRequest(mockPayload, "")).rejects.toThrow("Unauthorized");
  });
});

import { Context } from "@modelcontextprotocol/sdk/server";

export class TenantIsolationAdapter {
  private tenantId: string;

  constructor(ctx: Context) {
    this.tenantId = ctx.request_context.get("tenant_id");
    if (!this.tenantId) {
      throw new Error("Security Violation: Missing tenant context in stateless execution envelope");
    }
  }

  public getTenantKey(key: string): string {
    return `tenant:${this.tenantId}:mcp:${key}`;
  }
}

import { Response } from "express";

export function initStatelessSseStream(res: Response) {
  res.setHeader("Content-Type", "text/event-stream");
  res.setHeader("Cache-Control", "no-cache");
  res.setHeader("Connection", "keep-alive");
  res.setHeader("X-Accel-Buffering", "no"); // Disable NGINX buffering

  return (chunk: string) => {
    res.write(`data: ${JSON.stringify({ chunk })}\n\n`);
  };
}

{
  "@timestamp": "2026-08-07T14:32:01.482Z",
  "event": {
    "action": "mcp_tool_execution",
    "category": "ai_agent_activity",
    "outcome": "success"
  },
  "mcp": {
    "spec_version": "2026.1",
    "tool_name": "get_customer_metrics",
    "correlation_id": "req_99482-a72f-4c12-b912",
    "execution_time_ms": 42
  },
  "user": {
    "tenant_id": "org_99218",
    "sub": "user_204812"
  },
  "source": {
    "ip": "10.240.12.84",
    "user_agent": "Claude-Desktop/2026.8.0"
  }
}

app.get("/healthz", (req: Request, res: Response) => {
  // Liveness check verifying container process health
  res.status(200).json({ status: "healthy", timestamp: new Date().toISOString() });
});

app.get("/readyz", async (req: Request, res: Response) => {
  // Readiness check verifying backend database connectivity
  const isDbConnected = await checkDbConnection();
  if (isDbConnected) {
    res.status(200).json({ status: "ready", activeTools: 12 });
  } else {
    res.status(503).json({ status: "not_ready", error: "Database unreachable" });
  }
});

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: mcp-tool-route
  namespace: ai-infrastructure
spec:
  parentRefs:
  - name: mcp-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /mcp/v2/execute
    backendRefs:
    - name: mcp-server-v1-stable
      port: 8080
      weight: 90
    - name: mcp-server-v2-canary
      port: 8080
      weight: 10

server {
    listen 443 ssl http2;
    server_name mcp-internal.enterprise.local;

    ssl_certificate /etc/ssl/certs/mcp-server.crt;
    ssl_certificate_key /etc/ssl/private/mcp-server.key;

    # Require client certificate for mTLS authentication
    ssl_client_certificate /etc/ssl/certs/internal-ca.crt;
    ssl_verify_client on;

    location /mcp/v2/execute {
        proxy_pass http://mcp_backend_cluster;
        proxy_set_header X-Client-Cert-DN $ssl_client_s_dn;
        proxy_set_header X-Client-Cert-Verify $ssl_client_verify;
    }
}

import { Request, Response, NextFunction } from "express";
import Redis from "ioredis";

const redis = new Redis(process.env.REDIS_URL!);

export async function deduplicateMcpRequests(req: Request, res: Response, next: NextFunction) {
  const correlationId = req.headers["x-mcp-correlation-id"] as string;
  if (!correlationId) return next(); // Read-only tool calls can skip deduplication

  const lockKey = `mcp:lock:${correlationId}`;
  const isAcquired = await redis.set(lockKey, "processing", "NX", "EX", 30);

  if (!isAcquired) {
    // Request is currently being processed by another pod or was already completed
    const cachedResult = await redis.get(`mcp:result:${correlationId}`);
    if (cachedResult) {
      return res.status(200).json(JSON.parse(cachedResult));
    }
    return res.status(409).json({ error: "Duplicate request currently in progress" });
  }

  next();
}

import { useState, useEffect } from "react";

export function useStatelessMcpToolStream(toolUrl: string, payload: any, token: string) {
  const [output, setOutput] = useState<string>("");
  const [isExecuting, setIsExecuting] = useState<boolean>(false);
  const [error, setError] = useState<string | null>(null);

  const executeTool = async () => {
    setIsExecuting(true);
    setOutput("");
    setError(null);

    try {
      const response = await fetch(toolUrl, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "Authorization": `Bearer ${token}`,
          "Accept": "text/event-stream"
        },
        body: JSON.stringify(payload)
      });

      if (!response.ok) throw new Error(`Tool execution failed: ${response.statusText}`);

      const reader = response.body?.getReader();
      const decoder = new TextDecoder();

      while (reader) {
        const { done, value } = await reader.read();
        if (done) break;

        const chunkText = decoder.decode(value, { stream: true });
        const lines = chunkText.split("\n\n");

        for (const line of lines) {
          if (line.startsWith("data: ")) {
            const data = JSON.parse(line.replace("data: ", ""));
            setOutput((prev) => prev + data.chunk);
          }
        }
      }
    } catch (err: any) {
      setError(err.message);
    } finally {
      setIsExecuting(false);
    }
  };

  return { output, isExecuting, error, executeTool };
}

import { z } from "zod";
import { Request, Response, NextFunction } from "express";

const McpRequestSchema = z.object({
  jsonrpc: z.literal("2.0"),
  id: z.union([z.string(), z.number()]),
  method: z.string().min(1),
  params: z.object({
    name: z.string().regex(/^[a-zA-Z0-9_-]+$/), // Strict tool name pattern
    arguments: z.record(z.unknown()).optional(),
    _meta: z.record(z.unknown()).optional()
  })
});

export function validateMcpPayload(req: Request, res: Response, next: NextFunction) {
  const parseResult = McpRequestSchema.safeParse(req.body);
  if (!parseResult.success) {
    return res.status(400).json({
      jsonrpc: "2.0",
      id: req.body?.id || null,
      error: {
        code: -32600,
        message: "Invalid Request: Schema validation failed",
        data: parseResult.error.flatten()
      }
    });
  }
  next();
}

name: Build & Deploy Stateless MCP Server

on:
  push:
    branches: [ main ]
    tags: [ 'v*.*.*' ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Log in to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build & Push MCP Container Image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: |
            ghcr.io/${{ github.repository }}/mcp-stateless-server:latest
            ghcr.io/${{ github.repository }}/mcp-stateless-server:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: Trigger Kubernetes Rolling Update
        run: |
          echo "Triggering kubectl rollout restart deployment/mcp-tool-server"

// Registering an asynchronous tool task
mcpServer.registerAsyncTask(
  "generate_codebase_index",
  "Builds a vector index for a large repository",
  { repoUrl: z.string().url() },
  async ({ repoUrl }, taskContext) => {
    // Task executes in background job worker (e.g., BullMQ / Celery)
    const jobId = await enqueueIndexJob(repoUrl);
    return { taskId: jobId, status: "pending" };
  }
);