From 04c5cd5809abb992bfbe1cd52f4375676d74bfdc Mon Sep 17 00:00:00 2001
From: Dhruwang Jariwala <67850763+Dhruwang@users.noreply.github.com>
Date: Tue, 2 Jun 2026 20:58:33 +0530
Subject: [PATCH 1/3] refactor(survey-ui): strip inline styles for CSP
 compatibility (#8205)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../survey-ui/src/components/elements/consent.tsx |  4 +---
 .../src/components/elements/file-upload.tsx       | 10 +++-------
 .../src/components/general/element-media.tsx      |  3 +--
 .../survey-ui/src/components/general/input.tsx    |  3 +--
 .../survey-ui/src/components/general/progress.tsx | 15 +++++++++++----
 .../survey-ui/src/components/general/textarea.tsx |  3 +--
 packages/survey-ui/src/styles/globals.css         |  1 +
 7 files changed, 19 insertions(+), 20 deletions(-)

diff --git a/packages/survey-ui/src/components/elements/consent.tsx b/packages/survey-ui/src/components/elements/consent.tsx
index 1bea01499e13..8be73d37323d 100644
--- a/packages/survey-ui/src/components/elements/consent.tsx
+++ b/packages/survey-ui/src/components/elements/consent.tsx
@@ -92,10 +92,8 @@ function Consent({
             disabled={disabled}
             aria-invalid={Boolean(errorMessage)}
           />
-          {/* need to use style here because tailwind is not able to use css variables for font size and weight */}
           <span
-            className="font-input-weight text-input-text flex-1"
-            style={{ fontSize: "var(--fb-input-font-size)" }}
+            className="font-input-weight text-input-text flex-1 [font-size:var(--fb-input-font-size)]"
             dir={dir}>
             {checkboxLabel}
           </span>
diff --git a/packages/survey-ui/src/components/elements/file-upload.tsx b/packages/survey-ui/src/components/elements/file-upload.tsx
index d8b895ddd196..30177ab4eab3 100644
--- a/packages/survey-ui/src/components/elements/file-upload.tsx
+++ b/packages/survey-ui/src/components/elements/file-upload.tsx
@@ -96,8 +96,7 @@ function UploadedFileItem({
       <div className="flex flex-col items-center justify-center p-2">
         <UploadIcon />
         <p
-          style={{ fontSize: "var(--fb-input-font-size)" }}
-          className="mt-1 w-full overflow-hidden px-2 text-center overflow-ellipsis whitespace-nowrap text-[var(--foreground)]"
+          className="mt-1 w-full overflow-hidden px-2 text-center [font-size:var(--fb-input-font-size)] text-ellipsis whitespace-nowrap text-(--foreground)"
           title={file.name}>
           {file.name}
         </p>
@@ -189,8 +188,7 @@ function UploadArea({
         aria-label="Upload files by clicking or dragging them here">
         <Upload className="text-input-text h-6" aria-hidden="true" />
         <span
-          className="text-input-text font-input-weight m-2"
-          style={{ fontSize: "var(--fb-input-font-size)" }}
+          className="text-input-text font-input-weight m-2 [font-size:var(--fb-input-font-size)]"
           id={`${inputId}-label`}>
           {placeholderText}
         </span>
@@ -306,9 +304,7 @@ function FileUpload({
           <div className="w-full">
             {isUploading ? (
               <div className="flex animate-pulse items-center justify-center rounded-lg py-4">
-                <p
-                  className="text-muted-foreground font-medium"
-                  style={{ fontSize: "var(--fb-input-font-size)" }}>
+                <p className="text-muted-foreground [font-size:var(--fb-input-font-size)] font-medium">
                   {uploadingText}
                 </p>
               </div>
diff --git a/packages/survey-ui/src/components/general/element-media.tsx b/packages/survey-ui/src/components/general/element-media.tsx
index 773fdbbb0468..9e7d8bf0df39 100644
--- a/packages/survey-ui/src/components/general/element-media.tsx
+++ b/packages/survey-ui/src/components/general/element-media.tsx
@@ -56,8 +56,7 @@ function ElementMedia({ imgUrl, videoUrl, altText = "Image" }: Readonly<ElementM
             <iframe
               src={videoUrlWithParams}
               title="Question video"
-              style={{ border: 0 }}
-              className={cn("aspect-video w-full rounded-md", isLoading ? "opacity-0" : "")}
+              className={cn("aspect-video w-full rounded-md border-0", isLoading ? "opacity-0" : "")}
               onLoad={() => {
                 setIsLoading(false);
               }}
diff --git a/packages/survey-ui/src/components/general/input.tsx b/packages/survey-ui/src/components/general/input.tsx
index 73f84771c40e..4ebba436751e 100644
--- a/packages/survey-ui/src/components/general/input.tsx
+++ b/packages/survey-ui/src/components/general/input.tsx
@@ -19,7 +19,6 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(function Input(
         type={type}
         dir={dir}
         data-slot="input"
-        style={{ fontSize: "var(--fb-input-font-size)" }}
         className={cn(
           // Layout and behavior
           "flex min-w-0 border transition-[color,box-shadow] outline-none",
@@ -27,7 +26,7 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(function Input(
           "w-input min-h-[var(--fb-input-height)]",
           "bg-input-bg border-input-border rounded-input",
           "font-input font-input-weight",
-          "text-input-text",
+          "text-input-text [font-size:var(--fb-input-font-size)]",
           "px-input-x py-input-y",
           "shadow-input",
           // Placeholder styling
diff --git a/packages/survey-ui/src/components/general/progress.tsx b/packages/survey-ui/src/components/general/progress.tsx
index 8c3280057c2b..17ffd4aec4a8 100644
--- a/packages/survey-ui/src/components/general/progress.tsx
+++ b/packages/survey-ui/src/components/general/progress.tsx
@@ -8,6 +8,15 @@ export interface ProgressProps extends Omit<React.ComponentProps<"div">, "childr
 
 function Progress({ className, value, ...props }: Readonly<ProgressProps>): React.JSX.Element {
   const progressValue: number = typeof value === "number" ? value : 0;
+  const indicatorRef = React.useRef<HTMLDivElement>(null);
+
+  // Setting the translate value via setProperty (CSSOM) rather than the
+  // `style` JSX prop keeps the HTML free of inline `style="..."` attributes,
+  // which the strictest Content Security Policies disallow.
+  React.useLayoutEffect(() => {
+    indicatorRef.current?.style.setProperty("--fb-progress-translate-x", `-${String(100 - progressValue)}%`);
+  }, [progressValue]);
+
   return (
     <ProgressPrimitive.Root
       data-slot="progress"
@@ -15,11 +24,9 @@ function Progress({ className, value, ...props }: Readonly<ProgressProps>): Reac
       className={cn("progress-track relative w-full overflow-hidden", className)}
       {...props}>
       <ProgressPrimitive.Indicator
+        ref={indicatorRef}
         data-slot="progress-indicator"
-        className="progress-indicator h-full w-full flex-1 transition-all"
-        style={{
-          transform: `translateX(-${String(100 - progressValue)}%)`,
-        }}
+        className="progress-indicator h-full w-full flex-1 translate-x-(--fb-progress-translate-x) transition-all"
       />
     </ProgressPrimitive.Root>
   );
diff --git a/packages/survey-ui/src/components/general/textarea.tsx b/packages/survey-ui/src/components/general/textarea.tsx
index 777959d66773..5b98dcfe5389 100644
--- a/packages/survey-ui/src/components/general/textarea.tsx
+++ b/packages/survey-ui/src/components/general/textarea.tsx
@@ -10,10 +10,9 @@ function Textarea({ className, dir = "auto", ...props }: TextareaProps): React.J
     <div className="relative space-y-2">
       <textarea
         data-slot="textarea"
-        style={{ fontSize: "var(--fb-input-font-size)" }}
         dir={dir}
         className={cn(
-          "w-input bg-input-bg border-input-border rounded-input font-input font-input-weight px-input-x py-input-y shadow-input placeholder:text-input-placeholder placeholder:opacity-input-placeholder focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 aria-invalid:border-destructive text-input text-input-text flex field-sizing-content min-h-16 border transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50",
+          "w-input bg-input-bg border-input-border rounded-input font-input font-input-weight px-input-x py-input-y shadow-input placeholder:text-input-placeholder placeholder:opacity-input-placeholder focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 aria-invalid:border-destructive text-input-text flex field-sizing-content min-h-16 border [font-size:var(--fb-input-font-size)] transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50",
           className
         )}
         {...props}
diff --git a/packages/survey-ui/src/styles/globals.css b/packages/survey-ui/src/styles/globals.css
index 36f6bec52bdb..e4c3ef1bf872 100644
--- a/packages/survey-ui/src/styles/globals.css
+++ b/packages/survey-ui/src/styles/globals.css
@@ -213,6 +213,7 @@
 }
 
 #fbjs .progress-indicator {
+  --fb-progress-translate-x: -100%;
   background-color: var(--fb-progress-indicator-bg-color);
   border-radius: var(--fb-progress-indicator-border-radius);
 }

From 86bc4c910a9e50632a1bfd358ff2a2b5e8d6748a Mon Sep 17 00:00:00 2001
From: Bhagya Amarasinghe <b.sithumini@yahoo.com>
Date: Tue, 2 Jun 2026 22:39:10 +0530
Subject: [PATCH 2/3] feat: add MCP v3 surveys server (#8144)

Co-authored-by: Tiago Farto <tiago@formbricks.com>
---
 apps/web/app/api/mcp/route.test.ts            | 221 +++++
 apps/web/app/api/mcp/route.ts                 |  44 +
 apps/web/app/api/v3/lib/api-wrapper.ts        |  46 +-
 apps/web/app/api/v3/lib/audit.ts              |  48 ++
 .../app/api/v3/surveys/[surveyId]/route.ts    | 233 +-----
 .../app/api/v3/surveys/lib/operations.test.ts | 766 ++++++++++++++++++
 apps/web/app/api/v3/surveys/lib/operations.ts | 514 ++++++++++++
 apps/web/app/api/v3/surveys/route.ts          | 161 +---
 .../app/api/v3/surveys/serializers.test.ts    |  39 +
 apps/web/app/api/v3/surveys/serializers.ts    |  45 +-
 apps/web/app/api/v3/surveys/validate/route.ts | 105 +--
 apps/web/modules/mcp/auth.test.ts             | 210 +++++
 apps/web/modules/mcp/auth.ts                  | 209 +++++
 apps/web/modules/mcp/constants.ts             |   3 +
 apps/web/modules/mcp/errors.ts                |  72 ++
 apps/web/modules/mcp/server.ts                |  23 +
 apps/web/modules/mcp/tools/schemas.ts         |  90 ++
 apps/web/modules/mcp/tools/surveys.test.ts    | 430 ++++++++++
 apps/web/modules/mcp/tools/surveys.ts         | 293 +++++++
 apps/web/package.json                         |   8 +-
 .../technical-handbook/mcp-server.mdx         | 512 ++++++++++++
 docs/docs.json                                |   1 +
 pnpm-lock.yaml                                | 450 +++++++++-
 23 files changed, 3994 insertions(+), 529 deletions(-)
 create mode 100644 apps/web/app/api/mcp/route.test.ts
 create mode 100644 apps/web/app/api/mcp/route.ts
 create mode 100644 apps/web/app/api/v3/lib/audit.ts
 create mode 100644 apps/web/app/api/v3/surveys/lib/operations.test.ts
 create mode 100644 apps/web/app/api/v3/surveys/lib/operations.ts
 create mode 100644 apps/web/modules/mcp/auth.test.ts
 create mode 100644 apps/web/modules/mcp/auth.ts
 create mode 100644 apps/web/modules/mcp/constants.ts
 create mode 100644 apps/web/modules/mcp/errors.ts
 create mode 100644 apps/web/modules/mcp/server.ts
 create mode 100644 apps/web/modules/mcp/tools/schemas.ts
 create mode 100644 apps/web/modules/mcp/tools/surveys.test.ts
 create mode 100644 apps/web/modules/mcp/tools/surveys.ts
 create mode 100644 docs/development/technical-handbook/mcp-server.mdx

diff --git a/apps/web/app/api/mcp/route.test.ts b/apps/web/app/api/mcp/route.test.ts
new file mode 100644
index 000000000000..0838b985d80a
--- /dev/null
+++ b/apps/web/app/api/mcp/route.test.ts
@@ -0,0 +1,221 @@
+import { ApiKeyPermission } from "@prisma/client";
+import { NextRequest } from "next/server";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import { successListResponse } from "@/app/api/v3/lib/response";
+import { listV3Surveys } from "@/app/api/v3/surveys/lib/operations";
+import { DEFAULT_REQUEST_BODY_LIMIT_BYTES } from "@/app/lib/api/request-body";
+import { authenticateApiKeyFromHeaders } from "@/modules/api/lib/api-key-auth";
+import { applyRateLimit } from "@/modules/core/rate-limit/helpers";
+import { POST } from "./route";
+
+vi.mock("@/modules/api/lib/api-key-auth", () => ({
+  authenticateApiKeyFromHeaders: vi.fn(),
+}));
+
+vi.mock("@/modules/core/rate-limit/helpers", () => ({
+  applyRateLimit: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("@/app/api/v3/surveys/lib/operations", () => ({
+  createV3SurveyResponse: vi.fn(),
+  deleteV3Survey: vi.fn(),
+  getV3Survey: vi.fn(),
+  listV3Surveys: vi.fn(),
+  patchV3SurveyResponse: vi.fn(),
+  validateV3Survey: vi.fn(),
+}));
+
+vi.mock("@/app/api/v3/lib/audit", () => ({
+  buildV3AuditLog: vi.fn(),
+  queueV3AuditLog: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("@formbricks/logger", () => ({
+  logger: {
+    withContext: vi.fn(() => ({
+      error: vi.fn(),
+      warn: vi.fn(),
+    })),
+  },
+}));
+
+const apiKeyAuth = {
+  type: "apiKey" as const,
+  apiKeyId: "key_1",
+  organizationId: "org_1",
+  organizationAccess: {
+    accessControl: { read: true, write: true },
+  },
+  workspacePermissions: [
+    {
+      workspaceId: "clxx1234567890123456789012",
+      workspaceName: "Workspace",
+      permission: ApiKeyPermission.write,
+    },
+  ],
+};
+
+function createMcpRequest(body: Record<string, unknown>, headers: Record<string, string> = {}): NextRequest {
+  return new NextRequest("http://localhost/api/mcp", {
+    method: "POST",
+    headers: {
+      accept: "application/json, text/event-stream",
+      "content-type": "application/json",
+      "mcp-protocol-version": "2025-06-18",
+      "x-api-key": "fbk_test",
+      ...headers,
+    },
+    body: JSON.stringify(body),
+  });
+}
+
+async function readMcpResponse(response: Response): Promise<Record<string, any>> {
+  const text = await response.text();
+  const dataLine = text
+    .split("\n")
+    .map((line) => line.trim())
+    .find((line) => line.startsWith("data:"));
+
+  return JSON.parse(dataLine ? dataLine.slice("data:".length).trim() : text);
+}
+
+describe("POST /api/mcp", () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    vi.mocked(authenticateApiKeyFromHeaders).mockResolvedValue(apiKeyAuth);
+    vi.mocked(applyRateLimit).mockResolvedValue(undefined);
+    vi.mocked(listV3Surveys).mockResolvedValue(
+      successListResponse([], { limit: 20, nextCursor: null, totalCount: 0 }, { requestId: "req_mcp" })
+    );
+  });
+
+  test("returns 401 before MCP handling when authentication fails", async () => {
+    vi.mocked(authenticateApiKeyFromHeaders).mockResolvedValue(null);
+
+    const response = await POST(
+      createMcpRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/list",
+        params: {},
+      })
+    );
+
+    expect(response.status).toBe(401);
+    expect(response.headers.get("Content-Type")).toBe("application/problem+json");
+  });
+
+  test("returns 413 before MCP handling when content-length exceeds the v3 body limit", async () => {
+    const response = await POST(
+      createMcpRequest(
+        {
+          jsonrpc: "2.0",
+          id: 1,
+          method: "tools/list",
+          params: {},
+        },
+        {
+          "content-length": String(DEFAULT_REQUEST_BODY_LIMIT_BYTES + 1),
+          "x-request-id": "req_large",
+        }
+      )
+    );
+
+    expect(response.status).toBe(413);
+    expect(response.headers.get("X-Request-Id")).toBe("req_large");
+    expect(authenticateApiKeyFromHeaders).not.toHaveBeenCalled();
+  });
+
+  test("lists MCP tools for a valid API key", async () => {
+    const response = await POST(
+      createMcpRequest(
+        {
+          jsonrpc: "2.0",
+          id: 1,
+          method: "tools/list",
+          params: {},
+        },
+        {
+          "x-request-id": "req_tools",
+        }
+      )
+    );
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("X-Request-Id")).toBe("req_tools");
+    const message = await readMcpResponse(response);
+    expect(message.result.tools.map((tool: { name: string }) => tool.name)).toEqual([
+      "list_surveys",
+      "get_survey",
+      "create_survey",
+      "validate_survey",
+      "patch_survey",
+      "delete_survey",
+    ]);
+    expect(message.result.tools.find((tool: { name: string }) => tool.name === "list_surveys")).toMatchObject(
+      {
+        annotations: {
+          readOnlyHint: true,
+          destructiveHint: false,
+          idempotentHint: true,
+        },
+      }
+    );
+    expect(message.result.tools.find((tool: { name: string }) => tool.name === "patch_survey")).toMatchObject(
+      {
+        annotations: {
+          readOnlyHint: false,
+          destructiveHint: true,
+          idempotentHint: false,
+        },
+      }
+    );
+    expect(
+      message.result.tools.find((tool: { name: string }) => tool.name === "delete_survey")
+    ).toMatchObject({
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+      },
+    });
+  });
+
+  test("calls list_surveys through the MCP route", async () => {
+    const response = await POST(
+      createMcpRequest(
+        {
+          jsonrpc: "2.0",
+          id: 2,
+          method: "tools/call",
+          params: {
+            name: "list_surveys",
+            arguments: {
+              workspaceId: "clxx1234567890123456789012",
+              limit: 20,
+              includeTotalCount: true,
+            },
+          },
+        },
+        {
+          "x-request-id": "req_mcp",
+        }
+      )
+    );
+
+    expect(response.status).toBe(200);
+    const message = await readMcpResponse(response);
+    expect(message.result.structuredContent).toEqual({
+      data: [],
+      meta: { limit: 20, nextCursor: null, totalCount: 0 },
+      requestId: "req_mcp",
+    });
+    expect(listV3Surveys).toHaveBeenCalledWith(
+      expect.objectContaining({
+        authentication: apiKeyAuth,
+        requestId: "req_mcp",
+        instance: "/api/mcp",
+      })
+    );
+  });
+});
diff --git a/apps/web/app/api/mcp/route.ts b/apps/web/app/api/mcp/route.ts
new file mode 100644
index 000000000000..d04faee9f2e5
--- /dev/null
+++ b/apps/web/app/api/mcp/route.ts
@@ -0,0 +1,44 @@
+import { type NextRequest } from "next/server";
+import { DEFAULT_REQUEST_BODY_LIMIT_BYTES } from "@/app/lib/api/request-body";
+import { problemPayloadTooLarge } from "@/app/api/v3/lib/response";
+import { handleAuthenticatedMcpRequest } from "@/modules/mcp/auth";
+import { mcpHandler } from "@/modules/mcp/server";
+
+export const runtime = "nodejs";
+export const fetchCache = "force-no-store";
+
+function getRequestId(request: NextRequest): string {
+  return request.headers.get("x-request-id") ?? crypto.randomUUID();
+}
+
+function getContentLength(headers: Headers): number | null {
+  const contentLength = headers.get("content-length");
+  if (!contentLength) {
+    return null;
+  }
+
+  const parsedContentLength = Number(contentLength);
+  return Number.isSafeInteger(parsedContentLength) && parsedContentLength >= 0 ? parsedContentLength : null;
+}
+
+function validateMcpBodySize(request: NextRequest): Response | null {
+  const contentLength = getContentLength(request.headers);
+  if (contentLength === null || contentLength <= DEFAULT_REQUEST_BODY_LIMIT_BYTES) {
+    return null;
+  }
+
+  return problemPayloadTooLarge(
+    getRequestId(request),
+    `Request body must not exceed ${DEFAULT_REQUEST_BODY_LIMIT_BYTES} bytes`,
+    request.nextUrl.pathname
+  );
+}
+
+export async function POST(request: NextRequest): Promise<Response> {
+  const bodySizeResponse = validateMcpBodySize(request);
+  if (bodySizeResponse) {
+    return bodySizeResponse;
+  }
+
+  return await handleAuthenticatedMcpRequest(request, mcpHandler);
+}
diff --git a/apps/web/app/api/v3/lib/api-wrapper.ts b/apps/web/app/api/v3/lib/api-wrapper.ts
index 18c07787afe4..96c75f6af012 100644
--- a/apps/web/app/api/v3/lib/api-wrapper.ts
+++ b/apps/web/app/api/v3/lib/api-wrapper.ts
@@ -5,14 +5,13 @@ import { logger } from "@formbricks/logger";
 import { TooManyRequestsError } from "@formbricks/types/errors";
 import { authenticateRequest } from "@/app/api/v1/auth";
 import { RequestBodyTooLargeError, parseJsonBodyWithLimit } from "@/app/lib/api/request-body";
-import { buildAuditLogBaseObject } from "@/app/lib/api/with-api-logging";
 import { getApiKeyFromHeaders } from "@/modules/api/lib/api-key-auth";
 import { authOptions } from "@/modules/auth/lib/authOptions";
 import { applyRateLimit } from "@/modules/core/rate-limit/helpers";
 import { rateLimitConfigs } from "@/modules/core/rate-limit/rate-limit-configs";
 import type { TRateLimitConfig } from "@/modules/core/rate-limit/types/rate-limit";
-import { queueAuditEvent } from "@/modules/ee/audit-logs/lib/handler";
 import { TAuditAction, TAuditTarget } from "@/modules/ee/audit-logs/types/audit-log";
+import { buildV3AuditLog, queueV3AuditLog } from "./audit";
 import {
   type InvalidParam,
   isInvalidParamCode,
@@ -334,49 +333,6 @@ async function applyV3RateLimitOrRespond(params: {
   return null;
 }
 
-function buildV3AuditLog(
-  authentication: TV3Authentication,
-  action?: TAuditAction,
-  targetType?: TAuditTarget,
-  apiUrl?: string
-): TV3AuditLog | undefined {
-  if (!authentication || !action || !targetType || !apiUrl) {
-    return undefined;
-  }
-
-  const auditLog = buildAuditLogBaseObject(action, targetType, apiUrl);
-
-  if ("user" in authentication && authentication.user?.id) {
-    auditLog.userId = authentication.user.id;
-    auditLog.userType = "user";
-  } else if ("apiKeyId" in authentication) {
-    auditLog.userId = authentication.apiKeyId;
-    auditLog.userType = "api";
-    auditLog.organizationId = authentication.organizationId;
-  }
-
-  return auditLog;
-}
-
-async function queueV3AuditLog(
-  auditLog: TV3AuditLog | undefined,
-  requestId: string,
-  log: ReturnType<typeof logger.withContext>
-): Promise<void> {
-  if (!auditLog) {
-    return;
-  }
-
-  try {
-    await queueAuditEvent({
-      ...auditLog,
-      ...(auditLog.status === "failure" ? { eventId: auditLog.eventId ?? requestId } : {}),
-    });
-  } catch (error) {
-    log.error({ error }, "Failed to queue V3 audit event");
-  }
-}
-
 export const withV3ApiWrapper = <S extends TV3Schemas | undefined, TProps = unknown>(
   params: TWithV3ApiWrapperParams<S, TProps>
 ): ((req: NextRequest, props: TProps) => Promise<Response>) => {
diff --git a/apps/web/app/api/v3/lib/audit.ts b/apps/web/app/api/v3/lib/audit.ts
new file mode 100644
index 000000000000..6a917032b3c2
--- /dev/null
+++ b/apps/web/app/api/v3/lib/audit.ts
@@ -0,0 +1,48 @@
+import { logger } from "@formbricks/logger";
+import { buildAuditLogBaseObject } from "@/app/lib/api/with-api-logging";
+import { queueAuditEvent } from "@/modules/ee/audit-logs/lib/handler";
+import { TAuditAction, TAuditTarget } from "@/modules/ee/audit-logs/types/audit-log";
+import type { TV3AuditLog, TV3Authentication } from "./types";
+
+export function buildV3AuditLog(
+  authentication: TV3Authentication,
+  action?: TAuditAction,
+  targetType?: TAuditTarget,
+  apiUrl?: string
+): TV3AuditLog | undefined {
+  if (!authentication || !action || !targetType || !apiUrl) {
+    return undefined;
+  }
+
+  const auditLog = buildAuditLogBaseObject(action, targetType, apiUrl);
+
+  if ("user" in authentication && authentication.user?.id) {
+    auditLog.userId = authentication.user.id;
+    auditLog.userType = "user";
+  } else if ("apiKeyId" in authentication) {
+    auditLog.userId = authentication.apiKeyId;
+    auditLog.userType = "api";
+    auditLog.organizationId = authentication.organizationId;
+  }
+
+  return auditLog;
+}
+
+export async function queueV3AuditLog(
+  auditLog: TV3AuditLog | undefined,
+  requestId: string,
+  log: ReturnType<typeof logger.withContext>
+): Promise<void> {
+  if (!auditLog) {
+    return;
+  }
+
+  try {
+    await queueAuditEvent({
+      ...auditLog,
+      ...(auditLog.status === "failure" ? { eventId: auditLog.eventId ?? requestId } : {}),
+    });
+  } catch (error) {
+    log.error({ error }, "Failed to queue V3 audit event");
+  }
+}
diff --git a/apps/web/app/api/v3/surveys/[surveyId]/route.ts b/apps/web/app/api/v3/surveys/[surveyId]/route.ts
index 2bc8cf1869e8..bb3317e27c76 100644
--- a/apps/web/app/api/v3/surveys/[surveyId]/route.ts
+++ b/apps/web/app/api/v3/surveys/[surveyId]/route.ts
@@ -1,26 +1,8 @@
 import { z } from "zod";
-import { logger } from "@formbricks/logger";
-import { DatabaseError, ResourceNotFoundError } from "@formbricks/types/errors";
 import { withV3ApiWrapper } from "@/app/api/v3/lib/api-wrapper";
-import {
-  noContentResponse,
-  problemBadRequest,
-  problemForbidden,
-  problemInternalError,
-  successResponse,
-} from "@/app/api/v3/lib/response";
-import {
-  V3SurveyLanguageError,
-  V3SurveyUnsupportedShapeError,
-  serializeV3SurveyResource,
-} from "@/app/api/v3/surveys/serializers";
-import { deleteSurvey } from "@/modules/survey/lib/surveys";
-import { getAuthorizedV3Survey } from "../authorization";
+import { deleteV3Survey, getV3Survey, patchV3SurveyResponse } from "../lib/operations";
 import { parseV3SurveyLanguageQuery } from "../language";
-import { patchV3Survey } from "../patch";
-import { V3SurveyReferenceValidationError } from "../reference-validation";
 import { ZV3EmptyQuery } from "../schemas";
-import { V3SurveyWritePermissionError } from "../write-permissions";
 
 const surveyParamsSchema = z.object({
   surveyId: z.cuid2(),
@@ -54,70 +36,13 @@ export const GET = withV3ApiWrapper({
     query: surveyQuerySchema,
   },
   handler: async ({ parsedInput, authentication, requestId, instance }) => {
-    const surveyId = parsedInput.params.surveyId;
-    const log = logger.withContext({ requestId, surveyId });
-
-    try {
-      const { survey, response } = await getAuthorizedV3Survey({
-        surveyId,
-        authentication,
-        access: "read",
-        requestId,
-        instance,
-      });
-
-      if (response) {
-        log.warn({ statusCode: response.status }, "Survey not found or not accessible");
-        return response;
-      }
-
-      try {
-        return successResponse(serializeV3SurveyResource(survey, { lang: parsedInput.query.lang }), {
-          requestId,
-          cache: "private, no-store",
-        });
-      } catch (error) {
-        if (error instanceof V3SurveyLanguageError) {
-          log.warn(
-            { statusCode: 400, detail: error.message, lang: parsedInput.query.lang },
-            "Invalid survey language selector"
-          );
-          return problemBadRequest(requestId, error.message, {
-            instance,
-            invalid_params: [
-              {
-                name: "lang",
-                reason: error.message,
-                ...(error.normalizedCode && { identifier: error.normalizedCode }),
-              },
-            ],
-          });
-        }
-
-        if (error instanceof V3SurveyUnsupportedShapeError) {
-          log.warn({ statusCode: 400, detail: error.message }, "Unsupported v3 survey shape");
-          return problemBadRequest(requestId, error.message, {
-            instance,
-            invalid_params: [
-              {
-                name: "survey",
-                reason: error.message,
-              },
-            ],
-          });
-        }
-
-        throw error;
-      }
-    } catch (error) {
-      if (error instanceof DatabaseError) {
-        log.error({ error, statusCode: 500 }, "Database error");
-        return problemInternalError(requestId, "An unexpected error occurred.", instance);
-      }
-
-      log.error({ error, statusCode: 500 }, "V3 survey get unexpected error");
-      return problemInternalError(requestId, "An unexpected error occurred.", instance);
-    }
+    return await getV3Survey({
+      surveyId: parsedInput.params.surveyId,
+      lang: parsedInput.query.lang,
+      authentication,
+      requestId,
+      instance,
+    });
   },
 });
 
@@ -131,93 +56,14 @@ export const PATCH = withV3ApiWrapper({
     body: z.unknown(),
   },
   handler: async ({ parsedInput, authentication, requestId, instance, auditLog }) => {
-    const surveyId = parsedInput.params.surveyId;
-    const log = logger.withContext({ requestId, surveyId });
-    let workspaceId: string | undefined;
-
-    try {
-      const { survey, authResult, response } = await getAuthorizedV3Survey({
-        surveyId,
-        authentication,
-        access: "readWrite",
-        requestId,
-        instance,
-      });
-
-      if (response) {
-        log.warn({ statusCode: response.status }, "Survey not found or not accessible");
-        return response;
-      }
-
-      workspaceId = survey.workspaceId;
-      const updatedSurvey = await patchV3Survey(
-        survey,
-        parsedInput.body,
-        requestId,
-        authResult.organizationId
-      );
-      const resource = serializeV3SurveyResource(updatedSurvey);
-
-      if (auditLog) {
-        auditLog.targetId = updatedSurvey.id;
-        auditLog.organizationId = authResult.organizationId;
-        auditLog.oldObject = serializeV3SurveyResource(survey);
-        auditLog.newObject = resource;
-      }
-
-      return successResponse(resource, {
-        requestId,
-        cache: "private, no-store",
-      });
-    } catch (error) {
-      if (error instanceof V3SurveyReferenceValidationError) {
-        log.warn(
-          { statusCode: 400, workspaceId, invalidParamCount: error.invalidParams.length },
-          "Survey document validation failed"
-        );
-        return problemBadRequest(requestId, "Invalid survey document", {
-          invalid_params: error.invalidParams,
-          instance,
-        });
-      }
-
-      if (error instanceof V3SurveyUnsupportedShapeError) {
-        log.warn({ statusCode: 400, workspaceId, errorCode: error.name }, "Unsupported v3 survey shape");
-        return problemBadRequest(requestId, error.message, {
-          instance,
-          invalid_params: [
-            {
-              name: "survey",
-              reason: error.message,
-            },
-          ],
-        });
-      }
-
-      if (error instanceof V3SurveyWritePermissionError) {
-        log.warn(
-          { statusCode: 403, workspaceId, errorCode: error.name },
-          "Survey patch permission check failed"
-        );
-        return problemForbidden(requestId, error.message, instance);
-      }
-
-      if (error instanceof ResourceNotFoundError) {
-        log.warn(
-          { errorCode: error.name, workspaceId, statusCode: 403 },
-          "Survey not found or not accessible"
-        );
-        return problemForbidden(requestId, "You are not authorized to access this resource", instance);
-      }
-
-      if (error instanceof DatabaseError) {
-        log.error({ error, workspaceId, statusCode: 500 }, "Database error");
-        return problemInternalError(requestId, "An unexpected error occurred.", instance);
-      }
-
-      log.error({ error, workspaceId, statusCode: 500 }, "V3 survey patch unexpected error");
-      return problemInternalError(requestId, "An unexpected error occurred.", instance);
-    }
+    return await patchV3SurveyResponse({
+      surveyId: parsedInput.params.surveyId,
+      body: parsedInput.body,
+      authentication,
+      requestId,
+      instance,
+      auditLog,
+    });
   },
 });
 
@@ -229,45 +75,12 @@ export const DELETE = withV3ApiWrapper({
     params: surveyParamsSchema,
   },
   handler: async ({ parsedInput, authentication, requestId, instance, auditLog }) => {
-    const surveyId = parsedInput.params.surveyId;
-    const log = logger.withContext({ requestId, surveyId });
-
-    try {
-      const { survey, authResult, response } = await getAuthorizedV3Survey({
-        surveyId,
-        authentication,
-        access: "readWrite",
-        requestId,
-        instance,
-      });
-
-      if (response) {
-        log.warn({ statusCode: 403 }, "Survey not found or not accessible");
-        return response;
-      }
-
-      if (auditLog) {
-        auditLog.targetId = survey.id;
-        auditLog.organizationId = authResult.organizationId;
-        auditLog.oldObject = survey;
-      }
-
-      await deleteSurvey(surveyId);
-
-      return noContentResponse({ requestId });
-    } catch (error) {
-      if (error instanceof ResourceNotFoundError) {
-        log.warn({ errorCode: error.name, statusCode: 403 }, "Survey not found or not accessible");
-        return problemForbidden(requestId, "You are not authorized to access this resource", instance);
-      }
-
-      if (error instanceof DatabaseError) {
-        log.error({ error, statusCode: 500 }, "Database error");
-        return problemInternalError(requestId, "An unexpected error occurred.", instance);
-      }
-
-      log.error({ error, statusCode: 500 }, "V3 survey delete unexpected error");
-      return problemInternalError(requestId, "An unexpected error occurred.", instance);
-    }
+    return await deleteV3Survey({
+      surveyId: parsedInput.params.surveyId,
+      authentication,
+      requestId,
+      instance,
+      auditLog,
+    });
   },
 });
diff --git a/apps/web/app/api/v3/surveys/lib/operations.test.ts b/apps/web/app/api/v3/surveys/lib/operations.test.ts
new file mode 100644
index 000000000000..a5df3dc9693b
--- /dev/null
+++ b/apps/web/app/api/v3/surveys/lib/operations.test.ts
@@ -0,0 +1,766 @@
+import { describe, expect, test, vi, beforeEach } from "vitest";
+import { DatabaseError, ResourceNotFoundError } from "@formbricks/types/errors";
+import { problemForbidden } from "@/app/api/v3/lib/response";
+import { requireV3WorkspaceAccess } from "@/app/api/v3/lib/auth";
+import { deleteSurvey } from "@/modules/survey/lib/surveys";
+import { getSurveyCount } from "@/modules/survey/list/lib/survey";
+import { getSurveyListPage } from "@/modules/survey/list/lib/survey-page";
+import { getAuthorizedV3Survey } from "../authorization";
+import { V3SurveyCreatePermissionError, createV3Survey } from "../create";
+import { parseV3SurveysListQuery } from "../parse-v3-surveys-list-query";
+import { patchV3Survey } from "../patch";
+import { prepareV3SurveyCreateInput, prepareV3SurveyPatchInput } from "../prepare";
+import { V3SurveyReferenceValidationError } from "../reference-validation";
+import {
+  V3SurveyLanguageError,
+  V3SurveyUnsupportedShapeError,
+  serializeV3SurveyListItem,
+  serializeV3SurveyResource,
+} from "../serializers";
+import {
+  createV3SurveyResponse,
+  deleteV3Survey,
+  getV3Survey,
+  listV3Surveys,
+  patchV3SurveyResponse,
+  validateV3Survey,
+} from "./operations";
+import { V3SurveyWritePermissionError } from "../write-permissions";
+
+vi.mock("@formbricks/logger", () => ({
+  logger: {
+    withContext: vi.fn(() => ({
+      warn: vi.fn(),
+      error: vi.fn(),
+    })),
+  },
+}));
+
+vi.mock("@/app/api/v3/lib/auth", () => ({
+  requireV3WorkspaceAccess: vi.fn(),
+}));
+
+vi.mock("@/modules/survey/lib/surveys", () => ({
+  deleteSurvey: vi.fn(),
+}));
+
+vi.mock("@/modules/survey/list/lib/survey", () => ({
+  getSurveyCount: vi.fn(),
+}));
+
+vi.mock("@/modules/survey/list/lib/survey-page", () => ({
+  getSurveyListPage: vi.fn(),
+}));
+
+vi.mock("../authorization", () => ({
+  getAuthorizedV3Survey: vi.fn(),
+}));
+
+vi.mock("../create", async () => {
+  const actual = await vi.importActual<typeof import("../create")>("../create");
+  return {
+    ...actual,
+    createV3Survey: vi.fn(),
+  };
+});
+
+vi.mock("../parse-v3-surveys-list-query", () => ({
+  parseV3SurveysListQuery: vi.fn(),
+}));
+
+vi.mock("../patch", () => ({
+  patchV3Survey: vi.fn(),
+}));
+
+vi.mock("../prepare", () => ({
+  prepareV3SurveyCreateInput: vi.fn(),
+  prepareV3SurveyPatchInput: vi.fn(),
+}));
+
+vi.mock("../serializers", async () => {
+  const actual = await vi.importActual<typeof import("../serializers")>("../serializers");
+  return {
+    ...actual,
+    serializeV3SurveyListItem: vi.fn(),
+    serializeV3SurveyResource: vi.fn(),
+  };
+});
+
+const workspaceId = "tz4a98xxat96iws9zmbrgj3a";
+const requestId = "req_123";
+const instance = "/api/v3/surveys";
+const authentication = { type: "apiKey", apiKey: { id: "api_key_1" } } as any;
+const authResult = { workspaceId, organizationId: "org_1" };
+const survey = {
+  id: "survey_1",
+  workspaceId,
+  name: "Customer Survey",
+  status: "draft",
+};
+const serializedSurvey = {
+  id: "survey_1",
+  name: "Customer Survey",
+};
+const updatedSurvey = {
+  ...survey,
+  name: "Updated Survey",
+};
+const serializedUpdatedSurvey = {
+  id: "survey_1",
+  name: "Updated Survey",
+};
+const createBody = {
+  workspaceId,
+  name: "Customer Survey",
+  status: "draft",
+  metadata: {},
+  welcomeCard: { enabled: false },
+  blocks: [],
+  endings: [],
+  hiddenFields: { enabled: false, fieldIds: [] },
+  variables: [],
+} as any;
+
+function mockListQuery(overrides: Record<string, unknown> = {}) {
+  vi.mocked(parseV3SurveysListQuery).mockReturnValue({
+    ok: true,
+    workspaceId,
+    limit: 20,
+    cursor: null,
+    sortBy: undefined,
+    filterCriteria: {},
+    includeTotalCount: true,
+    ...overrides,
+  } as any);
+}
+
+async function readJson(response: Response) {
+  return response.json();
+}
+
+describe("listV3Surveys", () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    mockListQuery();
+    vi.mocked(requireV3WorkspaceAccess).mockResolvedValue(authResult);
+    vi.mocked(getSurveyListPage).mockResolvedValue({ surveys: [survey], nextCursor: "cursor_next" } as any);
+    vi.mocked(getSurveyCount).mockResolvedValue(7);
+    vi.mocked(serializeV3SurveyListItem).mockReturnValue(serializedSurvey as any);
+  });
+
+  test("returns a serialized paginated survey list", async () => {
+    const response = await listV3Surveys({
+      searchParams: new URLSearchParams({ workspaceId }),
+      authentication,
+      requestId,
+      instance,
+    });
+
+    expect(response.status).toBe(200);
+    expect(vi.mocked(requireV3WorkspaceAccess)).toHaveBeenCalledWith(
+      authentication,
+      workspaceId,
+      "read",
+      requestId,
+      instance
+    );
+    expect(vi.mocked(getSurveyListPage)).toHaveBeenCalledWith(workspaceId, {
+      limit: 20,
+      cursor: null,
+      sortBy: undefined,
+      filterCriteria: {},
+    });
+    expect(await readJson(response)).toEqual({
+      data: [serializedSurvey],
+      meta: { limit: 20, nextCursor: "cursor_next", totalCount: 7 },
+    });
+  });
+
+  test("skips total count when it is not requested", async () => {
+    mockListQuery({ includeTotalCount: false });
+
+    const response = await listV3Surveys({
+      searchParams: new URLSearchParams({ workspaceId }),
+      authentication,
+      requestId,
+      instance,
+    });
+
+    expect(response.status).toBe(200);
+    expect(vi.mocked(getSurveyCount)).not.toHaveBeenCalled();
+    expect((await readJson(response)).meta.totalCount).toBeNull();
+  });
+
+  test("returns bad request for invalid query parameters", async () => {
+    vi.mocked(parseV3SurveysListQuery).mockReturnValue({
+      ok: false,
+      invalid_params: [{ name: "workspaceId", reason: "Required" }],
+    } as any);
+
+    const response = await listV3Surveys({
+      searchParams: new URLSearchParams(),
+      authentication,
+      requestId,
+      instance,
+    });
+
+    expect(response.status).toBe(400);
+    expect((await readJson(response)).invalid_params).toEqual([
+      { name: "workspaceId", reason: "Required" },
+    ]);
+  });
+
+  test("returns authorization responses from workspace access", async () => {
+    vi.mocked(requireV3WorkspaceAccess).mockResolvedValue(problemForbidden(requestId, "nope", instance));
+
+    const response = await listV3Surveys({
+      searchParams: new URLSearchParams({ workspaceId }),
+      authentication,
+      requestId,
+      instance,
+    });
+
+    expect(response.status).toBe(403);
+    expect(vi.mocked(getSurveyListPage)).not.toHaveBeenCalled();
+  });
+
+  test("maps resource and database failures to v3 problem responses", async () => {
+    vi.mocked(getSurveyListPage).mockRejectedValueOnce(new ResourceNotFoundError("Workspace", workspaceId));
+
+    const forbidden = await listV3Surveys({
+      searchParams: new URLSearchParams({ workspaceId }),
+      authentication,
+      requestId,
+      instance,
+    });
+    expect(forbidden.status).toBe(403);
+
+    vi.mocked(getSurveyListPage).mockRejectedValueOnce(new DatabaseError("db down"));
+    const internal = await listV3Surveys({
+      searchParams: new URLSearchParams({ workspaceId }),
+      authentication,
+      requestId,
+      instance,
+    });
+    expect(internal.status).toBe(500);
+  });
+});
+
+describe("createV3SurveyResponse", () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    vi.mocked(requireV3WorkspaceAccess).mockResolvedValue(authResult);
+    vi.mocked(createV3Survey).mockResolvedValue(survey as any);
+    vi.mocked(serializeV3SurveyResource).mockReturnValue(serializedSurvey as any);
+  });
+
+  test("creates a survey, serializes it, and enriches the audit log", async () => {
+    const auditLog = {} as any;
+
+    const response = await createV3SurveyResponse({
+      body: createBody,
+      authentication,
+      requestId,
+      instance,
+      auditLog,
+    });
+
+    expect(response.status).toBe(201);
+    expect(response.headers.get("Location")).toBe("/api/v3/surveys/survey_1");
+    expect(vi.mocked(createV3Survey)).toHaveBeenCalledWith(
+      { ...createBody, workspaceId },
+      authentication,
+      requestId,
+      "org_1"
+    );
+    expect(auditLog).toMatchObject({
+      organizationId: "org_1",
+      targetId: "survey_1",
+      newObject: serializedSurvey,
+    });
+    expect(await readJson(response)).toEqual({ data: serializedSurvey });
+  });
+
+  test("returns authorization responses from workspace access", async () => {
+    vi.mocked(requireV3WorkspaceAccess).mockResolvedValue(problemForbidden(requestId, "nope", instance));
+
+    const response = await createV3SurveyResponse({
+      body: createBody,
+      authentication,
+      requestId,
+      instance,
+    });
+
+    expect(response.status).toBe(403);
+    expect(vi.mocked(createV3Survey)).not.toHaveBeenCalled();
+  });
+
+  test("maps validation, shape, permission, missing resource, and database errors", async () => {
+    vi.mocked(createV3Survey).mockRejectedValueOnce(
+      new V3SurveyReferenceValidationError([{ name: "blocks.0", reason: "Unknown element" }])
+    );
+    expect(
+      (
+        await createV3SurveyResponse({
+          body: createBody,
+          authentication,
+          requestId,
+          instance,
+        })
+      ).status
+    ).toBe(400);
+
+    vi.mocked(createV3Survey).mockRejectedValueOnce(new V3SurveyUnsupportedShapeError("Unsupported"));
+    expect(
+      (
+        await createV3SurveyResponse({
+          body: createBody,
+          authentication,
+          requestId,
+          instance,
+        })
+      ).status
+    ).toBe(400);
+
+    vi.mocked(createV3Survey).mockRejectedValueOnce(new V3SurveyCreatePermissionError("No external URLs"));
+    expect(
+      (
+        await createV3SurveyResponse({
+          body: createBody,
+          authentication,
+          requestId,
+          instance,
+        })
+      ).status
+    ).toBe(403);
+
+    vi.mocked(createV3Survey).mockRejectedValueOnce(new ResourceNotFoundError("Workspace", workspaceId));
+    expect(
+      (
+        await createV3SurveyResponse({
+          body: createBody,
+          authentication,
+          requestId,
+          instance,
+        })
+      ).status
+    ).toBe(403);
+
+    vi.mocked(createV3Survey).mockRejectedValueOnce(new DatabaseError("db down"));
+    expect(
+      (
+        await createV3SurveyResponse({
+          body: createBody,
+          authentication,
+          requestId,
+          instance,
+        })
+      ).status
+    ).toBe(500);
+  });
+});
+
+describe("getV3Survey", () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    vi.mocked(getAuthorizedV3Survey).mockResolvedValue({ survey, authResult, response: null } as any);
+    vi.mocked(serializeV3SurveyResource).mockReturnValue(serializedSurvey as any);
+  });
+
+  test("returns a serialized survey resource with language selection", async () => {
+    const response = await getV3Survey({
+      surveyId: "survey_1",
+      lang: ["en-US"],
+      authentication,
+      requestId,
+      instance,
+    });
+
+    expect(response.status).toBe(200);
+    expect(vi.mocked(getAuthorizedV3Survey)).toHaveBeenCalledWith({
+      surveyId: "survey_1",
+      authentication,
+      access: "read",
+      requestId,
+      instance,
+    });
+    expect(vi.mocked(serializeV3SurveyResource)).toHaveBeenCalledWith(survey, { lang: ["en-US"] });
+    expect(await readJson(response)).toEqual({ data: serializedSurvey });
+  });
+
+  test("returns authorization responses from survey access", async () => {
+    vi.mocked(getAuthorizedV3Survey).mockResolvedValue({
+      survey: null,
+      authResult: null,
+      response: problemForbidden(requestId, "nope", instance),
+    } as any);
+
+    const response = await getV3Survey({
+      surveyId: "survey_1",
+      authentication,
+      requestId,
+      instance,
+    });
+
+    expect(response.status).toBe(403);
+  });
+
+  test("maps serializer language and shape errors to bad requests", async () => {
+    vi.mocked(serializeV3SurveyResource).mockImplementationOnce(() => {
+      throw new V3SurveyLanguageError("Unknown language", "xx-YY");
+    });
+    const languageResponse = await getV3Survey({
+      surveyId: "survey_1",
+      lang: ["xx-YY"],
+      authentication,
+      requestId,
+      instance,
+    });
+    expect(languageResponse.status).toBe(400);
+    expect((await readJson(languageResponse)).invalid_params[0]).toMatchObject({
+      name: "lang",
+      identifier: "xx-YY",
+    });
+
+    vi.mocked(serializeV3SurveyResource).mockImplementationOnce(() => {
+      throw new V3SurveyUnsupportedShapeError("Unsupported shape");
+    });
+    const shapeResponse = await getV3Survey({
+      surveyId: "survey_1",
+      authentication,
+      requestId,
+      instance,
+    });
+    expect(shapeResponse.status).toBe(400);
+  });
+
+  test("maps database errors from survey access", async () => {
+    vi.mocked(getAuthorizedV3Survey).mockRejectedValue(new DatabaseError("db down"));
+
+    const response = await getV3Survey({
+      surveyId: "survey_1",
+      authentication,
+      requestId,
+      instance,
+    });
+
+    expect(response.status).toBe(500);
+  });
+});
+
+describe("deleteV3Survey", () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    vi.mocked(getAuthorizedV3Survey).mockResolvedValue({ survey, authResult, response: null } as any);
+    vi.mocked(deleteSurvey).mockResolvedValue(undefined);
+  });
+
+  test("deletes an authorized survey and enriches the audit log", async () => {
+    const auditLog = {} as any;
+
+    const response = await deleteV3Survey({
+      surveyId: "survey_1",
+      authentication,
+      requestId,
+      instance,
+      auditLog,
+    });
+
+    expect(response.status).toBe(204);
+    expect(vi.mocked(deleteSurvey)).toHaveBeenCalledWith("survey_1");
+    expect(auditLog).toMatchObject({
+      organizationId: "org_1",
+      targetId: "survey_1",
+      oldObject: survey,
+    });
+  });
+
+  test("returns authorization responses from survey access", async () => {
+    vi.mocked(getAuthorizedV3Survey).mockResolvedValue({
+      survey: null,
+      authResult: null,
+      response: problemForbidden(requestId, "nope", instance),
+    } as any);
+
+    const response = await deleteV3Survey({
+      surveyId: "survey_1",
+      authentication,
+      requestId,
+      instance,
+    });
+
+    expect(response.status).toBe(403);
+    expect(vi.mocked(deleteSurvey)).not.toHaveBeenCalled();
+  });
+
+  test("maps missing resource and database delete failures", async () => {
+    vi.mocked(deleteSurvey).mockRejectedValueOnce(new ResourceNotFoundError("Survey", "survey_1"));
+    expect(
+      (
+        await deleteV3Survey({
+          surveyId: "survey_1",
+          authentication,
+          requestId,
+          instance,
+        })
+      ).status
+    ).toBe(403);
+
+    vi.mocked(deleteSurvey).mockRejectedValueOnce(new DatabaseError("db down"));
+    expect(
+      (
+        await deleteV3Survey({
+          surveyId: "survey_1",
+          authentication,
+          requestId,
+          instance,
+        })
+      ).status
+    ).toBe(500);
+  });
+});
+
+describe("patchV3SurveyResponse", () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    vi.mocked(getAuthorizedV3Survey).mockResolvedValue({ survey, authResult, response: null } as any);
+    vi.mocked(patchV3Survey).mockResolvedValue(updatedSurvey as any);
+    vi.mocked(serializeV3SurveyResource).mockImplementation((input) => {
+      return (input as any).name === "Updated Survey"
+        ? (serializedUpdatedSurvey as any)
+        : (serializedSurvey as any);
+    });
+  });
+
+  test("patches an authorized survey, serializes it, and enriches the audit log", async () => {
+    const auditLog = {} as any;
+    const patchBody = { name: "Updated Survey" };
+
+    const response = await patchV3SurveyResponse({
+      surveyId: "survey_1",
+      body: patchBody,
+      authentication,
+      requestId,
+      instance,
+      auditLog,
+    });
+
+    expect(response.status).toBe(200);
+    expect(vi.mocked(getAuthorizedV3Survey)).toHaveBeenCalledWith({
+      surveyId: "survey_1",
+      authentication,
+      access: "readWrite",
+      requestId,
+      instance,
+    });
+    expect(vi.mocked(patchV3Survey)).toHaveBeenCalledWith(survey, patchBody, requestId, "org_1");
+    expect(auditLog).toMatchObject({
+      organizationId: "org_1",
+      targetId: "survey_1",
+      oldObject: serializedSurvey,
+      newObject: serializedUpdatedSurvey,
+    });
+    expect(await readJson(response)).toEqual({ data: serializedUpdatedSurvey });
+  });
+
+  test("returns authorization responses from survey access", async () => {
+    vi.mocked(getAuthorizedV3Survey).mockResolvedValue({
+      survey: null,
+      authResult: null,
+      response: problemForbidden(requestId, "nope", instance),
+    } as any);
+
+    const response = await patchV3SurveyResponse({
+      surveyId: "survey_1",
+      body: { name: "Updated Survey" },
+      authentication,
+      requestId,
+      instance,
+    });
+
+    expect(response.status).toBe(403);
+    expect(vi.mocked(patchV3Survey)).not.toHaveBeenCalled();
+  });
+
+  test("maps validation, shape, permission, missing resource, and database errors", async () => {
+    vi.mocked(patchV3Survey).mockRejectedValueOnce(
+      new V3SurveyReferenceValidationError([{ name: "blocks.0", reason: "Unknown element" }])
+    );
+    expect(
+      (
+        await patchV3SurveyResponse({
+          surveyId: "survey_1",
+          body: { blocks: [] },
+          authentication,
+          requestId,
+          instance,
+        })
+      ).status
+    ).toBe(400);
+
+    vi.mocked(patchV3Survey).mockRejectedValueOnce(new V3SurveyUnsupportedShapeError("Unsupported"));
+    expect(
+      (
+        await patchV3SurveyResponse({
+          surveyId: "survey_1",
+          body: { blocks: [] },
+          authentication,
+          requestId,
+          instance,
+        })
+      ).status
+    ).toBe(400);
+
+    vi.mocked(patchV3Survey).mockRejectedValueOnce(new V3SurveyWritePermissionError("No external URLs"));
+    expect(
+      (
+        await patchV3SurveyResponse({
+          surveyId: "survey_1",
+          body: { blocks: [] },
+          authentication,
+          requestId,
+          instance,
+        })
+      ).status
+    ).toBe(403);
+
+    vi.mocked(patchV3Survey).mockRejectedValueOnce(new ResourceNotFoundError("Survey", "survey_1"));
+    expect(
+      (
+        await patchV3SurveyResponse({
+          surveyId: "survey_1",
+          body: { blocks: [] },
+          authentication,
+          requestId,
+          instance,
+        })
+      ).status
+    ).toBe(403);
+
+    vi.mocked(patchV3Survey).mockRejectedValueOnce(new DatabaseError("db down"));
+    expect(
+      (
+        await patchV3SurveyResponse({
+          surveyId: "survey_1",
+          body: { blocks: [] },
+          authentication,
+          requestId,
+          instance,
+        })
+      ).status
+    ).toBe(500);
+  });
+});
+
+describe("validateV3Survey", () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    vi.mocked(requireV3WorkspaceAccess).mockResolvedValue(authResult);
+    vi.mocked(getAuthorizedV3Survey).mockResolvedValue({ survey, authResult, response: null } as any);
+    vi.mocked(prepareV3SurveyCreateInput).mockReturnValue({
+      ok: true,
+      languageRequests: [{ code: "en-US", default: true, enabled: true }],
+    } as any);
+    vi.mocked(prepareV3SurveyPatchInput).mockReturnValue({
+      ok: false,
+      validation: { invalidParams: [{ name: "name", reason: "Required" }] },
+    } as any);
+  });
+
+  test("validates create input and checks workspace access when workspaceId is present", async () => {
+    const response = await validateV3Survey({
+      body: { operation: "create", data: createBody },
+      authentication,
+      requestId,
+      instance,
+    } as any);
+
+    expect(response.status).toBe(200);
+    expect(vi.mocked(requireV3WorkspaceAccess)).toHaveBeenCalledWith(
+      authentication,
+      workspaceId,
+      "readWrite",
+      requestId,
+      instance
+    );
+    expect(await readJson(response)).toEqual({
+      data: {
+        valid: true,
+        operation: "create",
+        invalid_params: [],
+        languages: [{ code: "en-US", default: true, enabled: true, writeBehavior: "connect_or_create" }],
+      },
+    });
+  });
+
+  test("returns authorization responses while validating create input", async () => {
+    vi.mocked(requireV3WorkspaceAccess).mockResolvedValue(problemForbidden(requestId, "nope", instance));
+
+    const response = await validateV3Survey({
+      body: { operation: "create", data: createBody },
+      authentication,
+      requestId,
+      instance,
+    } as any);
+
+    expect(response.status).toBe(403);
+    expect(vi.mocked(prepareV3SurveyCreateInput)).not.toHaveBeenCalled();
+  });
+
+  test("validates patch input against the authorized survey", async () => {
+    const response = await validateV3Survey({
+      body: { operation: "patch", surveyId: "survey_1", data: { name: "" } },
+      authentication,
+      requestId,
+      instance,
+    } as any);
+
+    expect(response.status).toBe(200);
+    expect(vi.mocked(getAuthorizedV3Survey)).toHaveBeenCalledWith({
+      surveyId: "survey_1",
+      authentication,
+      access: "readWrite",
+      requestId,
+      instance,
+    });
+    expect(vi.mocked(prepareV3SurveyPatchInput)).toHaveBeenCalledWith(survey, { name: "" });
+    expect(await readJson(response)).toEqual({
+      data: {
+        valid: false,
+        operation: "patch",
+        invalid_params: [{ name: "name", reason: "Required" }],
+      },
+    });
+  });
+
+  test("returns authorization responses while validating patch input", async () => {
+    vi.mocked(getAuthorizedV3Survey).mockResolvedValue({
+      survey: null,
+      authResult: null,
+      response: problemForbidden(requestId, "nope", instance),
+    } as any);
+
+    const response = await validateV3Survey({
+      body: { operation: "patch", surveyId: "survey_1", data: {} },
+      authentication,
+      requestId,
+      instance,
+    } as any);
+
+    expect(response.status).toBe(403);
+    expect(vi.mocked(prepareV3SurveyPatchInput)).not.toHaveBeenCalled();
+  });
+
+  test("maps database errors during validation", async () => {
+    vi.mocked(getAuthorizedV3Survey).mockRejectedValue(new DatabaseError("db down"));
+
+    const response = await validateV3Survey({
+      body: { operation: "patch", surveyId: "survey_1", data: {} },
+      authentication,
+      requestId,
+      instance,
+    } as any);
+
+    expect(response.status).toBe(500);
+  });
+});
diff --git a/apps/web/app/api/v3/surveys/lib/operations.ts b/apps/web/app/api/v3/surveys/lib/operations.ts
new file mode 100644
index 000000000000..bd8a5c5d03bb
--- /dev/null
+++ b/apps/web/app/api/v3/surveys/lib/operations.ts
@@ -0,0 +1,514 @@
+import "server-only";
+import { z } from "zod";
+import { logger } from "@formbricks/logger";
+import { DatabaseError, ResourceNotFoundError } from "@formbricks/types/errors";
+import { requireV3WorkspaceAccess } from "@/app/api/v3/lib/auth";
+import {
+  createdResponse,
+  noContentResponse,
+  problemBadRequest,
+  problemForbidden,
+  problemInternalError,
+  successListResponse,
+  successResponse,
+} from "@/app/api/v3/lib/response";
+import type { TV3AuditLog, TV3Authentication } from "@/app/api/v3/lib/types";
+import { deleteSurvey } from "@/modules/survey/lib/surveys";
+import { getSurveyCount } from "@/modules/survey/list/lib/survey";
+import { getSurveyListPage } from "@/modules/survey/list/lib/survey-page";
+import { getAuthorizedV3Survey } from "../authorization";
+import { V3SurveyCreatePermissionError, createV3Survey } from "../create";
+import { parseV3SurveysListQuery } from "../parse-v3-surveys-list-query";
+import { patchV3Survey } from "../patch";
+import {
+  type TV3SurveyPrepareResult,
+  prepareV3SurveyCreateInput,
+  prepareV3SurveyPatchInput,
+} from "../prepare";
+import { V3SurveyReferenceValidationError } from "../reference-validation";
+import type { TV3CreateSurveyBody, TV3SurveyDocument, TV3SurveyValidationRequestBody } from "../schemas";
+import {
+  V3SurveyLanguageError,
+  V3SurveyUnsupportedShapeError,
+  serializeV3SurveyListItem,
+  serializeV3SurveyResource,
+} from "../serializers";
+import { V3SurveyWritePermissionError } from "../write-permissions";
+
+type TListV3SurveysParams = {
+  searchParams: URLSearchParams;
+  authentication: TV3Authentication;
+  requestId: string;
+  instance: string;
+};
+
+type TCreateV3SurveyParams = {
+  body: TV3CreateSurveyBody;
+  authentication: TV3Authentication;
+  requestId: string;
+  instance: string;
+  auditLog?: TV3AuditLog;
+};
+
+type TGetV3SurveyParams = {
+  surveyId: string;
+  lang?: string[];
+  authentication: TV3Authentication;
+  requestId: string;
+  instance: string;
+};
+
+type TDeleteV3SurveyParams = {
+  surveyId: string;
+  authentication: TV3Authentication;
+  requestId: string;
+  instance: string;
+  auditLog?: TV3AuditLog;
+};
+
+type TPatchV3SurveyParams = {
+  surveyId: string;
+  body: unknown;
+  authentication: TV3Authentication;
+  requestId: string;
+  instance: string;
+  auditLog?: TV3AuditLog;
+};
+
+type TValidateV3SurveyParams = {
+  body: TV3SurveyValidationRequestBody;
+  authentication: TV3Authentication;
+  requestId: string;
+  instance: string;
+};
+
+const createWorkspaceIdSchema = z.object({
+  workspaceId: z.cuid2(),
+});
+
+function serializeValidationResult<TDocument extends TV3SurveyDocument>(
+  operation: "create" | "patch",
+  preparation: TV3SurveyPrepareResult<TDocument>
+) {
+  if (!preparation.ok) {
+    return {
+      valid: false,
+      operation,
+      invalid_params: preparation.validation.invalidParams,
+    };
+  }
+
+  return {
+    valid: true,
+    operation,
+    invalid_params: [],
+    languages: preparation.languageRequests.map((languageRequest) => ({
+      ...languageRequest,
+      writeBehavior: "connect_or_create" as const,
+    })),
+  };
+}
+
+export async function listV3Surveys({
+  searchParams,
+  authentication,
+  requestId,
+  instance,
+}: TListV3SurveysParams): Promise<Response> {
+  const log = logger.withContext({ requestId });
+
+  try {
+    const parsed = parseV3SurveysListQuery(searchParams);
+    if (!parsed.ok) {
+      log.warn({ statusCode: 400, invalidParams: parsed.invalid_params }, "Validation failed");
+      return problemBadRequest(requestId, "Invalid query parameters", {
+        invalid_params: parsed.invalid_params,
+        instance,
+      });
+    }
+
+    const authResult = await requireV3WorkspaceAccess(
+      authentication,
+      parsed.workspaceId,
+      "read",
+      requestId,
+      instance
+    );
+    if (authResult instanceof Response) {
+      return authResult;
+    }
+
+    const { workspaceId } = authResult;
+
+    const surveyPagePromise = getSurveyListPage(workspaceId, {
+      limit: parsed.limit,
+      cursor: parsed.cursor,
+      sortBy: parsed.sortBy,
+      filterCriteria: parsed.filterCriteria,
+    });
+    const totalCountPromise = parsed.includeTotalCount
+      ? getSurveyCount(workspaceId, parsed.filterCriteria)
+      : Promise.resolve(null);
+    const [surveyPage, totalCount] = await Promise.all([surveyPagePromise, totalCountPromise]);
+
+    return successListResponse(
+      surveyPage.surveys.map(serializeV3SurveyListItem),
+      {
+        limit: parsed.limit,
+        nextCursor: surveyPage.nextCursor,
+        totalCount,
+      },
+      { requestId, cache: "private, no-store" }
+    );
+  } catch (err) {
+    if (err instanceof ResourceNotFoundError) {
+      log.warn({ statusCode: 403, errorCode: err.name }, "Resource not found");
+      return problemForbidden(requestId, "You are not authorized to access this resource", instance);
+    }
+    if (err instanceof DatabaseError) {
+      log.error({ error: err, statusCode: 500 }, "Database error");
+      return problemInternalError(requestId, "An unexpected error occurred.", instance);
+    }
+    log.error({ error: err, statusCode: 500 }, "V3 surveys list unexpected error");
+    return problemInternalError(requestId, "An unexpected error occurred.", instance);
+  }
+}
+
+export async function createV3SurveyResponse({
+  body,
+  authentication,
+  requestId,
+  instance,
+  auditLog,
+}: TCreateV3SurveyParams): Promise<Response> {
+  const log = logger.withContext({ requestId, workspaceId: body.workspaceId });
+
+  try {
+    const authResult = await requireV3WorkspaceAccess(
+      authentication,
+      body.workspaceId,
+      "readWrite",
+      requestId,
+      instance
+    );
+    if (authResult instanceof Response) {
+      return authResult;
+    }
+
+    const survey = await createV3Survey(
+      {
+        ...body,
+        workspaceId: authResult.workspaceId,
+      },
+      authentication,
+      requestId,
+      authResult.organizationId
+    );
+    const resource = serializeV3SurveyResource(survey);
+
+    if (auditLog) {
+      auditLog.organizationId = authResult.organizationId;
+      auditLog.targetId = survey.id;
+      auditLog.newObject = resource;
+    }
+
+    return createdResponse(resource, {
+      requestId,
+      location: `/api/v3/surveys/${survey.id}`,
+    });
+  } catch (err) {
+    if (err instanceof V3SurveyReferenceValidationError) {
+      log.warn({ statusCode: 400, invalidParams: err.invalidParams }, "Survey document validation failed");
+      return problemBadRequest(requestId, "Invalid survey document", {
+        invalid_params: err.invalidParams,
+        instance,
+      });
+    }
+    if (err instanceof V3SurveyUnsupportedShapeError) {
+      log.warn({ statusCode: 400, errorCode: err.name }, "Unsupported survey shape");
+      return problemBadRequest(requestId, err.message, {
+        invalid_params: [{ name: "body", reason: err.message }],
+        instance,
+      });
+    }
+    if (err instanceof V3SurveyCreatePermissionError) {
+      log.warn({ statusCode: 403, errorCode: err.name }, "Survey create permission check failed");
+      return problemForbidden(requestId, err.message, instance);
+    }
+    if (err instanceof ResourceNotFoundError) {
+      log.warn({ statusCode: 403, errorCode: err.name }, "Resource not found");
+      return problemForbidden(requestId, "You are not authorized to access this resource", instance);
+    }
+    if (err instanceof DatabaseError) {
+      log.error({ error: err, statusCode: 500 }, "Database error");
+      return problemInternalError(requestId, "An unexpected error occurred.", instance);
+    }
+
+    log.error({ error: err, statusCode: 500 }, "V3 survey create unexpected error");
+    return problemInternalError(requestId, "An unexpected error occurred.", instance);
+  }
+}
+
+export async function getV3Survey({
+  surveyId,
+  lang,
+  authentication,
+  requestId,
+  instance,
+}: TGetV3SurveyParams): Promise<Response> {
+  const log = logger.withContext({ requestId, surveyId });
+
+  try {
+    const { survey, response } = await getAuthorizedV3Survey({
+      surveyId,
+      authentication,
+      access: "read",
+      requestId,
+      instance,
+    });
+
+    if (response) {
+      log.warn({ statusCode: response.status }, "Survey not found or not accessible");
+      return response;
+    }
+
+    try {
+      return successResponse(serializeV3SurveyResource(survey, { lang }), {
+        requestId,
+        cache: "private, no-store",
+      });
+    } catch (error) {
+      if (error instanceof V3SurveyLanguageError) {
+        log.warn({ statusCode: 400, detail: error.message, lang }, "Invalid survey language selector");
+        return problemBadRequest(requestId, error.message, {
+          instance,
+          invalid_params: [
+            {
+              name: "lang",
+              reason: error.message,
+              ...(error.normalizedCode && { identifier: error.normalizedCode }),
+            },
+          ],
+        });
+      }
+
+      if (error instanceof V3SurveyUnsupportedShapeError) {
+        log.warn({ statusCode: 400, detail: error.message }, "Unsupported v3 survey shape");
+        return problemBadRequest(requestId, error.message, {
+          instance,
+          invalid_params: [
+            {
+              name: "survey",
+              reason: error.message,
+            },
+          ],
+        });
+      }
+
+      throw error;
+    }
+  } catch (error) {
+    if (error instanceof DatabaseError) {
+      log.error({ error, statusCode: 500 }, "Database error");
+      return problemInternalError(requestId, "An unexpected error occurred.", instance);
+    }
+
+    log.error({ error, statusCode: 500 }, "V3 survey get unexpected error");
+    return problemInternalError(requestId, "An unexpected error occurred.", instance);
+  }
+}
+
+export async function deleteV3Survey({
+  surveyId,
+  authentication,
+  requestId,
+  instance,
+  auditLog,
+}: TDeleteV3SurveyParams): Promise<Response> {
+  const log = logger.withContext({ requestId, surveyId });
+
+  try {
+    const { survey, authResult, response } = await getAuthorizedV3Survey({
+      surveyId,
+      authentication,
+      access: "readWrite",
+      requestId,
+      instance,
+    });
+
+    if (response) {
+      log.warn({ statusCode: 403 }, "Survey not found or not accessible");
+      return response;
+    }
+
+    if (auditLog) {
+      auditLog.targetId = survey.id;
+      auditLog.organizationId = authResult.organizationId;
+      auditLog.oldObject = survey;
+    }
+
+    await deleteSurvey(surveyId);
+
+    return noContentResponse({ requestId });
+  } catch (error) {
+    if (error instanceof ResourceNotFoundError) {
+      log.warn({ errorCode: error.name, statusCode: 403 }, "Survey not found or not accessible");
+      return problemForbidden(requestId, "You are not authorized to access this resource", instance);
+    }
+
+    if (error instanceof DatabaseError) {
+      log.error({ error, statusCode: 500 }, "Database error");
+      return problemInternalError(requestId, "An unexpected error occurred.", instance);
+    }
+
+    log.error({ error, statusCode: 500 }, "V3 survey delete unexpected error");
+    return problemInternalError(requestId, "An unexpected error occurred.", instance);
+  }
+}
+
+export async function patchV3SurveyResponse({
+  surveyId,
+  body,
+  authentication,
+  requestId,
+  instance,
+  auditLog,
+}: TPatchV3SurveyParams): Promise<Response> {
+  const log = logger.withContext({ requestId, surveyId });
+  let workspaceId: string | undefined;
+
+  try {
+    const { survey, authResult, response } = await getAuthorizedV3Survey({
+      surveyId,
+      authentication,
+      access: "readWrite",
+      requestId,
+      instance,
+    });
+
+    if (response) {
+      log.warn({ statusCode: response.status }, "Survey not found or not accessible");
+      return response;
+    }
+
+    workspaceId = survey.workspaceId;
+    const updatedSurvey = await patchV3Survey(survey, body, requestId, authResult.organizationId);
+    const resource = serializeV3SurveyResource(updatedSurvey);
+
+    if (auditLog) {
+      auditLog.targetId = updatedSurvey.id;
+      auditLog.organizationId = authResult.organizationId;
+      auditLog.oldObject = serializeV3SurveyResource(survey);
+      auditLog.newObject = resource;
+    }
+
+    return successResponse(resource, {
+      requestId,
+      cache: "private, no-store",
+    });
+  } catch (error) {
+    if (error instanceof V3SurveyReferenceValidationError) {
+      log.warn(
+        { statusCode: 400, workspaceId, invalidParamCount: error.invalidParams.length },
+        "Survey document validation failed"
+      );
+      return problemBadRequest(requestId, "Invalid survey document", {
+        invalid_params: error.invalidParams,
+        instance,
+      });
+    }
+
+    if (error instanceof V3SurveyUnsupportedShapeError) {
+      log.warn({ statusCode: 400, workspaceId, errorCode: error.name }, "Unsupported v3 survey shape");
+      return problemBadRequest(requestId, error.message, {
+        instance,
+        invalid_params: [
+          {
+            name: "survey",
+            reason: error.message,
+          },
+        ],
+      });
+    }
+
+    if (error instanceof V3SurveyWritePermissionError) {
+      log.warn({ statusCode: 403, workspaceId, errorCode: error.name }, "Survey patch permission check failed");
+      return problemForbidden(requestId, error.message, instance);
+    }
+
+    if (error instanceof ResourceNotFoundError) {
+      log.warn({ errorCode: error.name, workspaceId, statusCode: 403 }, "Survey not found or not accessible");
+      return problemForbidden(requestId, "You are not authorized to access this resource", instance);
+    }
+
+    if (error instanceof DatabaseError) {
+      log.error({ error, workspaceId, statusCode: 500 }, "Database error");
+      return problemInternalError(requestId, "An unexpected error occurred.", instance);
+    }
+
+    log.error({ error, workspaceId, statusCode: 500 }, "V3 survey patch unexpected error");
+    return problemInternalError(requestId, "An unexpected error occurred.", instance);
+  }
+}
+
+export async function validateV3Survey({
+  body,
+  authentication,
+  requestId,
+  instance,
+}: TValidateV3SurveyParams): Promise<Response> {
+  const log = logger.withContext({ requestId, operation: body.operation });
+
+  try {
+    if (body.operation === "create") {
+      const workspaceResult = createWorkspaceIdSchema.safeParse(body.data);
+      if (workspaceResult.success) {
+        const authResult = await requireV3WorkspaceAccess(
+          authentication,
+          workspaceResult.data.workspaceId,
+          "readWrite",
+          requestId,
+          instance
+        );
+
+        if (authResult instanceof Response) {
+          return authResult;
+        }
+      }
+
+      return successResponse(serializeValidationResult("create", prepareV3SurveyCreateInput(body.data)), {
+        requestId,
+        cache: "private, no-store",
+      });
+    }
+
+    const { survey, response } = await getAuthorizedV3Survey({
+      surveyId: body.surveyId,
+      authentication,
+      access: "readWrite",
+      requestId,
+      instance,
+    });
+
+    if (response) {
+      log.warn({ statusCode: response.status, surveyId: body.surveyId }, "Survey not found or not accessible");
+      return response;
+    }
+
+    return successResponse(
+      serializeValidationResult("patch", prepareV3SurveyPatchInput(survey, body.data)),
+      {
+        requestId,
+        cache: "private, no-store",
+      }
+    );
+  } catch (error) {
+    if (error instanceof DatabaseError) {
+      log.error({ error, statusCode: 500 }, "Database error");
+      return problemInternalError(requestId, "An unexpected error occurred.", instance);
+    }
+
+    log.error({ error, statusCode: 500 }, "V3 survey validation unexpected error");
+    return problemInternalError(requestId, "An unexpected error occurred.", instance);
+  }
+}
diff --git a/apps/web/app/api/v3/surveys/route.ts b/apps/web/app/api/v3/surveys/route.ts
index 508c8779b57d..d428a73caf8d 100644
--- a/apps/web/app/api/v3/surveys/route.ts
+++ b/apps/web/app/api/v3/surveys/route.ts
@@ -1,91 +1,20 @@
 /**
- * /api/v3/surveys — list and create block-based survey management resources.
+ * /api/v3/surveys - list and create block-based survey management resources.
  * Session cookie or x-api-key; scope by workspaceId only.
  */
-import { logger } from "@formbricks/logger";
-import { DatabaseError, ResourceNotFoundError } from "@formbricks/types/errors";
 import { withV3ApiWrapper } from "@/app/api/v3/lib/api-wrapper";
-import { requireV3WorkspaceAccess } from "@/app/api/v3/lib/auth";
-import {
-  createdResponse,
-  problemBadRequest,
-  problemForbidden,
-  problemInternalError,
-  successListResponse,
-} from "@/app/api/v3/lib/response";
-import { getSurveyCount } from "@/modules/survey/list/lib/survey";
-import { getSurveyListPage } from "@/modules/survey/list/lib/survey-page";
-import { V3SurveyCreatePermissionError, createV3Survey } from "./create";
-import { parseV3SurveysListQuery } from "./parse-v3-surveys-list-query";
-import { V3SurveyReferenceValidationError } from "./reference-validation";
+import { createV3SurveyResponse, listV3Surveys } from "./lib/operations";
 import { ZV3CreateSurveyBody } from "./schemas";
-import {
-  V3SurveyUnsupportedShapeError,
-  serializeV3SurveyListItem,
-  serializeV3SurveyResource,
-} from "./serializers";
 
 export const GET = withV3ApiWrapper({
   auth: "both",
   handler: async ({ req, authentication, requestId, instance }) => {
-    const log = logger.withContext({ requestId });
-
-    try {
-      const searchParams = new URL(req.url).searchParams;
-      const parsed = parseV3SurveysListQuery(searchParams);
-      if (!parsed.ok) {
-        log.warn({ statusCode: 400, invalidParams: parsed.invalid_params }, "Validation failed");
-        return problemBadRequest(requestId, "Invalid query parameters", {
-          invalid_params: parsed.invalid_params,
-          instance,
-        });
-      }
-
-      const authResult = await requireV3WorkspaceAccess(
-        authentication,
-        parsed.workspaceId,
-        "read",
-        requestId,
-        instance
-      );
-      if (authResult instanceof Response) {
-        return authResult;
-      }
-
-      const { workspaceId } = authResult;
-
-      const surveyPagePromise = getSurveyListPage(workspaceId, {
-        limit: parsed.limit,
-        cursor: parsed.cursor,
-        sortBy: parsed.sortBy,
-        filterCriteria: parsed.filterCriteria,
-      });
-      const totalCountPromise = parsed.includeTotalCount
-        ? getSurveyCount(workspaceId, parsed.filterCriteria)
-        : Promise.resolve(null);
-      const [surveyPage, totalCount] = await Promise.all([surveyPagePromise, totalCountPromise]);
-
-      return successListResponse(
-        surveyPage.surveys.map(serializeV3SurveyListItem),
-        {
-          limit: parsed.limit,
-          nextCursor: surveyPage.nextCursor,
-          totalCount,
-        },
-        { requestId, cache: "private, no-store" }
-      );
-    } catch (err) {
-      if (err instanceof ResourceNotFoundError) {
-        log.warn({ statusCode: 403, errorCode: err.name }, "Resource not found");
-        return problemForbidden(requestId, "You are not authorized to access this resource", instance);
-      }
-      if (err instanceof DatabaseError) {
-        log.error({ error: err, statusCode: 500 }, "Database error");
-        return problemInternalError(requestId, "An unexpected error occurred.", instance);
-      }
-      log.error({ error: err, statusCode: 500 }, "V3 surveys list unexpected error");
-      return problemInternalError(requestId, "An unexpected error occurred.", instance);
-    }
+    return await listV3Surveys({
+      searchParams: new URL(req.url).searchParams,
+      authentication,
+      requestId,
+      instance,
+    });
   },
 });
 
@@ -97,72 +26,12 @@ export const POST = withV3ApiWrapper({
   action: "created",
   targetType: "survey",
   handler: async ({ authentication, auditLog, parsedInput, requestId, instance }) => {
-    const { body } = parsedInput;
-    const log = logger.withContext({ requestId, workspaceId: body.workspaceId });
-
-    try {
-      const authResult = await requireV3WorkspaceAccess(
-        authentication,
-        body.workspaceId,
-        "readWrite",
-        requestId,
-        instance
-      );
-      if (authResult instanceof Response) {
-        return authResult;
-      }
-
-      const survey = await createV3Survey(
-        {
-          ...body,
-          workspaceId: authResult.workspaceId,
-        },
-        authentication,
-        requestId,
-        authResult.organizationId
-      );
-      const resource = serializeV3SurveyResource(survey);
-
-      if (auditLog) {
-        auditLog.organizationId = authResult.organizationId;
-        auditLog.targetId = survey.id;
-        auditLog.newObject = resource;
-      }
-
-      return createdResponse(resource, {
-        requestId,
-        location: `/api/v3/surveys/${survey.id}`,
-      });
-    } catch (err) {
-      if (err instanceof V3SurveyReferenceValidationError) {
-        log.warn({ statusCode: 400, invalidParams: err.invalidParams }, "Survey document validation failed");
-        return problemBadRequest(requestId, "Invalid survey document", {
-          invalid_params: err.invalidParams,
-          instance,
-        });
-      }
-      if (err instanceof V3SurveyUnsupportedShapeError) {
-        log.warn({ statusCode: 400, errorCode: err.name }, "Unsupported survey shape");
-        return problemBadRequest(requestId, err.message, {
-          invalid_params: [{ name: "body", reason: err.message }],
-          instance,
-        });
-      }
-      if (err instanceof V3SurveyCreatePermissionError) {
-        log.warn({ statusCode: 403, errorCode: err.name }, "Survey create permission check failed");
-        return problemForbidden(requestId, err.message, instance);
-      }
-      if (err instanceof ResourceNotFoundError) {
-        log.warn({ statusCode: 403, errorCode: err.name }, "Resource not found");
-        return problemForbidden(requestId, "You are not authorized to access this resource", instance);
-      }
-      if (err instanceof DatabaseError) {
-        log.error({ error: err, statusCode: 500 }, "Database error");
-        return problemInternalError(requestId, "An unexpected error occurred.", instance);
-      }
-
-      log.error({ error: err, statusCode: 500 }, "V3 survey create unexpected error");
-      return problemInternalError(requestId, "An unexpected error occurred.", instance);
-    }
+    return await createV3SurveyResponse({
+      body: parsedInput.body,
+      authentication,
+      requestId,
+      instance,
+      auditLog,
+    });
   },
 });
diff --git a/apps/web/app/api/v3/surveys/serializers.test.ts b/apps/web/app/api/v3/surveys/serializers.test.ts
index 1aeff26d0d59..11207a5578ee 100644
--- a/apps/web/app/api/v3/surveys/serializers.test.ts
+++ b/apps/web/app/api/v3/surveys/serializers.test.ts
@@ -1,8 +1,10 @@
 import { describe, expect, test } from "vitest";
 import type { TSurvey } from "@formbricks/types/surveys/types";
+import type { TSurvey as TSurveyListRecord } from "@/modules/survey/list/types/surveys";
 import {
   V3SurveyLanguageError,
   V3SurveyUnsupportedShapeError,
+  serializeV3SurveyListItem,
   serializeV3SurveyResource,
 } from "./serializers";
 
@@ -597,3 +599,40 @@ describe("serializeV3SurveyResource", () => {
     );
   });
 });
+
+describe("serializeV3SurveyListItem", () => {
+  const baseListSurvey = {
+    id: "survey_1",
+    name: "Customer onboarding",
+    workspaceId: "workspace_1",
+    type: "link",
+    status: "draft",
+    publishOn: null,
+    createdAt: new Date("2026-04-15T10:00:00.000Z"),
+    updatedAt: new Date("2026-04-16T10:00:00.000Z"),
+    responseCount: 0,
+    singleUse: null,
+  } satisfies Omit<TSurveyListRecord, "creator">;
+
+  test("allowlists nested creator fields", () => {
+    const survey = {
+      ...baseListSurvey,
+      creator: {
+        name: "Ada",
+        email: "ada@example.com",
+        id: "user_1",
+      },
+    } as unknown as TSurveyListRecord;
+
+    expect(serializeV3SurveyListItem(survey).creator).toEqual({ name: "Ada" });
+  });
+
+  test("preserves null creator", () => {
+    const survey = {
+      ...baseListSurvey,
+      creator: null,
+    } satisfies TSurveyListRecord;
+
+    expect(serializeV3SurveyListItem(survey).creator).toBeNull();
+  });
+});
diff --git a/apps/web/app/api/v3/surveys/serializers.ts b/apps/web/app/api/v3/surveys/serializers.ts
index eb899316d2ec..127018b25446 100644
--- a/apps/web/app/api/v3/surveys/serializers.ts
+++ b/apps/web/app/api/v3/surveys/serializers.ts
@@ -11,7 +11,25 @@ import {
 } from "./language";
 import { V3_SURVEY_TRANSLATABLE_METADATA_KEYS } from "./translation-fields";
 
-export type TV3SurveyListItem = Omit<TSurveyListRecord, "singleUse">;
+export type TV3SurveyCreator = Pick<NonNullable<TSurveyListRecord["creator"]>, "name">;
+
+type TV3SurveyListItemBase = Pick<
+  TSurveyListRecord,
+  | "id"
+  | "name"
+  | "workspaceId"
+  | "type"
+  | "status"
+  | "publishOn"
+  | "createdAt"
+  | "updatedAt"
+  | "responseCount"
+>;
+
+export type TV3SurveyListItem = TV3SurveyListItemBase & {
+  creator: TV3SurveyCreator | null;
+};
+
 const DEFAULT_V3_SURVEY_LANGUAGE = "en-US";
 
 type TSerializedValue =
@@ -39,14 +57,33 @@ export class V3SurveyUnsupportedShapeError extends Error {
   }
 }
 
+export function serializeV3SurveyCreator(creator: TSurveyListRecord["creator"]): TV3SurveyCreator | null {
+  if (!creator) {
+    return null;
+  }
+
+  return {
+    name: creator.name,
+  };
+}
+
 /**
  * Keep the v3 API contract isolated from internal persistence naming.
  * Surveys are scoped by workspaceId.
  */
 export function serializeV3SurveyListItem(survey: TSurveyListRecord): TV3SurveyListItem {
-  const { singleUse: _omitSingleUse, ...rest } = survey;
-
-  return rest;
+  return {
+    id: survey.id,
+    name: survey.name,
+    workspaceId: survey.workspaceId,
+    type: survey.type,
+    status: survey.status,
+    publishOn: survey.publishOn,
+    createdAt: survey.createdAt,
+    updatedAt: survey.updatedAt,
+    responseCount: survey.responseCount,
+    creator: serializeV3SurveyCreator(survey.creator),
+  };
 }
 
 function toIsoString(value: Date | string): string {
diff --git a/apps/web/app/api/v3/surveys/validate/route.ts b/apps/web/app/api/v3/surveys/validate/route.ts
index bc7f0c0b0471..a7a0fb1ff527 100644
--- a/apps/web/app/api/v3/surveys/validate/route.ts
+++ b/apps/web/app/api/v3/surveys/validate/route.ts
@@ -1,43 +1,6 @@
-import { z } from "zod";
-import { logger } from "@formbricks/logger";
-import { DatabaseError } from "@formbricks/types/errors";
 import { withV3ApiWrapper } from "@/app/api/v3/lib/api-wrapper";
-import { requireV3WorkspaceAccess } from "@/app/api/v3/lib/auth";
-import { problemInternalError, successResponse } from "@/app/api/v3/lib/response";
-import { getAuthorizedV3Survey } from "../authorization";
-import {
-  type TV3SurveyPrepareResult,
-  prepareV3SurveyCreateInput,
-  prepareV3SurveyPatchInput,
-} from "../prepare";
-import { type TV3SurveyDocument, ZV3EmptyQuery, ZV3SurveyValidationRequestBody } from "../schemas";
-
-const createWorkspaceIdSchema = z.object({
-  workspaceId: z.cuid2(),
-});
-
-function serializeValidationResult<TDocument extends TV3SurveyDocument>(
-  operation: "create" | "patch",
-  preparation: TV3SurveyPrepareResult<TDocument>
-) {
-  if (!preparation.ok) {
-    return {
-      valid: false,
-      operation,
-      invalid_params: preparation.validation.invalidParams,
-    };
-  }
-
-  return {
-    valid: true,
-    operation,
-    invalid_params: [],
-    languages: preparation.languageRequests.map((languageRequest) => ({
-      ...languageRequest,
-      writeBehavior: "connect_or_create" as const,
-    })),
-  };
-}
+import { validateV3Survey } from "../lib/operations";
+import { ZV3EmptyQuery, ZV3SurveyValidationRequestBody } from "../schemas";
 
 export const POST = withV3ApiWrapper({
   auth: "both",
@@ -46,63 +9,11 @@ export const POST = withV3ApiWrapper({
     query: ZV3EmptyQuery,
   },
   handler: async ({ parsedInput, authentication, requestId, instance }) => {
-    const { body } = parsedInput;
-    const log = logger.withContext({ requestId, operation: body.operation });
-
-    try {
-      if (body.operation === "create") {
-        const workspaceResult = createWorkspaceIdSchema.safeParse(body.data);
-        if (workspaceResult.success) {
-          const authResult = await requireV3WorkspaceAccess(
-            authentication,
-            workspaceResult.data.workspaceId,
-            "readWrite",
-            requestId,
-            instance
-          );
-
-          if (authResult instanceof Response) {
-            return authResult;
-          }
-        }
-
-        return successResponse(serializeValidationResult("create", prepareV3SurveyCreateInput(body.data)), {
-          requestId,
-          cache: "private, no-store",
-        });
-      }
-
-      const { survey, response } = await getAuthorizedV3Survey({
-        surveyId: body.surveyId,
-        authentication,
-        access: "readWrite",
-        requestId,
-        instance,
-      });
-
-      if (response) {
-        log.warn(
-          { statusCode: response.status, surveyId: body.surveyId },
-          "Survey not found or not accessible"
-        );
-        return response;
-      }
-
-      return successResponse(
-        serializeValidationResult("patch", prepareV3SurveyPatchInput(survey, body.data)),
-        {
-          requestId,
-          cache: "private, no-store",
-        }
-      );
-    } catch (error) {
-      if (error instanceof DatabaseError) {
-        log.error({ error, statusCode: 500 }, "Database error");
-        return problemInternalError(requestId, "An unexpected error occurred.", instance);
-      }
-
-      log.error({ error, statusCode: 500 }, "V3 survey validation unexpected error");
-      return problemInternalError(requestId, "An unexpected error occurred.", instance);
-    }
+    return await validateV3Survey({
+      body: parsedInput.body,
+      authentication,
+      requestId,
+      instance,
+    });
   },
 });
diff --git a/apps/web/modules/mcp/auth.test.ts b/apps/web/modules/mcp/auth.test.ts
new file mode 100644
index 000000000000..412ef4a0c53a
--- /dev/null
+++ b/apps/web/modules/mcp/auth.test.ts
@@ -0,0 +1,210 @@
+import { ApiKeyPermission } from "@prisma/client";
+import { NextRequest } from "next/server";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import { TooManyRequestsError } from "@formbricks/types/errors";
+import { authenticateApiKeyFromHeaders } from "@/modules/api/lib/api-key-auth";
+import { applyRateLimit } from "@/modules/core/rate-limit/helpers";
+import {
+  authenticateMcpRequest,
+  getMcpAuthentication,
+  getMcpRequestId,
+  handleAuthenticatedMcpRequest,
+} from "./auth";
+
+vi.mock("@/modules/api/lib/api-key-auth", () => ({
+  authenticateApiKeyFromHeaders: vi.fn(),
+}));
+
+vi.mock("@/modules/core/rate-limit/helpers", () => ({
+  applyRateLimit: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("@/lib/getPublicUrl", () => ({
+  getPublicDomain: vi.fn(() => "https://app.example.com"),
+}));
+
+vi.mock("@formbricks/logger", () => ({
+  logger: {
+    withContext: vi.fn(() => ({
+      warn: vi.fn(),
+      error: vi.fn(),
+    })),
+  },
+}));
+
+const apiKeyAuth = {
+  type: "apiKey" as const,
+  apiKeyId: "key_1",
+  organizationId: "org_1",
+  organizationAccess: {
+    accessControl: { read: true, write: true },
+  },
+  workspacePermissions: [
+    {
+      workspaceId: "workspace_1",
+      workspaceName: "Workspace",
+      permission: ApiKeyPermission.write,
+    },
+  ],
+};
+
+function createRequest(url = "http://localhost/api/mcp", headers: Record<string, string> = {}): NextRequest {
+  return new NextRequest(url, {
+    method: "POST",
+    headers,
+  });
+}
+
+describe("authenticateMcpRequest", () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    vi.mocked(applyRateLimit).mockResolvedValue(undefined);
+  });
+
+  test("returns 401 when no API key authenticates", async () => {
+    vi.mocked(authenticateApiKeyFromHeaders).mockResolvedValue(null);
+
+    const result = await authenticateMcpRequest(createRequest());
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.response.status).toBe(401);
+      expect(await result.response.json()).toMatchObject({
+        code: "not_authenticated",
+        detail: "API key required",
+      });
+    }
+  });
+
+  test("rejects API keys in query parameters", async () => {
+    const result = await authenticateMcpRequest(createRequest("http://localhost/api/mcp?apiKey=secret"));
+
+    expect(result.ok).toBe(false);
+    expect(authenticateApiKeyFromHeaders).not.toHaveBeenCalled();
+    if (!result.ok) {
+      expect(result.response.status).toBe(400);
+      const body = await result.response.json();
+      expect(body.invalid_params[0].name).toBe("query");
+    }
+  });
+
+  test("rejects query credential parameters case-insensitively", async () => {
+    const result = await authenticateMcpRequest(
+      createRequest("http://localhost/api/mcp?Authorization=Bearer%20secret")
+    );
+
+    expect(result.ok).toBe(false);
+    expect(authenticateApiKeyFromHeaders).not.toHaveBeenCalled();
+    if (!result.ok) {
+      expect(result.response.status).toBe(400);
+    }
+  });
+
+  test("rejects cross-origin browser requests", async () => {
+    const result = await authenticateMcpRequest(
+      createRequest("https://app.example.com/api/mcp", {
+        origin: "https://evil.example.com",
+        host: "app.example.com",
+      })
+    );
+
+    expect(result.ok).toBe(false);
+    expect(authenticateApiKeyFromHeaders).not.toHaveBeenCalled();
+    if (!result.ok) {
+      expect(result.response.status).toBe(403);
+    }
+  });
+
+  test("does not trust forwarded host headers for origin validation", async () => {
+    const result = await authenticateMcpRequest(
+      createRequest("https://app.example.com/api/mcp", {
+        origin: "https://evil.example.com",
+        "x-forwarded-host": "evil.example.com",
+        "x-forwarded-proto": "https",
+      })
+    );
+
+    expect(result.ok).toBe(false);
+    expect(authenticateApiKeyFromHeaders).not.toHaveBeenCalled();
+    if (!result.ok) {
+      expect(result.response.status).toBe(403);
+    }
+  });
+
+  test("allows the configured public origin", async () => {
+    vi.mocked(authenticateApiKeyFromHeaders).mockResolvedValue(apiKeyAuth);
+
+    const result = await authenticateMcpRequest(
+      createRequest("http://internal.local/api/mcp", {
+        origin: "https://app.example.com",
+        "x-api-key": "fbk_test",
+      })
+    );
+
+    expect(result.ok).toBe(true);
+  });
+
+  test("returns auth info for a valid API key and rate limits by API key id", async () => {
+    vi.mocked(authenticateApiKeyFromHeaders).mockResolvedValue(apiKeyAuth);
+
+    const result = await authenticateMcpRequest(
+      createRequest("http://localhost/api/mcp", {
+        "x-request-id": "req_1",
+        "x-api-key": "fbk_test",
+      })
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.requestId).toBe("req_1");
+      expect(result.authInfo.clientId).toBe("key_1");
+      expect(result.authInfo.token).toBe("key_1");
+      expect(getMcpAuthentication(result.authInfo)).toEqual(apiKeyAuth);
+      expect(getMcpRequestId(result.authInfo)).toBe("req_1");
+    }
+    expect(applyRateLimit).toHaveBeenCalledWith(expect.objectContaining({ namespace: "api:v3" }), "key_1");
+  });
+
+  test("returns 429 when rate limited", async () => {
+    vi.mocked(authenticateApiKeyFromHeaders).mockResolvedValue(apiKeyAuth);
+    vi.mocked(applyRateLimit).mockRejectedValue(new TooManyRequestsError("Too many requests", 30));
+
+    const result = await authenticateMcpRequest(createRequest());
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.response.status).toBe(429);
+      expect(result.response.headers.get("Retry-After")).toBe("30");
+    }
+  });
+});
+
+describe("handleAuthenticatedMcpRequest", () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    vi.mocked(applyRateLimit).mockResolvedValue(undefined);
+  });
+
+  test("attaches MCP auth info and request headers to handler response", async () => {
+    vi.mocked(authenticateApiKeyFromHeaders).mockResolvedValue(apiKeyAuth);
+    const handler = vi.fn(async (request: Request & { auth?: unknown }) => {
+      expect(request.auth).toMatchObject({
+        clientId: "key_1",
+      });
+      return Response.json({ ok: true });
+    });
+
+    const response = await handleAuthenticatedMcpRequest(
+      createRequest("http://localhost/api/mcp", {
+        "x-request-id": "req_2",
+        "x-api-key": "fbk_test",
+      }),
+      handler
+    );
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("X-Request-Id")).toBe("req_2");
+    expect(response.headers.get("Cache-Control")).toBe("private, no-store");
+    expect(await response.json()).toEqual({ ok: true });
+  });
+});
diff --git a/apps/web/modules/mcp/auth.ts b/apps/web/modules/mcp/auth.ts
new file mode 100644
index 000000000000..eb6fc54c1a3a
--- /dev/null
+++ b/apps/web/modules/mcp/auth.ts
@@ -0,0 +1,209 @@
+import "server-only";
+import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+import { ApiKeyPermission } from "@prisma/client";
+import type { NextRequest } from "next/server";
+import { logger } from "@formbricks/logger";
+import type { TAuthenticationApiKey } from "@formbricks/types/auth";
+import { TooManyRequestsError } from "@formbricks/types/errors";
+import {
+  problemBadRequest,
+  problemForbidden,
+  problemInternalError,
+  problemTooManyRequests,
+  problemUnauthorized,
+} from "@/app/api/v3/lib/response";
+import { getPublicDomain } from "@/lib/getPublicUrl";
+import { authenticateApiKeyFromHeaders } from "@/modules/api/lib/api-key-auth";
+import { applyRateLimit } from "@/modules/core/rate-limit/helpers";
+import { rateLimitConfigs } from "@/modules/core/rate-limit/rate-limit-configs";
+
+const QUERY_CREDENTIAL_PARAMS = new Set([
+  "api_key",
+  "apikey",
+  "x-api-key",
+  "access_token",
+  "token",
+  "authorization",
+]);
+
+export type TMcpAuthInfo = AuthInfo & {
+  extra: {
+    formbricksAuthentication: TAuthenticationApiKey;
+    requestId: string;
+  };
+};
+
+type TMcpAuthenticationResult =
+  | {
+      ok: true;
+      authInfo: TMcpAuthInfo;
+      requestId: string;
+    }
+  | {
+      ok: false;
+      response: Response;
+      requestId: string;
+    };
+
+function getRequestId(request: NextRequest): string {
+  return request.headers.get("x-request-id") ?? crypto.randomUUID();
+}
+
+function getPublicOrigin(): string {
+  return new URL(getPublicDomain()).origin;
+}
+
+function hasQueryCredentials(searchParams: URLSearchParams): boolean {
+  return Array.from(searchParams.keys()).some((param) => QUERY_CREDENTIAL_PARAMS.has(param.toLowerCase()));
+}
+
+function isOriginAllowed(request: NextRequest): boolean {
+  const origin = request.headers.get("origin");
+  if (!origin) {
+    return true;
+  }
+
+  try {
+    return new URL(origin).origin === getPublicOrigin();
+  } catch {
+    return false;
+  }
+}
+
+function getMcpScopes(authentication: TAuthenticationApiKey): string[] {
+  const scopes = new Set(["surveys:read"]);
+  if (
+    authentication.workspacePermissions.some(
+      (permission) =>
+        permission.permission === ApiKeyPermission.write || permission.permission === ApiKeyPermission.manage
+    )
+  ) {
+    scopes.add("surveys:write");
+  }
+
+  return Array.from(scopes);
+}
+
+function createMcpAuthInfo(authentication: TAuthenticationApiKey, requestId: string): TMcpAuthInfo {
+  return {
+    token: authentication.apiKeyId,
+    clientId: authentication.apiKeyId,
+    scopes: getMcpScopes(authentication),
+    extra: {
+      formbricksAuthentication: authentication,
+      requestId,
+    },
+  };
+}
+
+export function getMcpAuthentication(authInfo?: AuthInfo): TAuthenticationApiKey | null {
+  const authentication = authInfo?.extra?.formbricksAuthentication;
+  if (!authentication || typeof authentication !== "object" || !("apiKeyId" in authentication)) {
+    return null;
+  }
+
+  return authentication as TAuthenticationApiKey;
+}
+
+export function getMcpRequestId(authInfo?: AuthInfo): string {
+  const requestId = authInfo?.extra?.requestId;
+  return typeof requestId === "string" && requestId.length > 0 ? requestId : crypto.randomUUID();
+}
+
+export function withMcpResponseHeaders(response: Response, requestId: string): Response {
+  const headers = new Headers(response.headers);
+  headers.set("X-Request-Id", requestId);
+  headers.set("Cache-Control", "private, no-store");
+
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
+export async function authenticateMcpRequest(request: NextRequest): Promise<TMcpAuthenticationResult> {
+  const requestId = getRequestId(request);
+  const instance = request.nextUrl.pathname;
+  const log = logger.withContext({ requestId, path: instance, method: request.method });
+
+  if (hasQueryCredentials(request.nextUrl.searchParams)) {
+    log.warn({ statusCode: 400 }, "MCP API key supplied in query parameters");
+    return {
+      ok: false,
+      requestId,
+      response: problemBadRequest(requestId, "API keys must be sent in headers, not query parameters", {
+        instance,
+        invalid_params: [
+          {
+            name: "query",
+            reason: "Send the API key with x-api-key or Authorization: Bearer.",
+          },
+        ],
+      }),
+    };
+  }
+
+  if (!isOriginAllowed(request)) {
+    log.warn({ statusCode: 403, origin: request.headers.get("origin") }, "MCP origin validation failed");
+    return {
+      ok: false,
+      requestId,
+      response: problemForbidden(requestId, "Cross-origin MCP requests are not allowed", instance),
+    };
+  }
+
+  try {
+    const authentication = await authenticateApiKeyFromHeaders(request.headers);
+    if (!authentication) {
+      log.warn({ statusCode: 401 }, "MCP API authentication failed");
+      return {
+        ok: false,
+        requestId,
+        response: problemUnauthorized(requestId, "API key required", instance),
+      };
+    }
+
+    try {
+      await applyRateLimit(rateLimitConfigs.api.v3, authentication.apiKeyId);
+    } catch (error) {
+      log.warn({ error, statusCode: 429, apiKeyId: authentication.apiKeyId }, "MCP API rate limit exceeded");
+      return {
+        ok: false,
+        requestId,
+        response: problemTooManyRequests(
+          requestId,
+          error instanceof Error ? error.message : "Rate limit exceeded",
+          error instanceof TooManyRequestsError ? error.retryAfter : undefined
+        ),
+      };
+    }
+
+    return {
+      ok: true,
+      requestId,
+      authInfo: createMcpAuthInfo(authentication, requestId),
+    };
+  } catch (error) {
+    log.error({ error, statusCode: 500 }, "MCP API authentication unexpected error");
+    return {
+      ok: false,
+      requestId,
+      response: problemInternalError(requestId, "An unexpected error occurred.", instance),
+    };
+  }
+}
+
+export async function handleAuthenticatedMcpRequest(
+  request: NextRequest,
+  handler: (request: Request) => Promise<Response>
+): Promise<Response> {
+  const authResult = await authenticateMcpRequest(request);
+  if (!authResult.ok) {
+    return authResult.response;
+  }
+
+  (request as Request & { auth?: AuthInfo }).auth = authResult.authInfo;
+  const response = await handler(request);
+  return withMcpResponseHeaders(response, authResult.requestId);
+}
diff --git a/apps/web/modules/mcp/constants.ts b/apps/web/modules/mcp/constants.ts
new file mode 100644
index 000000000000..cdd85abbcb0c
--- /dev/null
+++ b/apps/web/modules/mcp/constants.ts
@@ -0,0 +1,3 @@
+export const MCP_API_ROUTE = "/api/mcp" as const;
+export const MCP_SERVER_NAME = "formbricks-v3-surveys" as const;
+export const MCP_SERVER_VERSION = "0.1.0" as const;
diff --git a/apps/web/modules/mcp/errors.ts b/apps/web/modules/mcp/errors.ts
new file mode 100644
index 000000000000..6afec836c682
--- /dev/null
+++ b/apps/web/modules/mcp/errors.ts
@@ -0,0 +1,72 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { ProblemBody } from "@/app/api/v3/lib/response";
+
+type TMcpSuccessPayload = Record<string, unknown> & {
+  requestId: string;
+};
+
+type TMcpErrorPayload = {
+  error: {
+    status: number;
+    title: string;
+    detail: string;
+    requestId: string;
+    code?: string;
+    invalid_params?: ProblemBody["invalid_params"];
+  };
+};
+
+function toTextResult(payload: TMcpSuccessPayload | TMcpErrorPayload, isError = false): CallToolResult {
+  return {
+    ...(isError ? { isError: true } : {}),
+    structuredContent: payload,
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(payload),
+      },
+    ],
+  };
+}
+
+async function readJsonResponse(response: Response): Promise<Record<string, unknown>> {
+  try {
+    const body = await response.json();
+    return body && typeof body === "object" ? (body as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+export async function responseToMcpToolResult(
+  response: Response,
+  fallbackRequestId: string
+): Promise<CallToolResult> {
+  const body = await readJsonResponse(response);
+  const requestId =
+    typeof body.requestId === "string"
+      ? body.requestId
+      : (response.headers.get("X-Request-Id") ?? fallbackRequestId);
+
+  if (response.ok) {
+    return toTextResult({
+      ...body,
+      requestId,
+    });
+  }
+
+  const problem = body as Partial<ProblemBody>;
+  return toTextResult(
+    {
+      error: {
+        status: response.status,
+        title: typeof problem.title === "string" ? problem.title : "Error",
+        detail: typeof problem.detail === "string" ? problem.detail : response.statusText || "Request failed",
+        requestId,
+        ...(typeof problem.code === "string" ? { code: problem.code } : {}),
+        ...(Array.isArray(problem.invalid_params) ? { invalid_params: problem.invalid_params } : {}),
+      },
+    },
+    true
+  );
+}
diff --git a/apps/web/modules/mcp/server.ts b/apps/web/modules/mcp/server.ts
new file mode 100644
index 000000000000..c30b1bc8858b
--- /dev/null
+++ b/apps/web/modules/mcp/server.ts
@@ -0,0 +1,23 @@
+import "server-only";
+import { createMcpHandler } from "mcp-handler";
+import { MCP_SERVER_NAME, MCP_SERVER_VERSION } from "./constants";
+import { registerSurveyTools } from "./tools/surveys";
+
+export const mcpHandler = createMcpHandler(
+  (server) => {
+    registerSurveyTools(server);
+  },
+  {
+    serverInfo: {
+      name: MCP_SERVER_NAME,
+      version: MCP_SERVER_VERSION,
+    },
+  },
+  {
+    basePath: "/api",
+    disableSse: true,
+    maxDuration: 60,
+    sessionIdGenerator: undefined,
+    verboseLogs: false,
+  }
+);
diff --git a/apps/web/modules/mcp/tools/schemas.ts b/apps/web/modules/mcp/tools/schemas.ts
new file mode 100644
index 000000000000..ad6858e4804e
--- /dev/null
+++ b/apps/web/modules/mcp/tools/schemas.ts
@@ -0,0 +1,90 @@
+import { z } from "zod";
+import type { TV3CreateSurveyBody, TV3SurveyValidationRequestBody } from "@/app/api/v3/surveys/schemas";
+import { ZV3CreateSurveyBody, ZV3SurveyValidationRequestBody } from "@/app/api/v3/surveys/schemas";
+import { ZId } from "@formbricks/types/common";
+import { ZSurveyFilters, ZSurveyStatus, ZSurveyType } from "@formbricks/types/surveys/types";
+
+export const ZMcpListSurveysInput = z.object({
+  workspaceId: ZId.describe("Workspace ID whose surveys should be listed."),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .describe("Maximum number of surveys to return. Defaults to 20.")
+    .default(20),
+  cursor: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Opaque pagination cursor from a previous list_surveys response."),
+  includeTotalCount: z
+    .boolean()
+    .describe("Whether to include the total matching survey count in the response metadata. Defaults to true.")
+    .default(true),
+  filter: z
+    .object({
+      name: z
+        .object({
+          contains: z.string().max(512).optional().describe("Case-insensitive survey name substring."),
+        })
+        .describe("Filter by survey name.")
+        .optional(),
+      status: z
+        .object({
+          in: z
+            .array(ZSurveyStatus)
+            .optional()
+            .describe("Survey statuses to include, for example draft or inProgress."),
+        })
+        .describe("Filter by survey status.")
+        .optional(),
+      type: z
+        .object({
+          in: z.array(ZSurveyType).optional().describe("Survey types to include, for example link."),
+        })
+        .describe("Filter by survey type.")
+        .optional(),
+    })
+    .describe("Optional supported v3 survey filters.")
+    .optional(),
+  sortBy: ZSurveyFilters.shape.sortBy
+    .optional()
+    .describe("Sort field for pagination. Defaults to the v3 API default of updatedAt."),
+});
+
+export const ZMcpGetSurveyInput = z.object({
+  surveyId: z.cuid2().describe("Survey ID to fetch."),
+  lang: z
+    .array(z.string().trim().min(1))
+    .optional()
+    .describe("Optional language codes or configured aliases used to filter translatable survey fields."),
+});
+
+export const ZMcpCreateSurveyInput = ZV3CreateSurveyBody.describe(
+  "Create a block-based link survey using the v3 survey document contract."
+);
+
+export const ZMcpPatchSurveyInput = z.object({
+  surveyId: z.cuid2().describe("Survey ID to update."),
+  data: z
+    .record(z.string(), z.unknown())
+    .describe(
+      "Strict top-level v3 survey patch payload. Omitted top-level fields are preserved; provided objects and arrays replace that whole subtree."
+    ),
+});
+
+export const ZMcpValidateSurveyInput = ZV3SurveyValidationRequestBody.describe(
+  "Validate a v3 survey create or patch payload without writing survey changes."
+);
+
+export const ZMcpDeleteSurveyInput = z.object({
+  surveyId: z.cuid2().describe("Survey ID to delete."),
+});
+
+export type TMcpListSurveysInput = z.infer<typeof ZMcpListSurveysInput>;
+export type TMcpGetSurveyInput = z.infer<typeof ZMcpGetSurveyInput>;
+export type TMcpCreateSurveyInput = TV3CreateSurveyBody;
+export type TMcpPatchSurveyInput = z.infer<typeof ZMcpPatchSurveyInput>;
+export type TMcpValidateSurveyInput = TV3SurveyValidationRequestBody;
+export type TMcpDeleteSurveyInput = z.infer<typeof ZMcpDeleteSurveyInput>;
diff --git a/apps/web/modules/mcp/tools/surveys.test.ts b/apps/web/modules/mcp/tools/surveys.test.ts
new file mode 100644
index 000000000000..3c81cc5f7720
--- /dev/null
+++ b/apps/web/modules/mcp/tools/surveys.test.ts
@@ -0,0 +1,430 @@
+import { ApiKeyPermission } from "@prisma/client";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import { buildV3AuditLog, queueV3AuditLog } from "@/app/api/v3/lib/audit";
+import {
+  createdResponse,
+  noContentResponse,
+  problemBadRequest,
+  problemForbidden,
+  successListResponse,
+  successResponse,
+} from "@/app/api/v3/lib/response";
+import {
+  createV3SurveyResponse,
+  deleteV3Survey,
+  getV3Survey,
+  listV3Surveys,
+  patchV3SurveyResponse,
+  validateV3Survey,
+} from "@/app/api/v3/surveys/lib/operations";
+import { buildListSurveysSearchParams, registerSurveyTools } from "./surveys";
+
+vi.mock("@/app/api/v3/surveys/lib/operations", () => ({
+  createV3SurveyResponse: vi.fn(),
+  deleteV3Survey: vi.fn(),
+  getV3Survey: vi.fn(),
+  listV3Surveys: vi.fn(),
+  patchV3SurveyResponse: vi.fn(),
+  validateV3Survey: vi.fn(),
+}));
+
+vi.mock("@/app/api/v3/lib/audit", () => ({
+  buildV3AuditLog: vi.fn(),
+  queueV3AuditLog: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("@formbricks/logger", () => ({
+  logger: {
+    withContext: vi.fn(() => ({
+      error: vi.fn(),
+      warn: vi.fn(),
+    })),
+  },
+}));
+
+const apiKeyAuth = {
+  type: "apiKey" as const,
+  apiKeyId: "key_1",
+  organizationId: "org_1",
+  organizationAccess: {
+    accessControl: { read: true, write: true },
+  },
+  workspacePermissions: [
+    {
+      workspaceId: "clxx1234567890123456789012",
+      workspaceName: "Workspace",
+      permission: ApiKeyPermission.write,
+    },
+  ],
+};
+
+const authInfo = {
+  token: "key_1",
+  clientId: "key_1",
+  scopes: ["surveys:read", "surveys:write"],
+  extra: {
+    formbricksAuthentication: apiKeyAuth,
+    requestId: "req_tool",
+  },
+};
+
+function createToolServer() {
+  const tools = new Map<
+    string,
+    {
+      config: Record<string, unknown>;
+      handler: (input: any, extra: any) => Promise<any>;
+    }
+  >();
+  const server = {
+    registerTool: vi.fn((name: string, config: Record<string, unknown>, handler: any) => {
+      tools.set(name, { config, handler });
+    }),
+  };
+
+  registerSurveyTools(server as any);
+  return { server, tools };
+}
+
+describe("buildListSurveysSearchParams", () => {
+  test("applies defensive defaults when optional defaults are not materialized", () => {
+    const params = buildListSurveysSearchParams({
+      workspaceId: "clxx1234567890123456789012",
+    } as unknown as Parameters<typeof buildListSurveysSearchParams>[0]);
+
+    expect(params.get("limit")).toBe("20");
+    expect(params.has("includeTotalCount")).toBe(false);
+  });
+
+  test("maps structured MCP filters to v3 query parameters", () => {
+    const params = buildListSurveysSearchParams({
+      workspaceId: "clxx1234567890123456789012",
+      limit: 50,
+      cursor: "cursor_1",
+      includeTotalCount: false,
+      sortBy: "updatedAt",
+      filter: {
+        name: { contains: "Onboarding" },
+        status: { in: ["draft", "inProgress"] },
+        type: { in: ["link"] },
+      },
+    });
+
+    expect(params.get("workspaceId")).toBe("clxx1234567890123456789012");
+    expect(params.get("limit")).toBe("50");
+    expect(params.get("cursor")).toBe("cursor_1");
+    expect(params.get("includeTotalCount")).toBe("false");
+    expect(params.get("sortBy")).toBe("updatedAt");
+    expect(params.get("filter[name][contains]")).toBe("Onboarding");
+    expect(params.getAll("filter[status][in]")).toEqual(["draft", "inProgress"]);
+    expect(params.getAll("filter[type][in]")).toEqual(["link"]);
+  });
+});
+
+describe("registerSurveyTools", () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    vi.mocked(queueV3AuditLog).mockResolvedValue(undefined);
+  });
+
+  test("registers survey tools with planning annotations", () => {
+    const { server, tools } = createToolServer();
+
+    expect(server.registerTool).toHaveBeenCalledTimes(6);
+    expect(tools.get("list_surveys")?.config).toMatchObject({
+      title: "List surveys",
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+      },
+    });
+    expect(tools.get("get_survey")?.config).toMatchObject({
+      title: "Get survey",
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+      },
+    });
+    expect(tools.get("create_survey")?.config).toMatchObject({
+      title: "Create survey",
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+      },
+    });
+    expect(tools.get("validate_survey")?.config).toMatchObject({
+      title: "Validate survey",
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+      },
+    });
+    expect(tools.get("patch_survey")?.config).toMatchObject({
+      title: "Patch survey",
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+      },
+    });
+    expect(tools.get("delete_survey")?.config).toMatchObject({
+      title: "Delete survey",
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+      },
+    });
+  });
+
+  test("list_surveys calls the shared v3 list operation and returns structured content", async () => {
+    const { tools } = createToolServer();
+    vi.mocked(listV3Surveys).mockResolvedValue(
+      successListResponse(
+        [{ id: "survey_1" }],
+        { limit: 20, nextCursor: null, totalCount: 1 },
+        { requestId: "req_tool" }
+      )
+    );
+
+    const result = await tools.get("list_surveys")!.handler(
+      {
+        workspaceId: "clxx1234567890123456789012",
+        limit: 20,
+        includeTotalCount: true,
+      },
+      { authInfo }
+    );
+
+    expect(listV3Surveys).toHaveBeenCalledWith(
+      expect.objectContaining({
+        authentication: apiKeyAuth,
+        requestId: "req_tool",
+        instance: "/api/mcp",
+      })
+    );
+    expect(result.structuredContent).toEqual({
+      data: [{ id: "survey_1" }],
+      meta: { limit: 20, nextCursor: null, totalCount: 1 },
+      requestId: "req_tool",
+    });
+  });
+
+  test("list_surveys maps v3 problem responses to MCP tool errors", async () => {
+    const { tools } = createToolServer();
+    vi.mocked(listV3Surveys).mockResolvedValue(
+      problemBadRequest("req_bad", "Invalid query parameters", {
+        instance: "/api/mcp",
+        invalid_params: [{ name: "limit", reason: "Too big" }],
+      })
+    );
+
+    const result = await tools.get("list_surveys")!.handler(
+      {
+        workspaceId: "clxx1234567890123456789012",
+        limit: 101,
+        includeTotalCount: true,
+      },
+      { authInfo }
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.structuredContent.error).toMatchObject({
+      status: 400,
+      code: "bad_request",
+      requestId: "req_bad",
+      invalid_params: [{ name: "limit", reason: "Too big" }],
+    });
+  });
+
+  test("get_survey calls the shared v3 get operation", async () => {
+    const { tools } = createToolServer();
+    vi.mocked(getV3Survey).mockResolvedValue(
+      successResponse({ id: "clxx1234567890123456789012" }, { requestId: "req_tool" })
+    );
+
+    const result = await tools.get("get_survey")!.handler(
+      {
+        surveyId: "clxx1234567890123456789012",
+        lang: ["en-US"],
+      },
+      { authInfo }
+    );
+
+    expect(getV3Survey).toHaveBeenCalledWith({
+      surveyId: "clxx1234567890123456789012",
+      lang: ["en-US"],
+      authentication: apiKeyAuth,
+      requestId: "req_tool",
+      instance: "/api/mcp",
+    });
+    expect(result.structuredContent).toEqual({
+      data: { id: "clxx1234567890123456789012" },
+      requestId: "req_tool",
+    });
+  });
+
+  test("create_survey queues a successful audit log", async () => {
+    const { tools } = createToolServer();
+    const auditLog = { status: "failure" };
+    const createBody = {
+      workspaceId: "clxx1234567890123456789012",
+      name: "New survey",
+      type: "link",
+      status: "draft",
+      metadata: {},
+      defaultLanguage: "en-US",
+      languages: [],
+      welcomeCard: { enabled: false },
+      blocks: [],
+      endings: [],
+      hiddenFields: { enabled: false, fieldIds: [] },
+      variables: [],
+    };
+    vi.mocked(buildV3AuditLog).mockReturnValue(auditLog as any);
+    vi.mocked(createV3SurveyResponse).mockResolvedValue(
+      createdResponse({ id: "clxx1234567890123456789012" }, { requestId: "req_tool", location: "/survey" })
+    );
+
+    const result = await tools.get("create_survey")!.handler(createBody, { authInfo });
+
+    expect(buildV3AuditLog).toHaveBeenCalledWith(apiKeyAuth, "created", "survey", "/api/mcp");
+    expect(createV3SurveyResponse).toHaveBeenCalledWith({
+      body: createBody,
+      authentication: apiKeyAuth,
+      requestId: "req_tool",
+      instance: "/api/mcp",
+      auditLog,
+    });
+    expect(auditLog.status).toBe("success");
+    expect(queueV3AuditLog).toHaveBeenCalledWith(auditLog, "req_tool", expect.any(Object));
+    expect(result.structuredContent).toEqual({
+      data: { id: "clxx1234567890123456789012" },
+      requestId: "req_tool",
+    });
+  });
+
+  test("validate_survey calls the shared v3 validation operation without audit logging", async () => {
+    const { tools } = createToolServer();
+    const validationBody = {
+      operation: "create" as const,
+      data: {
+        workspaceId: "clxx1234567890123456789012",
+        name: "New survey",
+      },
+    };
+    vi.mocked(validateV3Survey).mockResolvedValue(
+      successResponse({ valid: true, operation: "create", invalid_params: [] }, { requestId: "req_tool" })
+    );
+
+    const result = await tools.get("validate_survey")!.handler(validationBody, { authInfo });
+
+    expect(validateV3Survey).toHaveBeenCalledWith({
+      body: validationBody,
+      authentication: apiKeyAuth,
+      requestId: "req_tool",
+      instance: "/api/mcp",
+    });
+    expect(buildV3AuditLog).not.toHaveBeenCalled();
+    expect(queueV3AuditLog).not.toHaveBeenCalled();
+    expect(result.structuredContent).toEqual({
+      data: { valid: true, operation: "create", invalid_params: [] },
+      requestId: "req_tool",
+    });
+  });
+
+  test("patch_survey queues a successful audit log", async () => {
+    const { tools } = createToolServer();
+    const auditLog = { status: "failure" };
+    const patchInput = {
+      surveyId: "clxx1234567890123456789012",
+      data: {
+        name: "Updated survey",
+      },
+    };
+    vi.mocked(buildV3AuditLog).mockReturnValue(auditLog as any);
+    vi.mocked(patchV3SurveyResponse).mockResolvedValue(
+      successResponse({ id: "clxx1234567890123456789012", name: "Updated survey" }, { requestId: "req_tool" })
+    );
+
+    const result = await tools.get("patch_survey")!.handler(patchInput, { authInfo });
+
+    expect(buildV3AuditLog).toHaveBeenCalledWith(apiKeyAuth, "updated", "survey", "/api/mcp");
+    expect(patchV3SurveyResponse).toHaveBeenCalledWith({
+      surveyId: "clxx1234567890123456789012",
+      body: {
+        name: "Updated survey",
+      },
+      authentication: apiKeyAuth,
+      requestId: "req_tool",
+      instance: "/api/mcp",
+      auditLog,
+    });
+    expect(auditLog.status).toBe("success");
+    expect(queueV3AuditLog).toHaveBeenCalledWith(auditLog, "req_tool", expect.any(Object));
+    expect(result.structuredContent).toEqual({
+      data: { id: "clxx1234567890123456789012", name: "Updated survey" },
+      requestId: "req_tool",
+    });
+  });
+
+  test("delete_survey queues a successful audit log", async () => {
+    const { tools } = createToolServer();
+    const auditLog = { status: "failure" };
+    vi.mocked(buildV3AuditLog).mockReturnValue(auditLog as any);
+    vi.mocked(deleteV3Survey).mockResolvedValue(noContentResponse({ requestId: "req_tool" }));
+
+    const result = await tools.get("delete_survey")!.handler(
+      {
+        surveyId: "clxx1234567890123456789012",
+      },
+      { authInfo }
+    );
+
+    expect(deleteV3Survey).toHaveBeenCalledWith({
+      surveyId: "clxx1234567890123456789012",
+      authentication: apiKeyAuth,
+      requestId: "req_tool",
+      instance: "/api/mcp",
+      auditLog,
+    });
+    expect(auditLog.status).toBe("success");
+    expect(queueV3AuditLog).toHaveBeenCalledWith(auditLog, "req_tool", expect.any(Object));
+    expect(result.structuredContent).toEqual({
+      requestId: "req_tool",
+    });
+  });
+
+  test("delete_survey preserves forbidden errors without leaking resource existence", async () => {
+    const { tools } = createToolServer();
+    const auditLog = { status: "failure" };
+    vi.mocked(buildV3AuditLog).mockReturnValue(auditLog as any);
+    vi.mocked(deleteV3Survey).mockResolvedValue(
+      problemForbidden("req_forbidden", "You are not authorized to access this resource", "/api/mcp")
+    );
+
+    const result = await tools.get("delete_survey")!.handler(
+      {
+        surveyId: "clxx1234567890123456789012",
+      },
+      { authInfo }
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.structuredContent.error).toMatchObject({
+      status: 403,
+      code: "forbidden",
+      detail: "You are not authorized to access this resource",
+      requestId: "req_forbidden",
+    });
+    expect(auditLog).toMatchObject({
+      status: "failure",
+      eventId: "req_tool",
+    });
+    expect(queueV3AuditLog).toHaveBeenCalledWith(auditLog, "req_tool", expect.any(Object));
+  });
+});
diff --git a/apps/web/modules/mcp/tools/surveys.ts b/apps/web/modules/mcp/tools/surveys.ts
new file mode 100644
index 000000000000..ea9c408e1fbc
--- /dev/null
+++ b/apps/web/modules/mcp/tools/surveys.ts
@@ -0,0 +1,293 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { logger } from "@formbricks/logger";
+import { buildV3AuditLog, queueV3AuditLog } from "@/app/api/v3/lib/audit";
+import {
+  createV3SurveyResponse,
+  deleteV3Survey,
+  getV3Survey,
+  listV3Surveys,
+  patchV3SurveyResponse,
+  validateV3Survey,
+} from "@/app/api/v3/surveys/lib/operations";
+import { MCP_API_ROUTE } from "@/modules/mcp/constants";
+import { getMcpAuthentication, getMcpRequestId } from "../auth";
+import { responseToMcpToolResult } from "../errors";
+import {
+  type TMcpCreateSurveyInput,
+  type TMcpDeleteSurveyInput,
+  type TMcpGetSurveyInput,
+  type TMcpListSurveysInput,
+  type TMcpPatchSurveyInput,
+  type TMcpValidateSurveyInput,
+  ZMcpCreateSurveyInput,
+  ZMcpDeleteSurveyInput,
+  ZMcpGetSurveyInput,
+  ZMcpListSurveysInput,
+  ZMcpPatchSurveyInput,
+  ZMcpValidateSurveyInput,
+} from "./schemas";
+
+export function buildListSurveysSearchParams(input: TMcpListSurveysInput): URLSearchParams {
+  const searchParams = new URLSearchParams();
+
+  searchParams.set("workspaceId", input.workspaceId);
+  searchParams.set("limit", String(input.limit ?? 20));
+
+  if (input.cursor) {
+    searchParams.set("cursor", input.cursor);
+  }
+
+  if ((input.includeTotalCount ?? true) === false) {
+    searchParams.set("includeTotalCount", "false");
+  }
+
+  if (input.sortBy) {
+    searchParams.set("sortBy", input.sortBy);
+  }
+
+  if (input.filter?.name?.contains) {
+    searchParams.set("filter[name][contains]", input.filter.name.contains);
+  }
+
+  input.filter?.status?.in?.forEach((status) => {
+    searchParams.append("filter[status][in]", status);
+  });
+
+  input.filter?.type?.in?.forEach((type) => {
+    searchParams.append("filter[type][in]", type);
+  });
+
+  return searchParams;
+}
+
+export function registerSurveyTools(server: McpServer): void {
+  server.registerTool(
+    "list_surveys",
+    {
+      title: "List surveys",
+      description: "List surveys in a Formbricks workspace using the v3 Surveys API contract.",
+      inputSchema: ZMcpListSurveysInput.shape,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (input: TMcpListSurveysInput, extra) => {
+      const requestId = getMcpRequestId(extra.authInfo);
+      const response = await listV3Surveys({
+        searchParams: buildListSurveysSearchParams(input),
+        authentication: getMcpAuthentication(extra.authInfo),
+        requestId,
+        instance: MCP_API_ROUTE,
+      });
+
+      return await responseToMcpToolResult(response, requestId);
+    }
+  );
+
+  server.registerTool(
+    "get_survey",
+    {
+      title: "Get survey",
+      description: "Get one Formbricks survey using the v3 Surveys API contract.",
+      inputSchema: ZMcpGetSurveyInput.shape,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (input: TMcpGetSurveyInput, extra) => {
+      const requestId = getMcpRequestId(extra.authInfo);
+      const response = await getV3Survey({
+        surveyId: input.surveyId,
+        lang: input.lang,
+        authentication: getMcpAuthentication(extra.authInfo),
+        requestId,
+        instance: MCP_API_ROUTE,
+      });
+
+      return await responseToMcpToolResult(response, requestId);
+    }
+  );
+
+  server.registerTool(
+    "create_survey",
+    {
+      title: "Create survey",
+      description: "Create a Formbricks link survey using the v3 Surveys API contract.",
+      inputSchema: ZMcpCreateSurveyInput,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+      },
+    },
+    async (input: TMcpCreateSurveyInput, extra) => {
+      const requestId = getMcpRequestId(extra.authInfo);
+      const authentication = getMcpAuthentication(extra.authInfo);
+      const log = logger.withContext({ requestId, workspaceId: input.workspaceId });
+      const auditLog = buildV3AuditLog(authentication, "created", "survey", MCP_API_ROUTE);
+
+      try {
+        const response = await createV3SurveyResponse({
+          body: input,
+          authentication,
+          requestId,
+          instance: MCP_API_ROUTE,
+          auditLog,
+        });
+
+        if (auditLog) {
+          if (response.ok) {
+            auditLog.status = "success";
+          } else {
+            auditLog.eventId = requestId;
+          }
+        }
+
+        await queueV3AuditLog(auditLog, requestId, log);
+        return await responseToMcpToolResult(response, requestId);
+      } catch (error) {
+        if (auditLog) {
+          auditLog.eventId = requestId;
+          await queueV3AuditLog(auditLog, requestId, log);
+        }
+
+        throw error;
+      }
+    }
+  );
+
+  server.registerTool(
+    "validate_survey",
+    {
+      title: "Validate survey",
+      description: "Validate a v3 survey create or patch payload without writing survey changes.",
+      inputSchema: ZMcpValidateSurveyInput,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (input: TMcpValidateSurveyInput, extra) => {
+      const requestId = getMcpRequestId(extra.authInfo);
+      const response = await validateV3Survey({
+        body: input,
+        authentication: getMcpAuthentication(extra.authInfo),
+        requestId,
+        instance: MCP_API_ROUTE,
+      });
+
+      return await responseToMcpToolResult(response, requestId);
+    }
+  );
+
+  server.registerTool(
+    "patch_survey",
+    {
+      title: "Patch survey",
+      description: [
+        "Update a Formbricks survey using the v3 Surveys API patch contract.",
+        "Provided top-level arrays and objects replace that whole subtree.",
+      ].join(" "),
+      inputSchema: ZMcpPatchSurveyInput.shape,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+      },
+    },
+    async (input: TMcpPatchSurveyInput, extra) => {
+      const requestId = getMcpRequestId(extra.authInfo);
+      const authentication = getMcpAuthentication(extra.authInfo);
+      const log = logger.withContext({ requestId, surveyId: input.surveyId });
+      const auditLog = buildV3AuditLog(authentication, "updated", "survey", MCP_API_ROUTE);
+
+      try {
+        const response = await patchV3SurveyResponse({
+          surveyId: input.surveyId,
+          body: input.data,
+          authentication,
+          requestId,
+          instance: MCP_API_ROUTE,
+          auditLog,
+        });
+
+        if (auditLog) {
+          if (response.ok) {
+            auditLog.status = "success";
+          } else {
+            auditLog.eventId = requestId;
+          }
+        }
+
+        await queueV3AuditLog(auditLog, requestId, log);
+        return await responseToMcpToolResult(response, requestId);
+      } catch (error) {
+        if (auditLog) {
+          auditLog.eventId = requestId;
+          await queueV3AuditLog(auditLog, requestId, log);
+        }
+
+        throw error;
+      }
+    }
+  );
+
+  server.registerTool(
+    "delete_survey",
+    {
+      title: "Delete survey",
+      description: "Delete a Formbricks survey using the v3 Surveys API contract.",
+      inputSchema: ZMcpDeleteSurveyInput.shape,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+      },
+    },
+    async (input: TMcpDeleteSurveyInput, extra) => {
+      const requestId = getMcpRequestId(extra.authInfo);
+      const authentication = getMcpAuthentication(extra.authInfo);
+      const log = logger.withContext({ requestId, surveyId: input.surveyId });
+      const auditLog = buildV3AuditLog(authentication, "deleted", "survey", MCP_API_ROUTE);
+
+      try {
+        const response = await deleteV3Survey({
+          surveyId: input.surveyId,
+          authentication,
+          requestId,
+          instance: MCP_API_ROUTE,
+          auditLog,
+        });
+
+        if (auditLog) {
+          if (response.ok) {
+            auditLog.status = "success";
+          } else {
+            auditLog.eventId = requestId;
+          }
+        }
+
+        await queueV3AuditLog(auditLog, requestId, log);
+        return await responseToMcpToolResult(response, requestId);
+      } catch (error) {
+        if (auditLog) {
+          auditLog.eventId = requestId;
+          await queueV3AuditLog(auditLog, requestId, log);
+        }
+
+        throw error;
+      }
+    }
+  );
+}
diff --git a/apps/web/package.json b/apps/web/package.json
index 121720b6ebd9..180c8121e743 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -21,8 +21,8 @@
     "i18n:generate": "npx lingo.dev@latest run && npx lingo.dev@latest lockfile --force"
   },
   "dependencies": {
-    "@cubejs-client/core": "1.6.6",
     "@boxyhq/saml-jackson": "26.2.0",
+    "@cubejs-client/core": "1.6.6",
     "@dnd-kit/core": "6.3.1",
     "@dnd-kit/modifiers": "9.0.0",
     "@dnd-kit/sortable": "10.0.0",
@@ -33,8 +33,8 @@
     "@formbricks/email": "workspace:*",
     "@formbricks/hub": "0.5.0",
     "@formbricks/i18n-utils": "workspace:*",
-    "@formbricks/js-core": "workspace:*",
     "@formbricks/jobs": "workspace:*",
+    "@formbricks/js-core": "workspace:*",
     "@formbricks/logger": "workspace:*",
     "@formbricks/storage": "workspace:*",
     "@formbricks/surveys": "workspace:*",
@@ -48,6 +48,7 @@
     "@lexical/react": "0.41.0",
     "@lexical/rich-text": "0.41.0",
     "@lexical/table": "0.41.0",
+    "@modelcontextprotocol/sdk": "1.26.0",
     "@next-auth/prisma-adapter": "1.0.7",
     "@opentelemetry/auto-instrumentations-node": "0.75.0",
     "@opentelemetry/exporter-metrics-otlp-http": "0.217.0",
@@ -100,6 +101,7 @@
     "lexical": "0.41.0",
     "lucide-react": "0.577.0",
     "markdown-it": "14.1.1",
+    "mcp-handler": "1.1.0",
     "next": "16.2.6",
     "next-auth": "4.24.13",
     "next-safe-action": "8.1.10",
@@ -116,8 +118,8 @@
     "react-colorful": "5.6.2",
     "react-confetti": "6.4.0",
     "react-day-picker": "9.14.0",
-    "react-grid-layout": "2.2.2",
     "react-dom": "19.2.6",
+    "react-grid-layout": "2.2.2",
     "react-hook-form": "7.71.2",
     "react-hot-toast": "2.6.0",
     "react-i18next": "16.5.8",
diff --git a/docs/development/technical-handbook/mcp-server.mdx b/docs/development/technical-handbook/mcp-server.mdx
new file mode 100644
index 000000000000..a5dc0d2a543c
--- /dev/null
+++ b/docs/development/technical-handbook/mcp-server.mdx
@@ -0,0 +1,512 @@
+---
+title: "MCP Server"
+description: "Configure and use the Formbricks v3 Surveys MCP server"
+icon: "bot"
+---
+
+## Overview
+
+The Formbricks MCP server exposes a small v3 Surveys tool surface for AI agents. It runs inside the
+Formbricks web app at `/api/mcp` and reuses the same v3 Surveys API authentication, authorization,
+rate limiting, response handling, and audit logging paths as the REST routes.
+
+<Note>
+  This page documents the current API-key MVP. OAuth-based MCP authorization is not part of the current
+  implementation.
+</Note>
+
+## Endpoint
+
+Use the streamable HTTP MCP endpoint on the Formbricks app:
+
+```text
+https://app.formbricks.com/api/mcp
+```
+
+For local development:
+
+```text
+http://localhost:3000/api/mcp
+```
+
+The route supports `POST` requests, runs with the Next.js Node.js runtime, and sets private no-store
+response headers. Browser-origin MCP requests must come from the configured public Formbricks origin.
+
+## Authentication
+
+Authenticate with a Formbricks API key in a request header:
+
+```http
+Authorization: Bearer fbk_...
+```
+
+or:
+
+```http
+x-api-key: fbk_...
+```
+
+Do not pass credentials in the query string. The MCP route rejects query credential names such as
+`api_key`, `x-api-key`, `access_token`, `token`, and `authorization` case-insensitively.
+
+API key permissions are enforced through the same workspace access checks as the v3 REST API:
+
+| Tool              | Minimum Workspace Permission                                        |
+| ----------------- | ------------------------------------------------------------------- |
+| `list_surveys`    | `read`                                                              |
+| `get_survey`      | `read`                                                              |
+| `create_survey`   | `write` or `manage`                                                 |
+| `validate_survey` | `write` or `manage` when the validation request checks write access |
+| `patch_survey`    | `write` or `manage`                                                 |
+| `delete_survey`   | `write` or `manage`                                                 |
+
+<Warning>
+  Store MCP API keys as environment variables or client secrets. Do not commit API keys into MCP client config
+  files.
+</Warning>
+
+## Local Setup
+
+Start Formbricks and prepare the database:
+
+```bash
+pnpm db:up
+pnpm db:migrate:dev
+pnpm --filter @formbricks/web dev
+```
+
+Create an API key in the Formbricks app with access to the target workspace. Use the least privileged
+permission needed by the agent workflow.
+
+Verify that the MCP endpoint can list tools:
+
+```bash
+export FORMBRICKS_MCP_API_KEY="fbk_..."
+
+curl -sS -X POST http://localhost:3000/api/mcp \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $FORMBRICKS_MCP_API_KEY" \
+  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
+```
+
+## Codex Configuration
+
+Store the API key in the shell environment:
+
+```bash
+export FORMBRICKS_MCP_API_KEY="fbk_..."
+```
+
+For Codex Desktop on macOS, persist the value in the launch environment and restart Codex Desktop:
+
+```bash
+launchctl setenv FORMBRICKS_MCP_API_KEY "fbk_..."
+```
+
+Register the local MCP server:
+
+```bash
+codex mcp add formbricks-local \
+  --url http://localhost:3000/api/mcp \
+  --bearer-token-env-var FORMBRICKS_MCP_API_KEY
+```
+
+Equivalent Codex config:
+
+```toml
+[mcp_servers.formbricks-local]
+url = "http://localhost:3000/api/mcp"
+bearer_token_env_var = "FORMBRICKS_MCP_API_KEY"
+```
+
+Verify the registration:
+
+```bash
+codex mcp list
+codex mcp get formbricks-local
+```
+
+Then ask Codex to use the configured server:
+
+```text
+Use the formbricks-local MCP server to list surveys for workspace clxx1234567890123456789012.
+```
+
+## Claude Configuration
+
+### Claude Code
+
+Set the API key:
+
+```bash
+export FORMBRICKS_MCP_API_KEY="fbk_..."
+```
+
+Add the HTTP MCP server:
+
+```bash
+claude mcp add --transport http formbricks-local http://localhost:3000/api/mcp \
+  --header "Authorization: Bearer $FORMBRICKS_MCP_API_KEY"
+```
+
+Verify it:
+
+```bash
+claude mcp list
+claude mcp get formbricks-local
+```
+
+For a project-shared Claude Code configuration, use `.mcp.json` and keep the API key outside git:
+
+```json
+{
+  "mcpServers": {
+    "formbricks-local": {
+      "headers": {
+        "Authorization": "Bearer ${FORMBRICKS_MCP_API_KEY}"
+      },
+      "type": "http",
+      "url": "http://localhost:3000/api/mcp"
+    }
+  }
+}
+```
+
+Claude Code will fail to parse this config if `FORMBRICKS_MCP_API_KEY` is not set.
+
+### Claude Desktop
+
+If the installed Claude Desktop build supports remote HTTP MCP server entries, add the same server
+definition to the Claude Desktop config file and restart Claude Desktop.
+
+macOS config path:
+
+```text
+~/Library/Application Support/Claude/claude_desktop_config.json
+```
+
+Example config:
+
+```json
+{
+  "mcpServers": {
+    "formbricks-local": {
+      "headers": {
+        "Authorization": "Bearer ${FORMBRICKS_MCP_API_KEY}"
+      },
+      "type": "http",
+      "url": "http://localhost:3000/api/mcp"
+    }
+  }
+}
+```
+
+Set the API key in the Desktop launch environment before opening Claude Desktop:
+
+```bash
+launchctl setenv FORMBRICKS_MCP_API_KEY "fbk_..."
+```
+
+If a Claude Desktop version only supports stdio MCP servers, use Claude Code for the HTTP endpoint or
+add a local stdio-to-HTTP bridge.
+
+## Tool Responses
+
+Tool results include both `structuredContent` and a text content item containing the same JSON string.
+Successful results mirror the v3 REST response body and add `requestId` for correlation.
+
+Errors are returned as MCP error tool results with a structured v3 problem payload:
+
+```json
+{
+  "error": {
+    "code": "bad_request",
+    "detail": "Invalid survey document",
+    "invalid_params": [
+      {
+        "name": "blocks.0.elements.0.headline",
+        "reason": "Required"
+      }
+    ],
+    "requestId": "req_...",
+    "status": 400,
+    "title": "Bad Request"
+  }
+}
+```
+
+## Available Tools
+
+### list_surveys
+
+Lists surveys in one workspace. The tool is read-only and idempotent.
+
+Input:
+
+```json
+{
+  "cursor": "opaque-cursor-from-previous-response",
+  "filter": {
+    "name": {
+      "contains": "feedback"
+    },
+    "status": {
+      "in": ["draft", "inProgress"]
+    },
+    "type": {
+      "in": ["link"]
+    }
+  },
+  "includeTotalCount": true,
+  "limit": 20,
+  "sortBy": "updatedAt",
+  "workspaceId": "clxx1234567890123456789012"
+}
+```
+
+Output:
+
+```json
+{
+  "data": [
+    {
+      "createdAt": "2026-04-21T10:00:00.000Z",
+      "creator": {
+        "name": "Ada Lovelace"
+      },
+      "id": "clsv1234567890123456789012",
+      "name": "Product Feedback",
+      "responseCount": 0,
+      "status": "draft",
+      "type": "link",
+      "updatedAt": "2026-04-21T11:00:00.000Z",
+      "workspaceId": "clxx1234567890123456789012"
+    }
+  ],
+  "meta": {
+    "limit": 20,
+    "nextCursor": null,
+    "totalCount": 1
+  },
+  "requestId": "req_..."
+}
+```
+
+### get_survey
+
+Gets one survey by ID. The tool is read-only and idempotent.
+
+Input:
+
+```json
+{
+  "lang": ["en-US"],
+  "surveyId": "clsv1234567890123456789012"
+}
+```
+
+`lang` is optional. When supplied, it filters translatable survey fields to the requested language
+codes or configured aliases.
+
+### create_survey
+
+Creates a block-based link survey using the v3 survey document contract. The tool writes data and is
+not idempotent.
+
+Input:
+
+```json
+{
+  "blocks": [
+    {
+      "elements": [
+        {
+          "headline": {
+            "de-DE": "Was sollen wir verbessern?",
+            "en-US": "What should we improve?"
+          },
+          "id": "satisfaction",
+          "required": true,
+          "type": "openText"
+        }
+      ],
+      "name": "Main Block"
+    }
+  ],
+  "defaultLanguage": "en-US",
+  "endings": [],
+  "hiddenFields": {
+    "enabled": false
+  },
+  "languages": [
+    {
+      "code": "de-DE",
+      "enabled": true
+    }
+  ],
+  "metadata": {
+    "cx_operation": "enterprise_onboarding",
+    "title": {
+      "de-DE": "Produktfeedback",
+      "en-US": "Product Feedback"
+    }
+  },
+  "name": "Product Feedback Survey",
+  "status": "draft",
+  "variables": [],
+  "welcomeCard": {
+    "enabled": true,
+    "headline": {
+      "de-DE": "Willkommen",
+      "en-US": "Welcome"
+    }
+  },
+  "workspaceId": "clxx1234567890123456789012"
+}
+```
+
+Output uses the same survey resource shape as `GET /api/v3/surveys/{surveyId}` and includes the MCP
+`requestId`.
+
+### validate_survey
+
+Validates a create or patch payload without writing survey changes. The tool is read-only and
+idempotent, but create validation still checks workspace write access when `workspaceId` is present.
+
+Create validation input:
+
+```json
+{
+  "data": {
+    "blocks": [
+      {
+        "elements": [
+          {
+            "headline": {
+              "en-US": "What should we improve?"
+            },
+            "id": "satisfaction",
+            "required": true,
+            "type": "openText"
+          }
+        ],
+        "name": "Main Block"
+      }
+    ],
+    "defaultLanguage": "en-US",
+    "name": "Product Feedback Survey",
+    "workspaceId": "clxx1234567890123456789012"
+  },
+  "operation": "create"
+}
+```
+
+Patch validation input:
+
+```json
+{
+  "data": {
+    "name": "Updated Product Feedback Survey"
+  },
+  "operation": "patch",
+  "surveyId": "clsv1234567890123456789012"
+}
+```
+
+Validation failures return `200` with `valid: false` and structured `invalid_params`, matching
+`POST /api/v3/surveys/validate`.
+
+### patch_survey
+
+Updates a survey by ID using the v3 survey patch contract. The tool writes data, can be
+destructive, and is not idempotent. Omitted top-level fields are preserved. Provided top-level
+objects and arrays replace that whole subtree, so omitted nested entries inside a provided subtree
+can be removed. The patch tool does not deep-merge nested objects and does not implement JSON Patch.
+
+<Note>
+  For agent workflows, fetch the current survey first, modify only the intended top-level fields, run
+  `validate_survey` with `operation: "patch"`, and then submit the same patch with `patch_survey`.
+</Note>
+
+Input:
+
+```json
+{
+  "data": {
+    "metadata": {
+      "cx_operation": "enterprise_onboarding",
+      "title": {
+        "en-US": "Updated Product Feedback"
+      }
+    },
+    "name": "Updated Product Feedback"
+  },
+  "surveyId": "clsv1234567890123456789012"
+}
+```
+
+Output uses the same survey resource shape as `GET /api/v3/surveys/{surveyId}` and includes the MCP
+`requestId`.
+
+### delete_survey
+
+Deletes one survey by ID. The tool is destructive, writes data, and is not idempotent.
+
+Input:
+
+```json
+{
+  "surveyId": "clsv1234567890123456789012"
+}
+```
+
+The v3 REST delete operation returns `204 No Content`. The MCP tool result contains the `requestId`
+so callers can correlate the audit trail:
+
+```json
+{
+  "requestId": "req_..."
+}
+```
+
+## Relationship To V3 Surveys API
+
+The MCP server does not run custom survey database queries. Each tool calls the shared server-only v3
+survey operations used by the REST routes:
+
+| MCP Tool          | REST Contract                       |
+| ----------------- | ----------------------------------- |
+| `list_surveys`    | `GET /api/v3/surveys`               |
+| `get_survey`      | `GET /api/v3/surveys/{surveyId}`    |
+| `create_survey`   | `POST /api/v3/surveys`              |
+| `validate_survey` | `POST /api/v3/surveys/validate`     |
+| `patch_survey`    | `PATCH /api/v3/surveys/{surveyId}`  |
+| `delete_survey`   | `DELETE /api/v3/surveys/{surveyId}` |
+
+When the v3 OpenAPI contract changes, update the MCP schemas and this page together. The hand-maintained
+v3 OpenAPI spec lives at `docs/api-v3-reference/openapi.yml`.
+
+## Limitations
+
+- Authentication is API-key only. OAuth-based MCP authorization is a separate follow-up.
+- The MCP server exposes only the v3 survey operations listed on this page.
+- Tool coverage depends on the current v3 Surveys REST endpoint coverage.
+- `create_survey` creates link surveys only. In-app survey creation and distribution settings are not
+  part of the current v3 create operation.
+- `patch_survey` follows the v3 PATCH contract: top-level partial document updates only, no JSON Patch,
+  and no nested deep merge. Provided top-level objects and arrays replace their whole subtree and can
+  remove omitted nested entries.
+- `validate_survey` validates payload shape and references; it does not create languages, survey
+  versions, or surveys.
+- Query-string credentials are rejected; use headers for API keys.
+- Large request bodies are rejected before the MCP handler using the same body-size policy as v3 APIs.
+
+## Implementation Files
+
+- `apps/web/app/api/mcp/route.ts`
+- `apps/web/modules/mcp/auth.ts`
+- `apps/web/modules/mcp/server.ts`
+- `apps/web/modules/mcp/tools/surveys.ts`
+- `apps/web/modules/mcp/tools/schemas.ts`
+- `apps/web/app/api/v3/surveys/lib/operations.ts`
diff --git a/docs/docs.json b/docs/docs.json
index 64dc44ac6765..be2483e75647 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -338,6 +338,7 @@
             "pages": [
               "development/technical-handbook/overview",
               "development/technical-handbook/api-gateway",
+              "development/technical-handbook/mcp-server",
               "development/technical-handbook/background-job-processing",
               "development/technical-handbook/cube-tenant-isolation",
               "development/technical-handbook/database-model",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a3338c3cd10e..53d97a94481e 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -203,6 +203,9 @@ importers:
       '@lexical/table':
         specifier: 0.41.0
         version: 0.41.0
+      '@modelcontextprotocol/sdk':
+        specifier: 1.26.0
+        version: 1.26.0(zod@4.3.6)
       '@next-auth/prisma-adapter':
         specifier: 1.0.7
         version: 1.0.7(@prisma/client@6.19.3(prisma@7.4.2(@types/react@19.2.14)(better-sqlite3@12.8.0)(magicast@0.3.5)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(typescript@5.9.3))(typescript@5.9.3))(next-auth@4.24.13(patch_hash=6b21102fce2caaca35f5e4e93ea07a0b4ff486cbf3d3b09a4173ad45977d5798)(next@16.2.6(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(nodemailer@8.0.7)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))
@@ -359,6 +362,9 @@ importers:
       markdown-it:
         specifier: 14.1.1
         version: 14.1.1
+      mcp-handler:
+        specifier: 1.1.0
+        version: 1.1.0(@modelcontextprotocol/sdk@1.26.0(zod@4.3.6))(next@16.2.6(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))
       next:
         specifier: 16.2.6
         version: 16.2.6(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -2831,6 +2837,16 @@ packages:
   '@microsoft/tsdoc@0.16.0':
     resolution: {integrity: sha512-xgAyonlVVS+q7Vc7qLW0UrJU7rSFcETRWsqdXZtjzRU8dF+6CkozTK4V4y1LwOX7j8r/vHphjDeMeGI4tNGeGA==}
 
+  '@modelcontextprotocol/sdk@1.26.0':
+    resolution: {integrity: sha512-Y5RmPncpiDtTXDbLKswIJzTqu2hyBKxTNsgKqKclDbhIgg1wgtf1fRuvxgTnRfcnxtvvgbIEcqUOzZrJ6iSReg==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@cfworker/json-schema': ^4.1.1
+      zod: ^3.25 || ^4.0
+    peerDependenciesMeta:
+      '@cfworker/json-schema':
+        optional: true
+
   '@mongodb-js/saslprep@1.4.4':
     resolution: {integrity: sha512-p7X/ytJDIdwUfFL/CLOhKgdfJe1Fa8uw9seJYvdOmnP9JBWGWHW69HkOixXS6Wy9yvGf1MbhcS6lVmrhy4jm2g==}
 
@@ -6608,6 +6624,10 @@ packages:
     resolution: {integrity: sha512-PYAthTa2m2VKxuvSD3DPC/Gy+U+sOA1LAuT8mkmRuvw+NACSaeXEQ+NHcVF7rONl6qcaxV3Uuemwawk+7+SJLw==}
     engines: {node: '>= 0.6'}
 
+  accepts@2.0.0:
+    resolution: {integrity: sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==}
+    engines: {node: '>= 0.6'}
+
   acorn-import-attributes@1.9.5:
     resolution: {integrity: sha512-n02Vykv5uA3eHGM/Z2dQrcD56kL8TyDb2p1+0P83PClMnC/nc+anbQRhIOWnSq4Ke/KvDPrY3C9hDtC/A3eHnQ==}
     peerDependencies:
@@ -6928,6 +6948,10 @@ packages:
   bl@6.1.6:
     resolution: {integrity: sha512-jLsPgN/YSvPUg9UX0Kd73CXpm2Psg9FxMeCSXnk3WBO3CMT10JMwijubhGfHCnFu6TPn1ei3b975dxv7K2pWVg==}
 
+  body-parser@2.2.2:
+    resolution: {integrity: sha512-oP5VkATKlNwcgvxi0vM0p/D3n2C3EReYVX+DNYs5TjZFn/oQt2j+4sVJtSMr18pdRr8wjTcBl6LoV+FUwzPmNA==}
+    engines: {node: '>=18'}
+
   boolbase@1.0.0:
     resolution: {integrity: sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww==}
 
@@ -6991,6 +7015,10 @@ packages:
     resolution: {integrity: sha512-tjwM5exMg6BGRI+kNmTntNsvdZS1X8BFYS6tnJ2hdH0kVxM6/eVZ2xy+FqStSWvYmtfFMDLIxurorHwDKfDz5Q==}
     engines: {node: '>=18'}
 
+  bytes@3.1.2:
+    resolution: {integrity: sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==}
+    engines: {node: '>= 0.8'}
+
   c12@3.1.0:
     resolution: {integrity: sha512-uWoS8OU1MEIsOv8p/5a82c3H31LsWVR5qiyXVfBNOzfffjUWtPnhAb4BYI2uG2HfGmZmFjCtui5XNWaps+iFuw==}
     peerDependencies:
@@ -7223,9 +7251,25 @@ packages:
   console-control-strings@1.1.0:
     resolution: {integrity: sha512-ty/fTekppD2fIwRvnZAVdeOiGd1c7YXEixbgJTNzqcxJWKQnjJ/V1bNEEE6hygpM3WjwHFUVK6HTjWSzV4a8sQ==}
 
+  content-disposition@1.1.0:
+    resolution: {integrity: sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g==}
+    engines: {node: '>=18'}
+
+  content-type@1.0.5:
+    resolution: {integrity: sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==}
+    engines: {node: '>= 0.6'}
+
+  content-type@2.0.0:
+    resolution: {integrity: sha512-j/O/d7GcZCyNl7/hwZAb606rzqkyvaDctLmckbxLzHvFBzTJHuGEdodATcP3yIRoDrLHkIATJuvzbFlp/ki2cQ==}
+    engines: {node: '>=18'}
+
   convert-source-map@2.0.0:
     resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==}
 
+  cookie-signature@1.2.2:
+    resolution: {integrity: sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg==}
+    engines: {node: '>=6.6.0'}
+
   cookie@0.7.2:
     resolution: {integrity: sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==}
     engines: {node: '>= 0.6'}
@@ -7495,6 +7539,10 @@ packages:
     resolution: {integrity: sha512-HVQE3AAb/pxF8fQAoiqpvg9i3evqug3hoiwakOyZAwJm+6vZehbkYXZ0l4JxS+I3QxM97v5aaRNhj8v5oBhekw==}
     engines: {node: '>=0.10'}
 
+  depd@2.0.0:
+    resolution: {integrity: sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==}
+    engines: {node: '>= 0.8'}
+
   destr@2.0.5:
     resolution: {integrity: sha512-ugFTXCtDZunbzasqBxrK93Ik/DRYsO6S/fedkWEMKqt04xZ4csmnmwGDBAb07QWNaGMAmnTIemsYZCksjATwsA==}
 
@@ -7604,6 +7652,9 @@ packages:
   ecdsa-sig-formatter@1.0.11:
     resolution: {integrity: sha512-nagl3RYrbNv6kQkeJIpt6NJZy8twLB/2vtz6yN9Z4vRKHN4/QZJIEbqohALSgwKdnksuY3k5Addp5lg8sVoVcQ==}
 
+  ee-first@1.1.1:
+    resolution: {integrity: sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==}
+
   effect@3.20.0:
     resolution: {integrity: sha512-qMLfDJscrNG8p/aw+IkT9W7fgj50Z4wG5bLBy0Txsxz8iUHjDIkOgO3SV0WZfnQbNG2VJYb0b+rDLMrhM4+Krw==}
 
@@ -7626,6 +7677,10 @@ packages:
     resolution: {integrity: sha512-i6UzDscO/XfAcNYD75CfICkmfLedpyPDdozrLMmQc5ORaQcdMoc21OnlEylMIqI7U8eniKrPMxxtj8k0vhmJhA==}
     engines: {node: '>=14'}
 
+  encodeurl@2.0.0:
+    resolution: {integrity: sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==}
+    engines: {node: '>= 0.8'}
+
   encoding@0.1.13:
     resolution: {integrity: sha512-ETBauow1T35Y/WZMkio9jiM0Z5xjHHmJ4XmjZOq1l/dXz3lr2sRn87nJy20RupqSh1F2m3HHPSp8ShIPQJrJ3A==}
 
@@ -7999,6 +8054,10 @@ packages:
     resolution: {integrity: sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==}
     engines: {node: '>=0.10.0'}
 
+  etag@1.8.1:
+    resolution: {integrity: sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==}
+    engines: {node: '>= 0.6'}
+
   event-target-shim@5.0.1:
     resolution: {integrity: sha512-i/2XbnSz/uxRCU6+NdVJgKWDTM427+MqYbkQzD321DuCQJUqOuJKIA0IM2+W2xtYHdKOmZ4dR6fExsd4SXL+WQ==}
     engines: {node: '>=6'}
@@ -8017,6 +8076,10 @@ packages:
     resolution: {integrity: sha512-70QWGkr4snxr0OXLRWsFLeRBIRPuQOvt4s8QYjmUlmlkyTZkRqS7EDVRZtzU3TiyDbXSzaOeF0XUKy8PchzukQ==}
     engines: {node: '>=18.0.0'}
 
+  eventsource@3.0.7:
+    resolution: {integrity: sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==}
+    engines: {node: '>=18.0.0'}
+
   expand-template@2.0.3:
     resolution: {integrity: sha512-XYfuKMvj4O35f/pOXLObndIRvyQ+/+6AhODh+OKWj9S9498pHHn/IMszH+gt0fBCRWMNfk1ZSp5x3AifmnI2vg==}
     engines: {node: '>=6'}
@@ -8025,6 +8088,16 @@ packages:
     resolution: {integrity: sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==}
     engines: {node: '>=12.0.0'}
 
+  express-rate-limit@8.5.2:
+    resolution: {integrity: sha512-5Kb34ipNX694DH48vN9irak1Qx30nb0PLYHXfJgw4YEjiC3ZEmZJhwOp+VfiCYwFzvFTdB9QkArYS5kXa2cx2A==}
+    engines: {node: '>= 16'}
+    peerDependencies:
+      express: '>= 4.11'
+
+  express@5.2.1:
+    resolution: {integrity: sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==}
+    engines: {node: '>= 18'}
+
   exsolve@1.0.8:
     resolution: {integrity: sha512-LmDxfWXwcTArk8fUEnOfSZpHOJ6zOMUJKOtFLFqJLoKJetuQG874Uc7/Kki7zFLzYybmZhp1M7+98pfMqeX8yA==}
 
@@ -8119,6 +8192,10 @@ packages:
     resolution: {integrity: sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==}
     engines: {node: '>=8'}
 
+  finalhandler@2.1.1:
+    resolution: {integrity: sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA==}
+    engines: {node: '>= 18.0.0'}
+
   find-up@4.1.0:
     resolution: {integrity: sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==}
     engines: {node: '>=8'}
@@ -8162,6 +8239,10 @@ packages:
   forwarded-parse@2.1.2:
     resolution: {integrity: sha512-alTFZZQDKMporBH77856pXgzhEzaUVmLCDk+egLgIgHst3Tpndzz8MnKe+GzRJRfvVdn69HhpW7cmXzvtLvJAw==}
 
+  forwarded@0.2.0:
+    resolution: {integrity: sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==}
+    engines: {node: '>= 0.6'}
+
   fraction.js@5.3.4:
     resolution: {integrity: sha512-1X1NTtiJphryn/uLQz3whtY6jK3fTqoE3ohKs0tT+Ujr1W59oopxmoEh7Lu5p6vBaPbgoM0bzveAW4Qi5RyWDQ==}
 
@@ -8179,6 +8260,10 @@ packages:
       react-dom:
         optional: true
 
+  fresh@2.0.0:
+    resolution: {integrity: sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A==}
+    engines: {node: '>= 0.8'}
+
   fs-constants@1.0.0:
     resolution: {integrity: sha512-y6OAwoSIf7FyjMIv94u+b5rdheZEjzR63GTyZJm5qh4Bi+2YgwLCcI/fPFZkL5PSixOt6ZNKm+w+Hfp/Bciwow==}
 
@@ -8451,6 +8536,10 @@ packages:
   http-cache-semantics@4.2.0:
     resolution: {integrity: sha512-dTxcvPXqPvXBQpq5dUr6mEMJX4oIEFv6bwom3FDwKRDsuIjjJGANqhBuoAn9c1RQJIdAKav33ED65E2ys+87QQ==}
 
+  http-errors@2.0.1:
+    resolution: {integrity: sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==}
+    engines: {node: '>= 0.8'}
+
   http-proxy-agent@4.0.1:
     resolution: {integrity: sha512-k0zdNgqWTGA6aeIRVpvfVob4fL52dTfaehylg0Y4UvSySvOq/Y+BOyPrgpUrA7HylqvU8vIZGsRuXmspskV0Tg==}
     engines: {node: '>= 6'}
@@ -8574,6 +8663,10 @@ packages:
     resolution: {integrity: sha512-1FMu8/N15Ck1BL551Jf42NYIoin2unWjLQ2Fze/DXryJRl5twqtwNHlO39qERGbIOcKYWHdgRryhOC+NG4eaLw==}
     engines: {node: '>= 12'}
 
+  ipaddr.js@1.9.1:
+    resolution: {integrity: sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==}
+    engines: {node: '>= 0.10'}
+
   ipaddr.js@2.3.0:
     resolution: {integrity: sha512-Zv/pA+ciVFbCSBBjGfaKUya/CcGmUHzTydLMaTwrUUEM2DIEO3iZvueGxmacvmN50fGpGVKeTXpb2LcYQxeVdg==}
     engines: {node: '>= 10'}
@@ -8704,6 +8797,9 @@ packages:
   is-potential-custom-element-name@1.0.1:
     resolution: {integrity: sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==}
 
+  is-promise@4.0.0:
+    resolution: {integrity: sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==}
+
   is-property@1.0.2:
     resolution: {integrity: sha512-Ks/IoX00TtClbGQr4TWXemAnktAQvYB7HzcCxDGqEZU6oCmb2INHuOoKxbtR+HFkmYWBKv/dOZtGRiAjDhj92g==}
 
@@ -9200,6 +9296,16 @@ packages:
     resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==}
     engines: {node: '>= 0.4'}
 
+  mcp-handler@1.1.0:
+    resolution: {integrity: sha512-MVCES7g18gcoZy+R/3v5nadkUMzMAWdos8jRl6DyljOKvd2/ZKDmwlCjL6zp4vo+7FeCXOYL1uWinHWlkKAAUg==}
+    hasBin: true
+    peerDependencies:
+      '@modelcontextprotocol/sdk': 1.26.0
+      next: '>=13.0.0'
+    peerDependenciesMeta:
+      next:
+        optional: true
+
   mdn-data@2.0.14:
     resolution: {integrity: sha512-dn6wd0uw5GsdswPFfsgMp5NSB0/aDe6fK94YJV/AJDYXL6HVLWBsxeq7js7Ad+mU2K9LAlwpk6kN2D5mwCPVow==}
 
@@ -9209,6 +9315,10 @@ packages:
   mdurl@2.0.0:
     resolution: {integrity: sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==}
 
+  media-typer@1.1.0:
+    resolution: {integrity: sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw==}
+    engines: {node: '>= 0.8'}
+
   memoize@10.2.0:
     resolution: {integrity: sha512-DeC6b7QBrZsRs3Y02A6A7lQyzFbsQbqgjI6UW0GigGWV+u1s25TycMr0XHZE4cJce7rY/vyw2ctMQqfDkIhUEA==}
     engines: {node: '>=18'}
@@ -9216,6 +9326,10 @@ packages:
   memory-pager@1.5.0:
     resolution: {integrity: sha512-ZS4Bp4r/Zoeq6+NLJpP+0Zzm0pR8whtGPf1XExKLJBAczGMnSi3It14OiNCStjQjM6NU1okjQGSxgEZN8eBYKg==}
 
+  merge-descriptors@2.0.0:
+    resolution: {integrity: sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g==}
+    engines: {node: '>=18'}
+
   merge-stream@2.0.0:
     resolution: {integrity: sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w==}
 
@@ -9435,6 +9549,10 @@ packages:
     resolution: {integrity: sha512-myRT3DiWPHqho5PrJaIRyaMv2kgYf0mUVgBNOYMuCH5Ki1yEiQaf/ZJuQ62nvpc44wL5WDbTX7yGJi1Neevw8w==}
     engines: {node: '>= 0.6'}
 
+  negotiator@1.0.0:
+    resolution: {integrity: sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==}
+    engines: {node: '>= 0.6'}
+
   neo-async@2.6.2:
     resolution: {integrity: sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==}
 
@@ -9639,6 +9757,10 @@ packages:
     resolution: {integrity: sha512-0eJJY6hXLGf1udHwfNftBqH+g73EU4B504nZeKpz1sYRKafAghwxEJunB2O7rDZkL4PGfsMVnTXZ2EjibbqcsA==}
     engines: {node: '>=14.0.0'}
 
+  on-finished@2.4.1:
+    resolution: {integrity: sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==}
+    engines: {node: '>= 0.8'}
+
   once@1.4.0:
     resolution: {integrity: sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==}
 
@@ -9731,6 +9853,10 @@ packages:
   parseley@0.12.1:
     resolution: {integrity: sha512-e6qHKe3a9HWr0oMRVDTRhKce+bRO8VGQR3NyVwcjwrbhMmFCX9KszEV35+rn4AdilFAq9VPxP/Fe1wC9Qjd2lw==}
 
+  parseurl@1.3.3:
+    resolution: {integrity: sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==}
+    engines: {node: '>= 0.8'}
+
   path-browserify@1.0.1:
     resolution: {integrity: sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g==}
 
@@ -9761,6 +9887,9 @@ packages:
     resolution: {integrity: sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==}
     engines: {node: 18 || 20 || >=22}
 
+  path-to-regexp@8.4.2:
+    resolution: {integrity: sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA==}
+
   path-type@4.0.0:
     resolution: {integrity: sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==}
     engines: {node: '>=8'}
@@ -9853,6 +9982,10 @@ packages:
     resolution: {integrity: sha512-TfySrs/5nm8fQJDcBDuUng3VOUKsd7S+zqvbOTiGXHfxX4wK31ard+hoNuvkicM/2YFzlpDgABOevKSsB4G/FA==}
     engines: {node: '>= 6'}
 
+  pkce-challenge@5.0.1:
+    resolution: {integrity: sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==}
+    engines: {node: '>=16.20.0'}
+
   pkg-types@1.3.1:
     resolution: {integrity: sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==}
 
@@ -10148,6 +10281,10 @@ packages:
     resolution: {integrity: sha512-oI+GC9iPxrQEr6wragljFKH46/r3rNsm6eg7F2fp6kBUMnf6/mesDRdBuF4gK+OyaKJ8N4C1B9s9cCeYdqFikg==}
     engines: {node: '>=12.0.0'}
 
+  proxy-addr@2.0.7:
+    resolution: {integrity: sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==}
+    engines: {node: '>= 0.10'}
+
   proxy-from-env@1.1.0:
     resolution: {integrity: sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==}
 
@@ -10200,6 +10337,14 @@ packages:
   ramda@0.27.2:
     resolution: {integrity: sha512-SbiLPU40JuJniHexQSAgad32hfwd+DRUdwF2PlVuI5RZD0/vahUco7R8vD86J/tcEKKF9vZrUVwgtmGCqlCKyA==}
 
+  range-parser@1.2.1:
+    resolution: {integrity: sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg==}
+    engines: {node: '>= 0.6'}
+
+  raw-body@3.0.2:
+    resolution: {integrity: sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==}
+    engines: {node: '>= 0.10'}
+
   rc9@2.1.2:
     resolution: {integrity: sha512-btXCnMmRIBINM2LDZoEmOogIZU7Qe7zn4BpomSKZ/ykbLObuBdvG+mFq11DL6fjH1DRwHhrlgtYWG96bJiC7Cg==}
 
@@ -10568,6 +10713,10 @@ packages:
     engines: {node: '>=18.0.0', npm: '>=8.0.0'}
     hasBin: true
 
+  router@2.2.0:
+    resolution: {integrity: sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ==}
+    engines: {node: '>= 18'}
+
   rtl-css-js@1.16.1:
     resolution: {integrity: sha512-lRQgou1mu19e+Ya0LsTvKrVJ5TYUbqCVPAiImX3UfLTenarvPUl1QFdvu5Z3PYmHT9RCcwIfbjRQBntExyj3Zg==}
 
@@ -10656,9 +10805,17 @@ packages:
     engines: {node: '>=10'}
     hasBin: true
 
+  send@1.2.1:
+    resolution: {integrity: sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ==}
+    engines: {node: '>= 18'}
+
   seq-queue@0.0.5:
     resolution: {integrity: sha512-hr3Wtp/GZIc/6DAGPDcV4/9WoZhjrkXsi5B/07QgX8tsdc6ilr7BFM6PM6rbdAX1kFSDYeZGLipIZZKyQP0O5Q==}
 
+  serve-static@2.2.1:
+    resolution: {integrity: sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw==}
+    engines: {node: '>= 18'}
+
   server-only@0.0.1:
     resolution: {integrity: sha512-qepMx2JxAa5jjfzxG79yPPq+8BuFToHd1hm7kI+Z4zAq1ftQiP7HcxMhDDItrbtwVeLg/cY2JnKnrcFkmiswNA==}
 
@@ -10681,6 +10838,9 @@ packages:
     resolution: {integrity: sha512-RJRdvCo6IAnPdsvP/7m6bsQqNnn1FCBX5ZNtFL98MmFF/4xAIJTIg1YbHW5DC2W5SKZanrC6i4HsJqlajw/dZw==}
     engines: {node: '>= 0.4'}
 
+  setprototypeof@1.2.0:
+    resolution: {integrity: sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==}
+
   sha.js@2.4.12:
     resolution: {integrity: sha512-8LzC5+bvI45BjpfXU8V5fdU2mfeKiQe1D1gIMn7XUlF3OTUrpdJpPPH4EMAnF0DsHHdSZqCdSss5qCmJKuiO3w==}
     engines: {node: '>= 0.10'}
@@ -10878,6 +11038,10 @@ packages:
   standard-as-callback@2.1.0:
     resolution: {integrity: sha512-qoRRSyROncaz1z0mvYqIE4lCd9p2R90i6GxW3uZv5ucSu8tU7B5HXUP1gG8pVZsYNVaXjk8ClXHPttLyxAL48A==}
 
+  statuses@2.0.2:
+    resolution: {integrity: sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==}
+    engines: {node: '>= 0.8'}
+
   std-env@3.10.0:
     resolution: {integrity: sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==}
 
@@ -11219,6 +11383,10 @@ packages:
   toggle-selection@1.0.6:
     resolution: {integrity: sha512-BiZS+C1OS8g/q2RRbJmy59xpyghNBqrr6k5L/uKBGRsTfxmu3ffiRnd8mlGPUVayg8pvfi5urfnu8TU7DVOkLQ==}
 
+  toidentifier@1.0.1:
+    resolution: {integrity: sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==}
+    engines: {node: '>=0.6'}
+
   tough-cookie@6.0.1:
     resolution: {integrity: sha512-LktZQb3IeoUWB9lqR5EWTHgW/VTITCXg4D21M+lvybRVdylLrRMnqaIONLVb5mav8vM19m44HIcGq4qASeu2Qw==}
     engines: {node: '>=16'}
@@ -11356,6 +11524,10 @@ packages:
     resolution: {integrity: sha512-VCn+LMHbd4t6sF3wfU/+HKT63C9OoyrSIf4b+vtWHpt2U7/4InZG467YDNMFMR70DdHjAdpPWmw2lzRdg0Xqqg==}
     engines: {node: '>=20'}
 
+  type-is@2.1.0:
+    resolution: {integrity: sha512-faYHw0anBbc/kWF3zFTEnxSFOAGUX9GFbOBthvDdLsIlEoWOFOtS0zgCiQYwIskL9iGXZL3kAXD8OoZ4GmMATA==}
+    engines: {node: '>= 18'}
+
   typed-array-buffer@1.0.3:
     resolution: {integrity: sha512-nAYYwfY3qnzX30IkA6AQZjVbtK6duGontcQm1WSG1MD94YLqK0515GNApXkoxKOWMusVssAHWLh9SeaoefYFGw==}
     engines: {node: '>= 0.4'}
@@ -11482,6 +11654,10 @@ packages:
     resolution: {integrity: sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==}
     engines: {node: '>= 10.0.0'}
 
+  unpipe@1.0.0:
+    resolution: {integrity: sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==}
+    engines: {node: '>= 0.8'}
+
   unplugin@2.3.11:
     resolution: {integrity: sha512-5uKD0nqiYVzlmCRs01Fhs2BdkEgBS3SAVP6ndrBsuK42iC2+JHyxM05Rm9G8+5mkmRtzMZGY8Ct5+mliZxU/Ww==}
     engines: {node: '>=18.12.0'}
@@ -12056,6 +12232,11 @@ packages:
     peerDependencies:
       zod: ^3.25.74 || ^4.0.0
 
+  zod-to-json-schema@3.25.2:
+    resolution: {integrity: sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA==}
+    peerDependencies:
+      zod: ^3.25.28 || ^4
+
   zod@4.3.6:
     resolution: {integrity: sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==}
 
@@ -14156,7 +14337,6 @@ snapshots:
   '@hono/node-server@1.19.13(hono@4.12.18)':
     dependencies:
       hono: 4.12.18
-    optional: true
 
   '@hookform/resolvers@5.2.2(react-hook-form@7.71.2(react@19.2.6))':
     dependencies:
@@ -14550,6 +14730,28 @@ snapshots:
 
   '@microsoft/tsdoc@0.16.0': {}
 
+  '@modelcontextprotocol/sdk@1.26.0(zod@4.3.6)':
+    dependencies:
+      '@hono/node-server': 1.19.13(hono@4.12.18)
+      ajv: 8.20.0
+      ajv-formats: 3.0.1(ajv@8.20.0)
+      content-type: 1.0.5
+      cors: 2.8.5
+      cross-spawn: 7.0.6
+      eventsource: 3.0.7
+      eventsource-parser: 3.0.8
+      express: 5.2.1
+      express-rate-limit: 8.5.2(express@5.2.1)
+      hono: 4.12.18
+      jose: 6.2.2
+      json-schema-typed: 8.0.2
+      pkce-challenge: 5.0.1
+      raw-body: 3.0.2
+      zod: 4.3.6
+      zod-to-json-schema: 3.25.2(zod@4.3.6)
+    transitivePeerDependencies:
+      - supports-color
+
   '@mongodb-js/saslprep@1.4.4':
     dependencies:
       sparse-bitfield: 3.0.3
@@ -18595,10 +18797,10 @@ snapshots:
       '@typescript-eslint/eslint-plugin': 7.18.0(@typescript-eslint/parser@7.18.0(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1)(typescript@5.9.3)
       '@typescript-eslint/parser': 7.18.0(eslint@8.57.1)(typescript@5.9.3)
       eslint-config-prettier: 9.1.2(eslint@8.57.1)
-      eslint-import-resolver-alias: 1.1.2(eslint-plugin-import@2.32.0)
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@8.57.1)
+      eslint-import-resolver-alias: 1.1.2(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1)
       eslint-plugin-eslint-comments: 3.2.0(eslint@8.57.1)
-      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@7.18.0(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@8.57.1)
+      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@7.18.0(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1))(eslint@8.57.1)
       eslint-plugin-jest: 27.9.0(@typescript-eslint/eslint-plugin@8.57.2(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1)(typescript@5.9.3)
       eslint-plugin-jsx-a11y: 6.10.2(eslint@8.57.1)
       eslint-plugin-playwright: 1.8.3(eslint-plugin-jest@27.9.0(@typescript-eslint/eslint-plugin@7.18.0(@typescript-eslint/parser@7.18.0(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1)
@@ -18930,6 +19132,11 @@ snapshots:
       mime-types: 2.1.35
       negotiator: 0.6.3
 
+  accepts@2.0.0:
+    dependencies:
+      mime-types: 3.0.2
+      negotiator: 1.0.0
+
   acorn-import-attributes@1.9.5(acorn@8.16.0):
     dependencies:
       acorn: 8.16.0
@@ -18988,6 +19195,10 @@ snapshots:
     optionalDependencies:
       ajv: 8.18.0
 
+  ajv-formats@3.0.1(ajv@8.20.0):
+    optionalDependencies:
+      ajv: 8.20.0
+
   ajv-keywords@5.1.0(ajv@8.20.0):
     dependencies:
       ajv: 8.20.0
@@ -19264,6 +19475,20 @@ snapshots:
       inherits: 2.0.4
       readable-stream: 4.7.0
 
+  body-parser@2.2.2:
+    dependencies:
+      bytes: 3.1.2
+      content-type: 1.0.5
+      debug: 4.4.3
+      http-errors: 2.0.1
+      iconv-lite: 0.7.2
+      on-finished: 2.4.1
+      qs: 6.15.2
+      raw-body: 3.0.2
+      type-is: 2.1.0
+    transitivePeerDependencies:
+      - supports-color
+
   boolbase@1.0.0: {}
 
   boring-avatars@2.0.4(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
@@ -19340,6 +19565,8 @@ snapshots:
     dependencies:
       run-applescript: 7.1.0
 
+  bytes@3.1.2: {}
+
   c12@3.1.0(magicast@0.3.5):
     dependencies:
       chokidar: 4.0.3
@@ -19575,8 +19802,8 @@ snapshots:
 
   conf@15.0.2:
     dependencies:
-      ajv: 8.18.0
-      ajv-formats: 3.0.1(ajv@8.18.0)
+      ajv: 8.20.0
+      ajv-formats: 3.0.1(ajv@8.20.0)
       atomically: 2.1.0
       debounce-fn: 6.0.0
       dot-prop: 10.1.0
@@ -19594,8 +19821,16 @@ snapshots:
   console-control-strings@1.1.0:
     optional: true
 
+  content-disposition@1.1.0: {}
+
+  content-type@1.0.5: {}
+
+  content-type@2.0.0: {}
+
   convert-source-map@2.0.0: {}
 
+  cookie-signature@1.2.2: {}
+
   cookie@0.7.2: {}
 
   copy-to-clipboard@3.3.3:
@@ -19841,6 +20076,8 @@ snapshots:
 
   denque@2.1.0: {}
 
+  depd@2.0.0: {}
+
   destr@2.0.5: {}
 
   detect-europe-js@0.1.2: {}
@@ -19940,6 +20177,8 @@ snapshots:
     dependencies:
       safe-buffer: 5.2.1
 
+  ee-first@1.1.1: {}
+
   effect@3.20.0:
     dependencies:
       '@standard-schema/spec': 1.1.0
@@ -19957,6 +20196,8 @@ snapshots:
 
   empathic@2.0.0: {}
 
+  encodeurl@2.0.0: {}
+
   encoding@0.1.13:
     dependencies:
       iconv-lite: 0.6.3
@@ -20239,8 +20480,8 @@ snapshots:
       '@typescript-eslint/parser': 8.57.2(eslint@8.57.1)(typescript@5.9.3)
       eslint: 8.57.1
       eslint-import-resolver-node: 0.3.9
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@8.57.1)
-      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1)
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1)
+      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1))(eslint@8.57.1)
       eslint-plugin-jsx-a11y: 6.10.2(eslint@8.57.1)
       eslint-plugin-react: 7.37.5(eslint@8.57.1)
       eslint-plugin-react-hooks: 5.2.0(eslint@8.57.1)
@@ -20265,9 +20506,9 @@ snapshots:
       eslint-plugin-turbo: 2.8.21(eslint@8.57.1)(turbo@2.9.14)
       turbo: 2.9.14
 
-  eslint-import-resolver-alias@1.1.2(eslint-plugin-import@2.32.0):
+  eslint-import-resolver-alias@1.1.2(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1)):
     dependencies:
-      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1)
+      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1))(eslint@8.57.1)
 
   eslint-import-resolver-node@0.3.9:
     dependencies:
@@ -20277,7 +20518,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0)(eslint@8.57.1):
+  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1):
     dependencies:
       '@nolyfill/is-core-module': 1.0.39
       debug: 4.4.3
@@ -20288,29 +20529,29 @@ snapshots:
       tinyglobby: 0.2.15
       unrs-resolver: 1.11.1
     optionalDependencies:
-      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1)
+      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1))(eslint@8.57.1)
     transitivePeerDependencies:
       - supports-color
 
-  eslint-module-utils@2.12.1(@typescript-eslint/parser@7.18.0(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1)(eslint@8.57.1):
+  eslint-module-utils@2.12.1(@typescript-eslint/parser@7.18.0(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1))(eslint@8.57.1):
     dependencies:
       debug: 3.2.7
     optionalDependencies:
       '@typescript-eslint/parser': 7.18.0(eslint@8.57.1)(typescript@5.9.3)
       eslint: 8.57.1
       eslint-import-resolver-node: 0.3.9
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@8.57.1)
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1)
     transitivePeerDependencies:
       - supports-color
 
-  eslint-module-utils@2.12.1(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1)(eslint@8.57.1):
+  eslint-module-utils@2.12.1(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1))(eslint@8.57.1):
     dependencies:
       debug: 3.2.7
     optionalDependencies:
       '@typescript-eslint/parser': 8.57.2(eslint@8.57.1)(typescript@5.9.3)
       eslint: 8.57.1
       eslint-import-resolver-node: 0.3.9
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@8.57.1)
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1)
     transitivePeerDependencies:
       - supports-color
 
@@ -20320,7 +20561,7 @@ snapshots:
       eslint: 8.57.1
       ignore: 5.3.2
 
-  eslint-plugin-import@2.32.0(@typescript-eslint/parser@7.18.0(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@8.57.1):
+  eslint-plugin-import@2.32.0(@typescript-eslint/parser@7.18.0(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1))(eslint@8.57.1):
     dependencies:
       '@rtsao/scc': 1.1.0
       array-includes: 3.1.9
@@ -20331,7 +20572,7 @@ snapshots:
       doctrine: 2.1.0
       eslint: 8.57.1
       eslint-import-resolver-node: 0.3.9
-      eslint-module-utils: 2.12.1(@typescript-eslint/parser@7.18.0(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1)(eslint@8.57.1)
+      eslint-module-utils: 2.12.1(@typescript-eslint/parser@7.18.0(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1))(eslint@8.57.1)
       hasown: 2.0.2
       is-core-module: 2.16.1
       is-glob: 4.0.3
@@ -20349,7 +20590,7 @@ snapshots:
       - eslint-import-resolver-webpack
       - supports-color
 
-  eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1):
+  eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1))(eslint@8.57.1):
     dependencies:
       '@rtsao/scc': 1.1.0
       array-includes: 3.1.9
@@ -20360,7 +20601,7 @@ snapshots:
       doctrine: 2.1.0
       eslint: 8.57.1
       eslint-import-resolver-node: 0.3.9
-      eslint-module-utils: 2.12.1(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1)(eslint@8.57.1)
+      eslint-module-utils: 2.12.1(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.57.2(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1))(eslint@8.57.1)
       hasown: 2.0.2
       is-core-module: 2.16.1
       is-glob: 4.0.3
@@ -20600,6 +20841,8 @@ snapshots:
 
   esutils@2.0.3: {}
 
+  etag@1.8.1: {}
+
   event-target-shim@5.0.1: {}
 
   eventemitter3@4.0.7: {}
@@ -20610,10 +20853,52 @@ snapshots:
 
   eventsource-parser@3.0.8: {}
 
+  eventsource@3.0.7:
+    dependencies:
+      eventsource-parser: 3.0.8
+
   expand-template@2.0.3: {}
 
   expect-type@1.3.0: {}
 
+  express-rate-limit@8.5.2(express@5.2.1):
+    dependencies:
+      express: 5.2.1
+      ip-address: 10.1.1
+
+  express@5.2.1:
+    dependencies:
+      accepts: 2.0.0
+      body-parser: 2.2.2
+      content-disposition: 1.1.0
+      content-type: 1.0.5
+      cookie: 0.7.2
+      cookie-signature: 1.2.2
+      debug: 4.4.3
+      depd: 2.0.0
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      etag: 1.8.1
+      finalhandler: 2.1.1
+      fresh: 2.0.0
+      http-errors: 2.0.1
+      merge-descriptors: 2.0.0
+      mime-types: 3.0.2
+      on-finished: 2.4.1
+      once: 1.4.0
+      parseurl: 1.3.3
+      proxy-addr: 2.0.7
+      qs: 6.15.2
+      range-parser: 1.2.1
+      router: 2.2.0
+      send: 1.2.1
+      serve-static: 2.2.1
+      statuses: 2.0.2
+      type-is: 2.1.0
+      vary: 1.1.2
+    transitivePeerDependencies:
+      - supports-color
+
   exsolve@1.0.8: {}
 
   extend@3.0.2: {}
@@ -20699,6 +20984,17 @@ snapshots:
     dependencies:
       to-regex-range: 5.0.1
 
+  finalhandler@2.1.1:
+    dependencies:
+      debug: 4.4.3
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      on-finished: 2.4.1
+      parseurl: 1.3.3
+      statuses: 2.0.2
+    transitivePeerDependencies:
+      - supports-color
+
   find-up@4.1.0:
     dependencies:
       locate-path: 5.0.0
@@ -20742,6 +21038,8 @@ snapshots:
 
   forwarded-parse@2.1.2: {}
 
+  forwarded@0.2.0: {}
+
   fraction.js@5.3.4: {}
 
   framer-motion@12.35.2(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
@@ -20753,6 +21051,8 @@ snapshots:
       react: 19.2.6
       react-dom: 19.2.6(react@19.2.6)
 
+  fresh@2.0.0: {}
+
   fs-constants@1.0.0: {}
 
   fs-extra@11.3.3:
@@ -21048,8 +21348,7 @@ snapshots:
 
   help-me@5.0.0: {}
 
-  hono@4.12.18:
-    optional: true
+  hono@4.12.18: {}
 
   hosted-git-info@2.8.9: {}
 
@@ -21090,6 +21389,14 @@ snapshots:
   http-cache-semantics@4.2.0:
     optional: true
 
+  http-errors@2.0.1:
+    dependencies:
+      depd: 2.0.0
+      inherits: 2.0.4
+      setprototypeof: 1.2.0
+      statuses: 2.0.2
+      toidentifier: 1.0.1
+
   http-proxy-agent@4.0.1:
     dependencies:
       '@tootallnate/once': 3.0.1
@@ -21230,8 +21537,9 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  ip-address@10.1.1:
-    optional: true
+  ip-address@10.1.1: {}
+
+  ipaddr.js@1.9.1: {}
 
   ipaddr.js@2.3.0: {}
 
@@ -21350,6 +21658,8 @@ snapshots:
 
   is-potential-custom-element-name@1.0.1: {}
 
+  is-promise@4.0.0: {}
+
   is-property@1.0.2: {}
 
   is-reference@1.2.1:
@@ -21841,18 +22151,31 @@ snapshots:
 
   math-intrinsics@1.1.0: {}
 
+  mcp-handler@1.1.0(@modelcontextprotocol/sdk@1.26.0(zod@4.3.6))(next@16.2.6(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)):
+    dependencies:
+      '@modelcontextprotocol/sdk': 1.26.0(zod@4.3.6)
+      chalk: 5.6.2
+      commander: 11.1.0
+      redis: 4.7.1
+    optionalDependencies:
+      next: 16.2.6(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+
   mdn-data@2.0.14: {}
 
   mdn-data@2.27.1: {}
 
   mdurl@2.0.0: {}
 
+  media-typer@1.1.0: {}
+
   memoize@10.2.0:
     dependencies:
       mimic-function: 5.0.1
 
   memory-pager@1.5.0: {}
 
+  merge-descriptors@2.0.0: {}
+
   merge-stream@2.0.0: {}
 
   merge2@1.4.1: {}
@@ -22081,6 +22404,8 @@ snapshots:
   negotiator@0.6.4:
     optional: true
 
+  negotiator@1.0.0: {}
+
   neo-async@2.6.2: {}
 
   next-auth@4.24.13(patch_hash=6b21102fce2caaca35f5e4e93ea07a0b4ff486cbf3d3b09a4173ad45977d5798)(next@16.2.6(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(nodemailer@8.0.7)(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
@@ -22303,6 +22628,10 @@ snapshots:
 
   on-exit-leak-free@2.1.2: {}
 
+  on-finished@2.4.1:
+    dependencies:
+      ee-first: 1.1.1
+
   once@1.4.0:
     dependencies:
       wrappy: 1.0.2
@@ -22438,6 +22767,8 @@ snapshots:
       leac: 0.6.0
       peberminta: 0.9.0
 
+  parseurl@1.3.3: {}
+
   path-browserify@1.0.1: {}
 
   path-exists@4.0.0: {}
@@ -22460,6 +22791,8 @@ snapshots:
       lru-cache: 11.2.6
       minipass: 7.1.3
 
+  path-to-regexp@8.4.2: {}
+
   path-type@4.0.0: {}
 
   pathe@2.0.3: {}
@@ -22561,6 +22894,8 @@ snapshots:
 
   pirates@4.0.7: {}
 
+  pkce-challenge@5.0.1: {}
+
   pkg-types@1.3.1:
     dependencies:
       confbox: 0.1.8
@@ -22815,6 +23150,11 @@ snapshots:
       '@types/node': 25.4.0
       long: 5.3.2
 
+  proxy-addr@2.0.7:
+    dependencies:
+      forwarded: 0.2.0
+      ipaddr.js: 1.9.1
+
   proxy-from-env@1.1.0: {}
 
   proxy-from-env@2.1.0: {}
@@ -22856,6 +23196,15 @@ snapshots:
 
   ramda@0.27.2: {}
 
+  range-parser@1.2.1: {}
+
+  raw-body@3.0.2:
+    dependencies:
+      bytes: 3.1.2
+      http-errors: 2.0.1
+      iconv-lite: 0.7.2
+      unpipe: 1.0.0
+
   rc9@2.1.2:
     dependencies:
       defu: 6.1.7
@@ -23346,6 +23695,16 @@ snapshots:
       '@rollup/rollup-win32-x64-msvc': 4.59.0
       fsevents: 2.3.3
 
+  router@2.2.0:
+    dependencies:
+      debug: 4.4.3
+      depd: 2.0.0
+      is-promise: 4.0.0
+      parseurl: 1.3.3
+      path-to-regexp: 8.4.2
+    transitivePeerDependencies:
+      - supports-color
+
   rtl-css-js@1.16.1:
     dependencies:
       '@babel/runtime': 7.28.4
@@ -23433,9 +23792,34 @@ snapshots:
   semver@7.8.0:
     optional: true
 
+  send@1.2.1:
+    dependencies:
+      debug: 4.4.3
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      etag: 1.8.1
+      fresh: 2.0.0
+      http-errors: 2.0.1
+      mime-types: 3.0.2
+      ms: 2.1.3
+      on-finished: 2.4.1
+      range-parser: 1.2.1
+      statuses: 2.0.2
+    transitivePeerDependencies:
+      - supports-color
+
   seq-queue@0.0.5:
     optional: true
 
+  serve-static@2.2.1:
+    dependencies:
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      parseurl: 1.3.3
+      send: 1.2.1
+    transitivePeerDependencies:
+      - supports-color
+
   server-only@0.0.1: {}
 
   set-blocking@2.0.0: {}
@@ -23464,6 +23848,8 @@ snapshots:
       es-errors: 1.3.0
       es-object-atoms: 1.1.1
 
+  setprototypeof@1.2.0: {}
+
   sha.js@2.4.12:
     dependencies:
       inherits: 2.0.4
@@ -23725,6 +24111,8 @@ snapshots:
 
   standard-as-callback@2.1.0: {}
 
+  statuses@2.0.2: {}
+
   std-env@3.10.0: {}
 
   std-env@4.1.0: {}
@@ -24086,6 +24474,8 @@ snapshots:
 
   toggle-selection@1.0.6: {}
 
+  toidentifier@1.0.1: {}
+
   tough-cookie@6.0.1:
     dependencies:
       tldts: 7.0.19
@@ -24207,6 +24597,12 @@ snapshots:
     dependencies:
       tagged-tag: 1.0.0
 
+  type-is@2.1.0:
+    dependencies:
+      content-type: 2.0.0
+      media-typer: 1.1.0
+      mime-types: 3.0.2
+
   typed-array-buffer@1.0.3:
     dependencies:
       call-bound: 1.0.4
@@ -24316,6 +24712,8 @@ snapshots:
 
   universalify@2.0.1: {}
 
+  unpipe@1.0.0: {}
+
   unplugin@2.3.11:
     dependencies:
       '@jridgewell/remapping': 2.3.5
@@ -24987,4 +25385,8 @@ snapshots:
     dependencies:
       zod: 4.3.6
 
+  zod-to-json-schema@3.25.2(zod@4.3.6):
+    dependencies:
+      zod: 4.3.6
+
   zod@4.3.6: {}

From bb7b92706bb8d06e06279704418320b09ff22bfe Mon Sep 17 00:00:00 2001
From: Bhagya Amarasinghe <b.sithumini@yahoo.com>
Date: Tue, 2 Jun 2026 22:41:49 +0530
Subject: [PATCH 3/3] fix: use node for cube compose healthcheck (#8216)

---
 docker/docker-compose.yml                | 8 +++++++-
 docs/self-hosting/advanced/migration.mdx | 3 +++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml
index 2c1f9765a168..8e7ccd75f30a 100644
--- a/docker/docker-compose.yml
+++ b/docker/docker-compose.yml
@@ -321,7 +321,13 @@ services:
       - ./cube/cube.js:/cube/conf/cube.js:ro
       - ./cube/schema:/cube/conf/model:ro
     healthcheck:
-      test: ["CMD", "wget", "-qO-", "http://localhost:4000/readyz"]
+      test:
+        [
+          "CMD",
+          "node",
+          "-e",
+          "require('http').get('http://127.0.0.1:4000/readyz', (res) => { res.resume(); process.exit(res.statusCode === 200 ? 0 : 1); }).on('error', () => process.exit(1));",
+        ]
       interval: 10s
       timeout: 5s
       retries: 12
diff --git a/docs/self-hosting/advanced/migration.mdx b/docs/self-hosting/advanced/migration.mdx
index cb6b2d18820c..fe28406ba8c9 100644
--- a/docs/self-hosting/advanced/migration.mdx
+++ b/docs/self-hosting/advanced/migration.mdx
@@ -243,6 +243,9 @@ Common upgrade issues:
 - **Missing `CUBEJS_API_SECRET`** (or unreachable Cube endpoint): the Formbricks app fails env validation
   at boot, or — if env vars are present but Cube is unreachable — dashboards and analysis queries fail
   while the rest of the app stays healthy
+- **Cube healthcheck fails with `wget: not found`**: older v5 Docker Compose files used `wget` for the
+  bundled Cube healthcheck, but `cubejs/cube:v1.6.6` does not include it. Sync the Cube healthcheck from the
+  current Docker Compose file so it checks `/readyz` with Node instead.
 
 If you need to roll back: