From da382ba0450a5581ac6dc7443e5b33853deb12f2 Mon Sep 17 00:00:00 2001
From: Tapiwa Muzira <tapsmuzira@gmail.com>
Date: Wed, 17 Jun 2026 14:11:08 +0200
Subject: [PATCH 1/8] Add nestable Postman-style folders within collections
 (storage, execution chain, import, MCP, UI, tests).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |   6 +
 client/src/App.tsx                            | 256 ++++++++++-----
 client/src/api.ts                             |  73 ++++-
 .../{CollectionEditor.tsx => NodeEditor.tsx}  |  58 ++--
 client/src/components/RequestEditor.tsx       |   6 +-
 client/src/components/Sidebar.tsx             | 297 +++++++++++-------
 client/src/selection.ts                       |   8 +-
 client/src/styles.css                         |   6 +-
 client/src/types.ts                           |  11 +
 server/src/importer.ts                        |  73 ++++-
 server/src/mcp.ts                             | 172 ++++++++--
 server/src/postmanImport.test.ts              |  46 ++-
 server/src/postmanImport.ts                   | 102 +++---
 server/src/router.integration.test.ts         | 130 ++++++++
 server/src/router.ts                          |  54 +++-
 server/src/types.ts                           |  11 +
 server/src/workspaceFs.test.ts                |  70 ++++-
 server/src/workspaceFs.ts                     | 250 ++++++++++++---
 18 files changed, 1245 insertions(+), 384 deletions(-)
 rename client/src/components/{CollectionEditor.tsx => NodeEditor.tsx} (65%)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f9f9ca6..58dcf0a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,12 @@ See [RELEASING.md](RELEASING.md) for the release process.
 
 ### Added
 
+- **Folders** inside collections, nestable to any depth (Postman-style).
+  Folders carry their own description and pre-request/test scripts, which run in
+  the execution chain (collection → folder(s) → request). Postman imports now
+  preserve their folder structure instead of flattening it into separate
+  collections. On disk, folders are mirrored as nested directories; pre-folders
+  workspaces still load (their requests appear at the collection root).
 - Documentation now has **edit** and **preview** modes (request docs and
   collection descriptions). Existing docs open in a read-only rendered preview
   with an **Edit** button; empty docs open straight in the editor; a **Done**
diff --git a/client/src/App.tsx b/client/src/App.tsx
index 4955937..f778a39 100644
--- a/client/src/App.tsx
+++ b/client/src/App.tsx
@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { api } from './api';
-import { CollectionEditor } from './components/CollectionEditor';
+import { NodeEditor } from './components/NodeEditor';
 import { CookieManager } from './components/CookieManager';
 import { EnvironmentEditor } from './components/EnvironmentEditor';
 import { PromptModal, type PromptConfig } from './components/PromptModal';
@@ -9,7 +9,13 @@ import { Sidebar } from './components/Sidebar';
 import { TopBar } from './components/TopBar';
 import { parseCurl } from './curl';
 import type { Selection } from './selection';
-import type { ApiRequest, WorkspaceMeta, WorkspaceTree } from './types';
+import type {
+  ApiRequest,
+  Collection,
+  Folder,
+  WorkspaceMeta,
+  WorkspaceTree,
+} from './types';
 import { VariablesContext, type VariablesInfo } from './variables';
 
 const LAST_WORKSPACE_KEY = 'apinotebook.lastWorkspace';
@@ -169,13 +175,40 @@ export default function App() {
     window.addEventListener('mouseup', onUp);
   }
 
+  function findCollection(collectionId: string): Collection | undefined {
+    return tree?.collections.find((c) => c.id === collectionId);
+  }
+
+  /** The container at a folder path — the collection itself when path is []. */
+  function findNode(
+    collectionId: string,
+    folderPath: string[]
+  ): { folders: Folder[]; requests: ApiRequest[] } | undefined {
+    let node: { folders: Folder[]; requests: ApiRequest[] } | undefined =
+      findCollection(collectionId);
+    for (const slug of folderPath) {
+      node = node?.folders.find((f) => f.id === slug);
+      if (!node) return undefined;
+    }
+    return node;
+  }
+
+  function findFolder(
+    collectionId: string,
+    folderPath: string[]
+  ): Folder | undefined {
+    if (folderPath.length === 0) return undefined;
+    return findNode(collectionId, folderPath) as Folder | undefined;
+  }
+
   function findRequest(
     collectionId: string,
+    folderPath: string[],
     requestId: string
   ): ApiRequest | undefined {
-    return tree?.collections
-      .find((c) => c.id === collectionId)
-      ?.requests.find((r) => r.id === requestId);
+    return findNode(collectionId, folderPath)?.requests.find(
+      (r) => r.id === requestId
+    );
   }
 
   // ----- workspace prompts -----
@@ -237,7 +270,7 @@ export default function App() {
     });
   }
 
-  function promptNewRequest(collectionId: string) {
+  function promptNewRequest(collectionId: string, folderPath: string[]) {
     if (!workspaceId) return;
     setPrompt({
       title: 'New Request',
@@ -257,6 +290,7 @@ export default function App() {
         const request = await api.createRequest(
           workspaceId,
           collectionId,
+          folderPath,
           values.name,
           values.type === 'graphql' ? 'graphql' : 'http'
         );
@@ -265,6 +299,7 @@ export default function App() {
           setSelection({
             kind: 'request',
             collectionId,
+            folderPath,
             requestId: request.id,
           });
         }
@@ -272,6 +307,30 @@ export default function App() {
     });
   }
 
+  function promptNewFolder(collectionId: string, parentPath: string[]) {
+    if (!workspaceId) return;
+    setPrompt({
+      title: 'New Folder',
+      fields: [{ name: 'name', label: 'Name', placeholder: 'Admin' }],
+      onSubmit: async (values) => {
+        const folder = await api.createFolder(
+          workspaceId,
+          collectionId,
+          parentPath,
+          values.name
+        );
+        await loadTree(workspaceId, true);
+        if (!editorDirtyRef.current) {
+          setSelection({
+            kind: 'folder',
+            collectionId,
+            folderPath: [...parentPath, folder.id],
+          });
+        }
+      },
+    });
+  }
+
   function promptNewEnvironment() {
     if (!workspaceId) return;
     setPrompt({
@@ -287,8 +346,12 @@ export default function App() {
     });
   }
 
-  function promptRenameRequest(collectionId: string, requestId: string) {
-    const request = findRequest(collectionId, requestId);
+  function promptRenameRequest(
+    collectionId: string,
+    folderPath: string[],
+    requestId: string
+  ) {
+    const request = findRequest(collectionId, folderPath, requestId);
     if (!request || !workspaceId) return;
     setPrompt({
       title: 'Rename Request',
@@ -297,7 +360,7 @@ export default function App() {
       onSubmit: async (values) => {
         const name = values.name.trim();
         if (!name) throw new Error('Name is required');
-        await api.updateRequest(workspaceId, collectionId, {
+        await api.updateRequest(workspaceId, collectionId, folderPath, {
           ...request,
           name,
         });
@@ -306,23 +369,32 @@ export default function App() {
     });
   }
 
-  function promptRenameCollection(collectionId: string) {
-    const collection = tree?.collections.find((c) => c.id === collectionId);
-    if (!collection || !workspaceId) return;
+  /** Renames a collection (folderPath []) or a folder. */
+  function promptRenameNode(collectionId: string, folderPath: string[]) {
+    if (!workspaceId) return;
+    const isFolder = folderPath.length > 0;
+    const node = isFolder
+      ? findFolder(collectionId, folderPath)
+      : findCollection(collectionId);
+    if (!node) return;
     setPrompt({
-      title: 'Rename Collection',
+      title: isFolder ? 'Rename Folder' : 'Rename Collection',
       submitLabel: 'Rename',
-      fields: [{ name: 'name', label: 'Name', initial: collection.name }],
+      fields: [{ name: 'name', label: 'Name', initial: node.name }],
       onSubmit: async (values) => {
         const name = values.name.trim();
         if (!name) throw new Error('Name is required');
-        await api.updateCollection(workspaceId, collectionId, { name });
+        if (isFolder) {
+          await api.updateFolder(workspaceId, collectionId, folderPath, { name });
+        } else {
+          await api.updateCollection(workspaceId, collectionId, { name });
+        }
         await loadTree(workspaceId, true);
       },
     });
   }
 
-  function promptImportCurl(collectionId: string) {
+  function promptImportCurl(collectionId: string, folderPath: string[]) {
     if (!workspaceId) return;
     setPrompt({
       title: 'Import cURL',
@@ -341,10 +413,11 @@ export default function App() {
         const created = await api.createRequest(
           workspaceId,
           collectionId,
+          folderPath,
           parsed.name,
           'http'
         );
-        await api.updateRequest(workspaceId, collectionId, {
+        await api.updateRequest(workspaceId, collectionId, folderPath, {
           ...parsed,
           id: created.id,
         });
@@ -353,6 +426,7 @@ export default function App() {
           setSelection({
             kind: 'request',
             collectionId,
+            folderPath,
             requestId: created.id,
           });
         }
@@ -373,8 +447,10 @@ export default function App() {
         result.kind === 'collection'
           ? `Imported ${result.requests} request${
               result.requests === 1 ? '' : 's'
-            } into ${result.collections} collection${
-              result.collections === 1 ? '' : 's'
+            }${
+              result.folders
+                ? ` across ${result.folders} folder${result.folders === 1 ? '' : 's'}`
+                : ''
             }.`
           : `Imported environment "${result.name}" with ${result.variables} variable${
               result.variables === 1 ? '' : 's'
@@ -387,6 +463,7 @@ export default function App() {
 
   async function copyRequestInto(
     collectionId: string,
+    folderPath: string[],
     source: ApiRequest,
     name: string
   ) {
@@ -395,10 +472,11 @@ export default function App() {
       const created = await api.createRequest(
         workspaceId,
         collectionId,
+        folderPath,
         name,
         source.type
       );
-      await api.updateRequest(workspaceId, collectionId, {
+      await api.updateRequest(workspaceId, collectionId, folderPath, {
         ...structuredClone(source),
         id: created.id,
         name,
@@ -409,15 +487,20 @@ export default function App() {
     }
   }
 
-  async function deleteRequestAction(collectionId: string, request: ApiRequest) {
+  async function deleteRequestAction(
+    collectionId: string,
+    folderPath: string[],
+    request: ApiRequest
+  ) {
     if (!workspaceId) return;
     if (!confirm(`Delete request "${request.name}"?`)) return;
     try {
-      await api.deleteRequest(workspaceId, collectionId, request.id);
+      await api.deleteRequest(workspaceId, collectionId, folderPath, request.id);
       setSelection((sel) =>
         sel?.kind === 'request' &&
         sel.collectionId === collectionId &&
-        sel.requestId === request.id
+        sel.requestId === request.id &&
+        sel.folderPath.join('/') === folderPath.join('/')
           ? null
           : sel
       );
@@ -428,24 +511,37 @@ export default function App() {
     }
   }
 
-  async function deleteCollectionAction(collection: {
-    id: string;
-    name: string;
-  }) {
+  /** Deletes a collection (folderPath []) or a folder, with its contents. */
+  async function deleteNode(collectionId: string, folderPath: string[]) {
     if (!workspaceId) return;
-    if (
-      !confirm(`Delete collection "${collection.name}" and all its requests?`)
-    ) {
+    const isFolder = folderPath.length > 0;
+    const node = isFolder
+      ? findFolder(collectionId, folderPath)
+      : findCollection(collectionId);
+    if (!node) return;
+    const label = isFolder ? 'folder' : 'collection';
+    if (!confirm(`Delete ${label} "${node.name}" and everything inside it?`)) {
       return;
     }
     try {
-      await api.deleteCollection(workspaceId, collection.id);
-      setSelection((sel) =>
-        (sel?.kind === 'collection' || sel?.kind === 'request') &&
-        sel.collectionId === collection.id
-          ? null
-          : sel
-      );
+      if (isFolder) {
+        await api.deleteFolder(workspaceId, collectionId, folderPath);
+      } else {
+        await api.deleteCollection(workspaceId, collectionId);
+      }
+      // Clear the selection if it pointed inside the deleted node.
+      setSelection((sel) => {
+        if (!sel || sel.kind === 'environment') return sel;
+        if (sel.collectionId !== collectionId) return sel;
+        const selPath =
+          sel.kind === 'collection' ? [] : sel.folderPath;
+        const prefix = folderPath.join('/');
+        const within =
+          selPath.join('/') === prefix ||
+          selPath.join('/').startsWith(prefix + '/') ||
+          (!isFolder);
+        return within ? null : sel;
+      });
       handleDirtyChange(false);
       await loadTree(workspaceId, true);
     } catch (err) {
@@ -486,21 +582,21 @@ export default function App() {
     }
 
     if (selection?.kind === 'request') {
-      const collection = tree.collections.find(
-        (c) => c.id === selection.collectionId
-      );
-      const request = collection?.requests.find(
-        (r) => r.id === selection.requestId
-      );
+      const { collectionId, folderPath, requestId } = selection;
+      const collection = findCollection(collectionId);
+      const request = findRequest(collectionId, folderPath, requestId);
       if (collection && request) {
         return (
           <RequestEditor
-            key={`${collection.id}/${request.id}`}
+            key={`${collectionId}/${folderPath.join('/')}/${request.id}`}
             workspaceId={tree.meta.id}
-            collectionId={collection.id}
+            collectionId={collectionId}
+            folderPath={folderPath}
             request={request}
             onSaved={() => loadTree(tree.meta.id, true)}
-            onDelete={() => deleteRequestAction(collection.id, request)}
+            onDelete={() =>
+              deleteRequestAction(collectionId, folderPath, request)
+            }
             onDirtyChange={handleDirtyChange}
             onVariablesChanged={() => loadTree(tree.meta.id, true)}
           />
@@ -509,19 +605,43 @@ export default function App() {
     }
 
     if (selection?.kind === 'collection') {
-      const collection = tree.collections.find(
-        (c) => c.id === selection.collectionId
-      );
+      const collection = findCollection(selection.collectionId);
       if (collection) {
         return (
-          <CollectionEditor
+          <NodeEditor
             key={collection.id}
-            collection={collection}
+            kind="collection"
+            node={collection}
             onSave={async (changes) => {
               await api.updateCollection(tree.meta.id, collection.id, changes);
               await loadTree(tree.meta.id, true);
             }}
-            onDelete={() => deleteCollectionAction(collection)}
+            onDelete={() => deleteNode(collection.id, [])}
+            onDirtyChange={handleDirtyChange}
+          />
+        );
+      }
+    }
+
+    if (selection?.kind === 'folder') {
+      const { collectionId, folderPath } = selection;
+      const folder = findFolder(collectionId, folderPath);
+      if (folder) {
+        return (
+          <NodeEditor
+            key={`${collectionId}/${folderPath.join('/')}`}
+            kind="folder"
+            node={folder}
+            onSave={async (changes) => {
+              await api.updateFolder(
+                tree.meta.id,
+                collectionId,
+                folderPath,
+                changes
+              );
+              await loadTree(tree.meta.id, true);
+            }}
+            onDelete={() => deleteNode(collectionId, folderPath)}
             onDirtyChange={handleDirtyChange}
           />
         );
@@ -602,36 +722,32 @@ export default function App() {
                 canPaste={clipboard !== null}
                 requestActions={{
                   onRename: promptRenameRequest,
-                  onCopy: (cid, rid) => {
-                    const request = findRequest(cid, rid);
+                  onCopy: (cid, fp, rid) => {
+                    const request = findRequest(cid, fp, rid);
                     if (request) setClipboard(structuredClone(request));
                   },
-                  onDuplicate: (cid, rid) => {
-                    const request = findRequest(cid, rid);
+                  onDuplicate: (cid, fp, rid) => {
+                    const request = findRequest(cid, fp, rid);
                     if (request) {
-                      void copyRequestInto(cid, request, `${request.name} copy`);
+                      void copyRequestInto(cid, fp, request, `${request.name} copy`);
                     }
                   },
-                  onDelete: (cid, rid) => {
-                    const request = findRequest(cid, rid);
-                    if (request) void deleteRequestAction(cid, request);
+                  onDelete: (cid, fp, rid) => {
+                    const request = findRequest(cid, fp, rid);
+                    if (request) void deleteRequestAction(cid, fp, request);
                   },
                 }}
-                collectionActions={{
+                nodeActions={{
                   onNewRequest: promptNewRequest,
-                  onRename: promptRenameCollection,
-                  onPasteRequest: (cid) => {
+                  onNewFolder: promptNewFolder,
+                  onRename: promptRenameNode,
+                  onPasteRequest: (cid, fp) => {
                     if (clipboard) {
-                      void copyRequestInto(cid, clipboard, clipboard.name);
+                      void copyRequestInto(cid, fp, clipboard, clipboard.name);
                     }
                   },
                   onImportCurl: promptImportCurl,
-                  onDelete: (cid) => {
-                    const collection = tree.collections.find(
-                      (c) => c.id === cid
-                    );
-                    if (collection) void deleteCollectionAction(collection);
-                  },
+                  onDelete: deleteNode,
                 }}
                 onSelect={selectGuarded}
                 onNewCollection={promptNewCollection}
diff --git a/client/src/api.ts b/client/src/api.ts
index 4458716..30207d2 100644
--- a/client/src/api.ts
+++ b/client/src/api.ts
@@ -3,6 +3,7 @@ import type {
   Collection,
   Environment,
   ExecutionResult,
+  Folder,
   KeyValue,
   RequestType,
   Scripts,
@@ -10,6 +11,12 @@ import type {
   WorkspaceTree,
 } from './types';
 
+/** Encodes a folder path (slugs, outer→inner) as a ?folderPath= query string. */
+const fpQuery = (folderPath: string[]): string =>
+  folderPath.length
+    ? `?folderPath=${encodeURIComponent(folderPath.join('/'))}`
+    : '';
+
 async function http<T>(path: string, init?: RequestInit): Promise<T> {
   const res = await fetch(path, {
     headers: { 'content-type': 'application/json' },
@@ -77,15 +84,53 @@ export const api = {
       method: 'DELETE',
     }),
 
-  createRequest: (id: string, cid: string, name: string, type: RequestType) =>
+  createFolder: (id: string, cid: string, parentPath: string[], name: string) =>
+    http<Folder>(
+      `/api/workspaces/${id}/collections/${cid}/folders`,
+      json({ name, folderPath: parentPath.join('/') })
+    ),
+
+  updateFolder: (
+    id: string,
+    cid: string,
+    folderPath: string[],
+    changes: { name?: string; description?: string; scripts?: Scripts }
+  ) =>
+    http<null>(
+      `/api/workspaces/${id}/collections/${cid}/folders${fpQuery(folderPath)}`,
+      {
+        method: 'PATCH',
+        body: JSON.stringify(changes),
+        headers: { 'content-type': 'application/json' },
+      }
+    ),
+
+  deleteFolder: (id: string, cid: string, folderPath: string[]) =>
+    http<null>(
+      `/api/workspaces/${id}/collections/${cid}/folders${fpQuery(folderPath)}`,
+      { method: 'DELETE' }
+    ),
+
+  createRequest: (
+    id: string,
+    cid: string,
+    folderPath: string[],
+    name: string,
+    type: RequestType
+  ) =>
     http<ApiRequest>(
       `/api/workspaces/${id}/collections/${cid}/requests`,
-      json({ name, type })
+      json({ name, type, folderPath: folderPath.join('/') })
     ),
 
-  updateRequest: (id: string, cid: string, request: ApiRequest) =>
+  updateRequest: (
+    id: string,
+    cid: string,
+    folderPath: string[],
+    request: ApiRequest
+  ) =>
     http<null>(
-      `/api/workspaces/${id}/collections/${cid}/requests/${request.id}`,
+      `/api/workspaces/${id}/collections/${cid}/requests/${request.id}${fpQuery(folderPath)}`,
       {
         method: 'PUT',
         body: JSON.stringify(request),
@@ -93,10 +138,11 @@ export const api = {
       }
     ),
 
-  deleteRequest: (id: string, cid: string, rid: string) =>
-    http<null>(`/api/workspaces/${id}/collections/${cid}/requests/${rid}`, {
-      method: 'DELETE',
-    }),
+  deleteRequest: (id: string, cid: string, folderPath: string[], rid: string) =>
+    http<null>(
+      `/api/workspaces/${id}/collections/${cid}/requests/${rid}${fpQuery(folderPath)}`,
+      { method: 'DELETE' }
+    ),
 
   createEnvironment: (id: string, name: string) =>
     http<Environment>(`/api/workspaces/${id}/environments`, json({ name })),
@@ -123,10 +169,15 @@ export const api = {
       json({ path })
     ),
 
-  execute: (id: string, request: ApiRequest, collectionId: string) =>
+  execute: (
+    id: string,
+    request: ApiRequest,
+    collectionId: string,
+    folderPath: string[] = []
+  ) =>
     http<ExecutionResult>(
       `/api/workspaces/${id}/execute`,
-      json({ request, collectionId })
+      json({ request, collectionId, folderPath: folderPath.join('/') })
     ),
 
   listCookies: (id: string) =>
@@ -152,5 +203,5 @@ export interface StoredCookie {
 }
 
 export type PostmanImportResult =
-  | { kind: 'collection'; collections: number; requests: number }
+  | { kind: 'collection'; collections: number; folders: number; requests: number }
   | { kind: 'environment'; name: string; variables: number };
diff --git a/client/src/components/CollectionEditor.tsx b/client/src/components/NodeEditor.tsx
similarity index 65%
rename from client/src/components/CollectionEditor.tsx
rename to client/src/components/NodeEditor.tsx
index 3be3b55..a49635e 100644
--- a/client/src/components/CollectionEditor.tsx
+++ b/client/src/components/NodeEditor.tsx
@@ -1,9 +1,17 @@
 import { useEffect, useState } from 'react';
-import type { Collection, Scripts } from '../types';
+import type { Scripts } from '../types';
 import { DocsEditor } from './DocsEditor';
 
+/** A collection or folder — both carry a name, description and scripts. */
+export interface EditableNode {
+  name: string;
+  description: string;
+  scripts: Scripts;
+}
+
 interface Props {
-  collection: Collection;
+  kind: 'collection' | 'folder';
+  node: EditableNode;
   onSave: (changes: {
     name: string;
     description: string;
@@ -15,23 +23,23 @@ interface Props {
 
 type Tab = 'description' | 'preReq' | 'tests';
 
-export function CollectionEditor({
-  collection,
-  onSave,
-  onDelete,
-  onDirtyChange,
-}: Props) {
-  const [name, setName] = useState(collection.name);
-  const [description, setDescription] = useState(collection.description);
-  const [scripts, setScripts] = useState(collection.scripts);
+/**
+ * Edits a container node: a collection or a folder. Both run pre-request/test
+ * scripts around every request they contain (folders nest within the
+ * collection's chain), so the editor is shared.
+ */
+export function NodeEditor({ kind, node, onSave, onDelete, onDirtyChange }: Props) {
+  const [name, setName] = useState(node.name);
+  const [description, setDescription] = useState(node.description);
+  const [scripts, setScripts] = useState(node.scripts);
   const [tab, setTab] = useState<Tab>('description');
   const [error, setError] = useState<string | null>(null);
 
   const dirty =
-    name !== collection.name ||
-    description !== collection.description ||
-    scripts.preRequest !== collection.scripts.preRequest ||
-    scripts.postResponse !== collection.scripts.postResponse;
+    name !== node.name ||
+    description !== node.description ||
+    scripts.preRequest !== node.scripts.preRequest ||
+    scripts.postResponse !== node.scripts.postResponse;
 
   useEffect(() => {
     onDirtyChange(dirty);
@@ -47,10 +55,14 @@ export function CollectionEditor({
     }
   }
 
+  const label = kind === 'collection' ? 'collection' : 'folder';
+
   return (
     <div className="pane-editor">
       <div className="editor-title-row">
-        <span className="type-badge type-collection">COL</span>
+        <span className={`type-badge type-${kind}`}>
+          {kind === 'collection' ? 'COL' : 'DIR'}
+        </span>
         <input
           className="name-input"
           value={name}
@@ -76,13 +88,13 @@ export function CollectionEditor({
             ['preReq', 'Pre-request'],
             ['tests', 'Tests'],
           ] as [Tab, string][]
-        ).map(([value, label]) => (
+        ).map(([value, tabLabel]) => (
           <button
             key={value}
             className={tab === value ? 'tab active' : 'tab'}
             onClick={() => setTab(value)}
           >
-            {label}
+            {tabLabel}
           </button>
         ))}
       </div>
@@ -91,20 +103,20 @@ export function CollectionEditor({
         <DocsEditor
           value={description}
           onChange={setDescription}
-          placeholder="Describe this collection in Markdown…"
+          placeholder={`Describe this ${label} in Markdown…`}
         />
       )}
 
       {tab === 'preReq' && (
         <div className="script-editor">
           <p className="muted">
-            Runs before <em>every</em> request in this collection, ahead of the
+            Runs before <em>every</em> request in this {label}, ahead of the
             request's own pre-request script.
           </p>
           <textarea
             className="code-area"
             value={scripts.preRequest}
-            placeholder="// collection pre-request script"
+            placeholder={`// ${label} pre-request script`}
             spellCheck={false}
             onChange={(e) =>
               setScripts((s) => ({ ...s, preRequest: e.target.value }))
@@ -116,13 +128,13 @@ export function CollectionEditor({
       {tab === 'tests' && (
         <div className="script-editor">
           <p className="muted">
-            Runs after <em>every</em> request in this collection, ahead of the
+            Runs after <em>every</em> request in this {label}, ahead of the
             request's own post-response script.
           </p>
           <textarea
             className="code-area"
             value={scripts.postResponse}
-            placeholder="// collection post-response script (tests)"
+            placeholder={`// ${label} post-response script (tests)`}
             spellCheck={false}
             onChange={(e) =>
               setScripts((s) => ({ ...s, postResponse: e.target.value }))
diff --git a/client/src/components/RequestEditor.tsx b/client/src/components/RequestEditor.tsx
index 1c06107..bf134b5 100644
--- a/client/src/components/RequestEditor.tsx
+++ b/client/src/components/RequestEditor.tsx
@@ -21,6 +21,7 @@ import { VarField } from './VarField';
 interface Props {
   workspaceId: string;
   collectionId: string;
+  folderPath: string[];
   request: ApiRequest;
   onSaved: (request: ApiRequest) => void;
   onDelete: () => void;
@@ -60,6 +61,7 @@ const BODY_MODES: { value: BodyMode; label: string }[] = [
 export function RequestEditor({
   workspaceId,
   collectionId,
+  folderPath,
   request,
   onSaved,
   onDelete,
@@ -105,7 +107,7 @@ export function RequestEditor({
     setSaveError(null);
     const clean = canonical(draft);
     try {
-      await api.updateRequest(workspaceId, collectionId, clean);
+      await api.updateRequest(workspaceId, collectionId, folderPath, clean);
       setSaved(clean);
       setDraft(clean);
       onSaved(clean);
@@ -118,7 +120,7 @@ export function RequestEditor({
     setExecuting(true);
     setExecError(null);
     try {
-      const result = await api.execute(workspaceId, draft, collectionId);
+      const result = await api.execute(workspaceId, draft, collectionId, folderPath);
       setResponse(result);
       // Scripts may have persisted environment variables; refresh so the
       // sidebar, variable highlights and env editor reflect the new values.
diff --git a/client/src/components/Sidebar.tsx b/client/src/components/Sidebar.tsx
index cb1e5e8..10fe05c 100644
--- a/client/src/components/Sidebar.tsx
+++ b/client/src/components/Sidebar.tsx
@@ -1,20 +1,22 @@
 import { useState, type MouseEvent } from 'react';
 import type { Selection } from '../selection';
-import type { WorkspaceTree } from '../types';
+import type { ApiRequest, Collection, Folder, WorkspaceTree } from '../types';
 
 export interface RequestActions {
-  onRename: (collectionId: string, requestId: string) => void;
-  onCopy: (collectionId: string, requestId: string) => void;
-  onDuplicate: (collectionId: string, requestId: string) => void;
-  onDelete: (collectionId: string, requestId: string) => void;
+  onRename: (collectionId: string, folderPath: string[], requestId: string) => void;
+  onCopy: (collectionId: string, folderPath: string[], requestId: string) => void;
+  onDuplicate: (collectionId: string, folderPath: string[], requestId: string) => void;
+  onDelete: (collectionId: string, folderPath: string[], requestId: string) => void;
 }
 
-export interface CollectionActions {
-  onNewRequest: (collectionId: string) => void;
-  onRename: (collectionId: string) => void;
-  onPasteRequest: (collectionId: string) => void;
-  onImportCurl: (collectionId: string) => void;
-  onDelete: (collectionId: string) => void;
+/** Actions on a container node — a collection (folderPath []) or a folder. */
+export interface NodeActions {
+  onNewRequest: (collectionId: string, folderPath: string[]) => void;
+  onNewFolder: (collectionId: string, folderPath: string[]) => void;
+  onRename: (collectionId: string, folderPath: string[]) => void;
+  onPasteRequest: (collectionId: string, folderPath: string[]) => void;
+  onImportCurl: (collectionId: string, folderPath: string[]) => void;
+  onDelete: (collectionId: string, folderPath: string[]) => void;
 }
 
 interface Props {
@@ -23,7 +25,7 @@ interface Props {
   width: number;
   canPaste: boolean;
   requestActions: RequestActions;
-  collectionActions: CollectionActions;
+  nodeActions: NodeActions;
   onSelect: (selection: Selection) => void;
   onNewCollection: () => void;
   onNewEnvironment: () => void;
@@ -31,9 +33,12 @@ interface Props {
 }
 
 interface MenuState {
-  kind: 'request' | 'collection';
+  kind: 'request' | 'node';
   collectionId: string;
+  folderPath: string[];
   requestId?: string;
+  /** True for a collection root node (vs. a folder), to label its menu. */
+  isCollection?: boolean;
   x: number;
   y: number;
 }
@@ -45,13 +50,18 @@ interface MenuItem {
   action: () => void;
 }
 
+const pathKey = (collectionId: string, folderPath: string[]): string =>
+  [collectionId, ...folderPath].join('/');
+
+const INDENT = 16;
+
 export function Sidebar({
   tree,
   selection,
   width,
   canPaste,
   requestActions,
-  collectionActions,
+  nodeActions,
   onSelect,
   onNewCollection,
   onNewEnvironment,
@@ -63,6 +73,9 @@ export function Sidebar({
   const isSelected = (sel: Selection): boolean =>
     JSON.stringify(sel) === JSON.stringify(selection);
 
+  const toggle = (key: string) =>
+    setCollapsed((c) => ({ ...c, [key]: !c[key] }));
+
   function openMenu(
     e: MouseEvent<HTMLButtonElement>,
     state: Omit<MenuState, 'x' | 'y'>
@@ -73,29 +86,174 @@ export function Sidebar({
   }
 
   function menuItems(m: MenuState): MenuItem[] {
-    const cid = m.collectionId;
+    const { collectionId: cid, folderPath: fp } = m;
     if (m.kind === 'request') {
       const rid = m.requestId!;
       return [
-        { label: 'Rename…', action: () => requestActions.onRename(cid, rid) },
-        { label: 'Copy', action: () => requestActions.onCopy(cid, rid) },
-        { label: 'Duplicate', action: () => requestActions.onDuplicate(cid, rid) },
-        { label: 'Delete', danger: true, action: () => requestActions.onDelete(cid, rid) },
+        { label: 'Rename…', action: () => requestActions.onRename(cid, fp, rid) },
+        { label: 'Copy', action: () => requestActions.onCopy(cid, fp, rid) },
+        { label: 'Duplicate', action: () => requestActions.onDuplicate(cid, fp, rid) },
+        { label: 'Delete', danger: true, action: () => requestActions.onDelete(cid, fp, rid) },
       ];
     }
     return [
-      { label: 'New Request…', action: () => collectionActions.onNewRequest(cid) },
-      { label: 'Rename…', action: () => collectionActions.onRename(cid) },
+      { label: 'New Request…', action: () => nodeActions.onNewRequest(cid, fp) },
+      { label: 'New Folder…', action: () => nodeActions.onNewFolder(cid, fp) },
+      { label: 'Rename…', action: () => nodeActions.onRename(cid, fp) },
       {
         label: 'Paste Request',
         disabled: !canPaste,
-        action: () => collectionActions.onPasteRequest(cid),
+        action: () => nodeActions.onPasteRequest(cid, fp),
+      },
+      { label: 'Import cURL…', action: () => nodeActions.onImportCurl(cid, fp) },
+      {
+        label: m.isCollection ? 'Delete Collection' : 'Delete Folder',
+        danger: true,
+        action: () => nodeActions.onDelete(cid, fp),
       },
-      { label: 'Import cURL…', action: () => collectionActions.onImportCurl(cid) },
-      { label: 'Delete', danger: true, action: () => collectionActions.onDelete(cid) },
     ];
   }
 
+  function renderRequest(
+    collectionId: string,
+    folderPath: string[],
+    request: ApiRequest,
+    depth: number
+  ) {
+    const sel: Selection = {
+      kind: 'request',
+      collectionId,
+      folderPath,
+      requestId: request.id,
+    };
+    return (
+      <div
+        key={`r:${request.id}`}
+        className={isSelected(sel) ? 'sidebar-row request-row selected' : 'sidebar-row request-row'}
+        style={{ paddingLeft: depth * INDENT + 22 }}
+      >
+        <button className="row-label" onClick={() => onSelect(sel)}>
+          <span
+            className={
+              request.type === 'graphql'
+                ? 'method-tag method-GQL'
+                : `method-tag method-${request.method}`
+            }
+          >
+            {request.type === 'graphql' ? 'GQL' : request.method}
+          </span>
+          {request.name}
+        </button>
+        <button
+          className="icon-btn"
+          title="Request actions"
+          onClick={(e) =>
+            openMenu(e, {
+              kind: 'request',
+              collectionId,
+              folderPath,
+              requestId: request.id,
+            })
+          }
+        >
+          ⋯
+        </button>
+      </div>
+    );
+  }
+
+  function renderFolder(
+    collectionId: string,
+    parentPath: string[],
+    folder: Folder,
+    depth: number
+  ) {
+    const folderPath = [...parentPath, folder.id];
+    const key = pathKey(collectionId, folderPath);
+    const sel: Selection = { kind: 'folder', collectionId, folderPath };
+    return (
+      <div key={`f:${folder.id}`}>
+        <div
+          className={isSelected(sel) ? 'sidebar-row selected' : 'sidebar-row'}
+          style={{ paddingLeft: depth * INDENT }}
+        >
+          <button className="icon-btn chevron" onClick={() => toggle(key)}>
+            {collapsed[key] ? '▸' : '▾'}
+          </button>
+          <button className="row-label" onClick={() => onSelect(sel)}>
+            <span className="folder-tag">▥</span>
+            {folder.name}
+          </button>
+          <button
+            className="icon-btn"
+            title="Folder actions"
+            onClick={(e) => openMenu(e, { kind: 'node', collectionId, folderPath })}
+          >
+            ⋯
+          </button>
+        </div>
+        {!collapsed[key] &&
+          renderChildren(collectionId, folderPath, folder, depth + 1)}
+      </div>
+    );
+  }
+
+  function renderChildren(
+    collectionId: string,
+    folderPath: string[],
+    node: { folders: Folder[]; requests: ApiRequest[] },
+    depth: number
+  ) {
+    return (
+      <>
+        {node.folders.map((f) => renderFolder(collectionId, folderPath, f, depth))}
+        {node.requests.map((r) => renderRequest(collectionId, folderPath, r, depth))}
+      </>
+    );
+  }
+
+  function renderCollection(collection: Collection) {
+    const key = pathKey(collection.id, []);
+    return (
+      <div key={collection.id}>
+        <div
+          className={
+            isSelected({ kind: 'collection', collectionId: collection.id })
+              ? 'sidebar-row selected'
+              : 'sidebar-row'
+          }
+        >
+          <button className="icon-btn chevron" onClick={() => toggle(key)}>
+            {collapsed[key] ? '▸' : '▾'}
+          </button>
+          <button
+            className="row-label"
+            onClick={() =>
+              onSelect({ kind: 'collection', collectionId: collection.id })
+            }
+          >
+            {collection.name}
+          </button>
+          <button
+            className="icon-btn"
+            title="Collection actions"
+            onClick={(e) =>
+              openMenu(e, {
+                kind: 'node',
+                collectionId: collection.id,
+                folderPath: [],
+                isCollection: true,
+              })
+            }
+          >
+            ⋯
+          </button>
+        </div>
+        {!collapsed[key] && renderChildren(collection.id, [], collection, 1)}
+      </div>
+    );
+  }
+
   return (
     <aside className="sidebar" style={{ width, minWidth: width }}>
       <div className="sidebar-section">
@@ -121,96 +279,7 @@ export function Sidebar({
         {tree.collections.length === 0 && (
           <p className="muted sidebar-empty">No collections yet.</p>
         )}
-        {tree.collections.map((collection) => (
-          <div key={collection.id}>
-            <div
-              className={
-                isSelected({ kind: 'collection', collectionId: collection.id })
-                  ? 'sidebar-row selected'
-                  : 'sidebar-row'
-              }
-            >
-              <button
-                className="icon-btn chevron"
-                onClick={() =>
-                  setCollapsed((c) => ({
-                    ...c,
-                    [collection.id]: !c[collection.id],
-                  }))
-                }
-              >
-                {collapsed[collection.id] ? '▸' : '▾'}
-              </button>
-              <button
-                className="row-label"
-                onClick={() =>
-                  onSelect({ kind: 'collection', collectionId: collection.id })
-                }
-              >
-                {collection.name}
-              </button>
-              <button
-                className="icon-btn"
-                title="Collection actions"
-                onClick={(e) =>
-                  openMenu(e, { kind: 'collection', collectionId: collection.id })
-                }
-              >
-                ⋯
-              </button>
-            </div>
-            {!collapsed[collection.id] &&
-              collection.requests.map((request) => (
-                <div
-                  key={request.id}
-                  className={
-                    isSelected({
-                      kind: 'request',
-                      collectionId: collection.id,
-                      requestId: request.id,
-                    })
-                      ? 'sidebar-row request-row selected'
-                      : 'sidebar-row request-row'
-                  }
-                >
-                  <button
-                    className="row-label"
-                    onClick={() =>
-                      onSelect({
-                        kind: 'request',
-                        collectionId: collection.id,
-                        requestId: request.id,
-                      })
-                    }
-                  >
-                    <span
-                      className={
-                        request.type === 'graphql'
-                          ? 'method-tag method-GQL'
-                          : `method-tag method-${request.method}`
-                      }
-                    >
-                      {request.type === 'graphql' ? 'GQL' : request.method}
-                    </span>
-                    {request.name}
-                  </button>
-                  <button
-                    className="icon-btn"
-                    title="Request actions"
-                    onClick={(e) =>
-                      openMenu(e, {
-                        kind: 'request',
-                        collectionId: collection.id,
-                        requestId: request.id,
-                      })
-                    }
-                  >
-                    ⋯
-                  </button>
-                </div>
-              ))}
-          </div>
-        ))}
+        {tree.collections.map((collection) => renderCollection(collection))}
       </div>
 
       <div className="sidebar-section">
diff --git a/client/src/selection.ts b/client/src/selection.ts
index be488cc..8f8bf06 100644
--- a/client/src/selection.ts
+++ b/client/src/selection.ts
@@ -1,5 +1,11 @@
 export type Selection =
-  | { kind: 'request'; collectionId: string; requestId: string }
+  | {
+      kind: 'request';
+      collectionId: string;
+      folderPath: string[];
+      requestId: string;
+    }
   | { kind: 'collection'; collectionId: string }
+  | { kind: 'folder'; collectionId: string; folderPath: string[] }
   | { kind: 'environment'; environmentId: string }
   | null;
diff --git a/client/src/styles.css b/client/src/styles.css
index 2a4b6d7..afdd609 100644
--- a/client/src/styles.css
+++ b/client/src/styles.css
@@ -175,8 +175,9 @@ pre,
   text-overflow: ellipsis;
 }
 
-.request-row {
-  margin-left: 22px;
+.folder-tag {
+  font-size: 0.78rem;
+  color: var(--text-muted);
 }
 
 .sidebar-empty {
@@ -286,6 +287,7 @@ pre,
 .type-graphql { background: #3b2436; color: var(--pink); }
 .type-env { background: #24303b; color: var(--blue); }
 .type-collection { background: #3b3324; color: var(--yellow); }
+.type-folder { background: #2a3340; color: var(--blue); }
 
 .ctx-backdrop {
   position: fixed;
diff --git a/client/src/types.ts b/client/src/types.ts
index a72ff6f..956971b 100644
--- a/client/src/types.ts
+++ b/client/src/types.ts
@@ -83,11 +83,22 @@ export interface ApiRequest {
   scripts: Scripts;
 }
 
+export interface Folder {
+  id: string;
+  name: string;
+  description: string;
+  scripts: Scripts;
+  folders: Folder[];
+  requests: ApiRequest[];
+}
+
 export interface Collection {
   id: string;
   name: string;
   description: string;
   scripts: Scripts;
+  folders: Folder[];
+  /** Requests sitting directly at the collection root (outside any folder). */
   requests: ApiRequest[];
 }
 
diff --git a/server/src/importer.ts b/server/src/importer.ts
index e144336..ef2f86e 100644
--- a/server/src/importer.ts
+++ b/server/src/importer.ts
@@ -5,13 +5,14 @@ import {
   convertEnvironment,
   detectPostmanKind,
   hasScripts,
+  type ConvertedFolder,
 } from './postmanImport.js';
-import type { WorkspaceMeta } from './types.js';
+import type { Scripts, WorkspaceMeta } from './types.js';
 import * as wsfs from './workspaceFs.js';
 import { expandHome, HttpError } from './workspaceFs.js';
 
 export type PostmanImportSummary =
-  | { kind: 'collection'; collections: number; requests: number }
+  | { kind: 'collection'; collections: number; folders: number; requests: number }
   | { kind: 'environment'; name: string; variables: number };
 
 /**
@@ -32,31 +33,69 @@ export function importPostmanFile(
 
   const kind = detectPostmanKind(json);
   if (kind === 'collection') {
-    const { groups } = convertCollection(json as never);
-    let requests = 0;
-    for (const group of groups) {
-      const collection = wsfs.createCollection(ws, group.name);
-      if (group.description || hasScripts(group.scripts)) {
-        wsfs.updateCollection(ws, collection.id, {
-          description: group.description,
-          scripts: hasScripts(group.scripts) ? group.scripts : undefined,
-        });
-      }
-      for (const request of group.requests) {
+    const converted = convertCollection(json as never);
+    const collection = wsfs.createCollection(ws, converted.name);
+    if (converted.description || hasScripts(converted.scripts)) {
+      wsfs.updateCollection(ws, collection.id, {
+        description: converted.description || undefined,
+        scripts: hasScripts(converted.scripts) ? converted.scripts : undefined,
+      });
+    }
+
+    const counts = { folders: 0, requests: 0 };
+
+    const writeRequests = (
+      folderPath: string[],
+      requests: ReturnType<typeof convertCollection>['requests']
+    ) => {
+      for (const request of requests) {
         const created = wsfs.createRequest(
           ws,
           collection.id,
+          folderPath,
           request.name,
           request.type
         );
-        wsfs.updateRequest(ws, collection.id, created.id, {
+        wsfs.updateRequest(ws, collection.id, folderPath, created.id, {
           ...request,
           id: created.id,
         });
-        requests += 1;
+        counts.requests += 1;
       }
-    }
-    return { kind, collections: groups.length, requests };
+    };
+
+    const writeFolders = (parentPath: string[], folders: ConvertedFolder[]) => {
+      for (const folder of folders) {
+        const created = wsfs.createFolder(
+          ws,
+          collection.id,
+          parentPath,
+          folder.name
+        );
+        counts.folders += 1;
+        const folderPath = [...parentPath, created.id];
+        const scripts: Scripts | undefined = hasScripts(folder.scripts)
+          ? folder.scripts
+          : undefined;
+        if (folder.description || scripts) {
+          wsfs.updateFolder(ws, collection.id, folderPath, {
+            description: folder.description || undefined,
+            scripts,
+          });
+        }
+        writeRequests(folderPath, folder.requests);
+        writeFolders(folderPath, folder.folders);
+      }
+    };
+
+    writeRequests([], converted.requests);
+    writeFolders([], converted.folders);
+    return {
+      kind,
+      collections: 1,
+      folders: counts.folders,
+      requests: counts.requests,
+    };
   }
 
   if (kind === 'environment') {
diff --git a/server/src/mcp.ts b/server/src/mcp.ts
index 76547fc..5291e0e 100644
--- a/server/src/mcp.ts
+++ b/server/src/mcp.ts
@@ -90,10 +90,50 @@ const auth = z.object({
     .optional(),
 });
 const graphql = z.object({ query: z.string(), variables: z.string() });
+/** A request/folder's location inside a collection: folder slugs, outer→inner. */
+const folderPath = z.array(z.string()).default([]);
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type Args = any;
 
+interface NodeSummary {
+  id?: string;
+  name?: string;
+  folders: NodeSummary[];
+  requests: { id: string; name: string; type: string; method: string; url: string }[];
+}
+
+/** Compact, recursive view of a collection/folder's requests and subfolders. */
+function summarizeNode(node: {
+  folders: import('./types.js').Folder[];
+  requests: ApiRequest[];
+}): NodeSummary {
+  return {
+    requests: node.requests.map((r) => ({
+      id: r.id,
+      name: r.name,
+      type: r.type,
+      method: r.method,
+      url: r.url,
+    })),
+    folders: node.folders.map((f) => ({
+      id: f.id,
+      name: f.name,
+      ...summarizeNode(f),
+    })),
+  };
+}
+
+function countRequests(node: {
+  folders: import('./types.js').Folder[];
+  requests: ApiRequest[];
+}): number {
+  return (
+    node.requests.length +
+    node.folders.reduce((sum, f) => sum + countRequests(f), 0)
+  );
+}
+
 function buildServer(): McpServer {
   const server = new McpServer({ name: 'api-notebook', version: '0.1.0' });
 
@@ -152,13 +192,7 @@ function buildServer(): McpServer {
           id: c.id,
           name: c.name,
           description: c.description,
-          requests: c.requests.map((r) => ({
-            id: r.id,
-            name: r.name,
-            type: r.type,
-            method: r.method,
-            url: r.url,
-          })),
+          ...summarizeNode(c),
         })),
         environments: tree.environments.map((e) => ({
           id: e.id,
@@ -173,16 +207,18 @@ function buildServer(): McpServer {
   reg(
     'get_request',
     {
-      description: 'Get a request in full (method, url, params, headers, auth, body, scripts, docs).',
+      description:
+        'Get a request in full (method, url, params, headers, auth, body, scripts, docs). Pass folderPath (folder slugs from the tree) when the request lives inside a folder.',
       inputSchema: {
         workspaceId: z.string(),
         collectionId: z.string(),
+        folderPath,
         requestId: z.string(),
       },
       annotations: readonly,
     },
-    ({ workspaceId, collectionId, requestId }: Args) =>
-      wsfs.getRequest(resolveWorkspace(workspaceId), collectionId, requestId)
+    ({ workspaceId, collectionId, folderPath: fp, requestId }: Args) =>
+      wsfs.getRequest(resolveWorkspace(workspaceId), collectionId, fp ?? [], requestId)
   );
 
   reg(
@@ -199,13 +235,7 @@ function buildServer(): McpServer {
         name: c.name,
         description: c.description,
         scripts: c.scripts,
-        requests: c.requests.map((r) => ({
-          id: r.id,
-          name: r.name,
-          type: r.type,
-          method: r.method,
-          url: r.url,
-        })),
+        ...summarizeNode(c),
       };
     }
   );
@@ -266,19 +296,58 @@ function buildServer(): McpServer {
     }
   );
 
+  reg(
+    'create_folder',
+    {
+      description:
+        'Create a folder inside a collection (pass folderPath to nest it inside an existing folder; omit or [] for the collection root). Returns the created folder.',
+      inputSchema: {
+        workspaceId: z.string(),
+        collectionId: z.string(),
+        folderPath,
+        name: z.string(),
+      },
+    },
+    ({ workspaceId, collectionId, folderPath: fp, name }: Args) =>
+      wsfs.createFolder(resolveWorkspace(workspaceId), collectionId, fp ?? [], name)
+  );
+
+  reg(
+    'update_folder',
+    {
+      description:
+        "Update a folder's name, description, or folder-level scripts (which run around every request inside it).",
+      inputSchema: {
+        workspaceId: z.string(),
+        collectionId: z.string(),
+        folderPath,
+        name: z.string().optional(),
+        description: z.string().optional(),
+        scripts: scripts.optional(),
+      },
+    },
+    ({ workspaceId, collectionId, folderPath: fp, name, description, scripts: s }: Args) => {
+      const ws = resolveWorkspace(workspaceId);
+      wsfs.updateFolder(ws, collectionId, fp ?? [], { name, description, scripts: s });
+      return wsfs.getCollection(ws, collectionId);
+    }
+  );
+
   reg(
     'create_request',
     {
-      description: 'Create a new request in a collection. Returns the created request.',
+      description:
+        'Create a new request in a collection (optionally inside a folder via folderPath). Returns the created request.',
       inputSchema: {
         workspaceId: z.string(),
         collectionId: z.string(),
+        folderPath,
         name: z.string(),
         type: z.enum(['http', 'graphql']).default('http'),
       },
     },
-    ({ workspaceId, collectionId, name, type }: Args) =>
-      wsfs.createRequest(resolveWorkspace(workspaceId), collectionId, name, type)
+    ({ workspaceId, collectionId, folderPath: fp, name, type }: Args) =>
+      wsfs.createRequest(resolveWorkspace(workspaceId), collectionId, fp ?? [], name, type)
   );
 
   reg(
@@ -289,6 +358,7 @@ function buildServer(): McpServer {
       inputSchema: {
         workspaceId: z.string(),
         collectionId: z.string(),
+        folderPath,
         requestId: z.string(),
         name: z.string().optional(),
         method: z.enum(METHODS).optional(),
@@ -304,7 +374,8 @@ function buildServer(): McpServer {
     },
     (a: Args) => {
       const ws = resolveWorkspace(a.workspaceId);
-      const existing = wsfs.getRequest(ws, a.collectionId, a.requestId);
+      const fp = a.folderPath ?? [];
+      const existing = wsfs.getRequest(ws, a.collectionId, fp, a.requestId);
       const merged: ApiRequest = {
         ...existing,
         ...(a.name !== undefined && { name: a.name }),
@@ -318,8 +389,8 @@ function buildServer(): McpServer {
         ...(a.docs !== undefined && { docs: a.docs }),
         ...(a.scripts !== undefined && { scripts: a.scripts }),
       };
-      wsfs.updateRequest(ws, a.collectionId, a.requestId, merged);
-      return wsfs.getRequest(ws, a.collectionId, a.requestId);
+      wsfs.updateRequest(ws, a.collectionId, fp, a.requestId, merged);
+      return wsfs.getRequest(ws, a.collectionId, fp, a.requestId);
     }
   );
 
@@ -333,13 +404,15 @@ function buildServer(): McpServer {
       inputSchema: {
         workspaceId: z.string(),
         collectionId: z.string(),
+        folderPath,
         requestId: z.string(),
       },
     },
-    async ({ workspaceId, collectionId, requestId }: Args) => {
+    async ({ workspaceId, collectionId, folderPath: fp, requestId }: Args) => {
       const ws = resolveWorkspace(workspaceId);
-      const request = wsfs.getRequest(ws, collectionId, requestId);
-      const collectionScripts = wsfs.getCollectionScripts(ws, collectionId);
+      const path = fp ?? [];
+      const request = wsfs.getRequest(ws, collectionId, path, requestId);
+      const collectionScripts = wsfs.getScriptChain(ws, collectionId, path);
       const activeId = appData.getActiveEnvironmentId(ws.id);
       const env = activeId ? wsfs.getEnvironment(ws, activeId) : undefined;
       const jar = cookies.loadJar(ws.id);
@@ -461,21 +534,23 @@ function buildServer(): McpServer {
       inputSchema: {
         workspaceId: z.string(),
         collectionId: z.string(),
+        folderPath,
         requestId: z.string(),
         confirm: z.boolean().default(false),
       },
       annotations: destructive,
     },
-    ({ workspaceId, collectionId, requestId, confirm }: Args) => {
+    ({ workspaceId, collectionId, folderPath: fp, requestId, confirm }: Args) => {
       const ws = resolveWorkspace(workspaceId);
-      const req = wsfs.getRequest(ws, collectionId, requestId);
+      const path = fp ?? [];
+      const req = wsfs.getRequest(ws, collectionId, path, requestId);
       if (!confirm) {
         return needsConfirmation(
           `Delete request "${req.name}" (${req.method})? This cannot be undone.`,
-          { tool: 'delete_request', workspaceId, collectionId, requestId }
+          { tool: 'delete_request', workspaceId, collectionId, folderPath: path, requestId }
         );
       }
-      wsfs.deleteRequest(ws, collectionId, requestId);
+      wsfs.deleteRequest(ws, collectionId, path, requestId);
       return { deleted: requestId };
     }
   );
@@ -497,7 +572,7 @@ function buildServer(): McpServer {
       const col = wsfs.getCollection(ws, collectionId);
       if (!confirm) {
         return needsConfirmation(
-          `Delete collection "${col.name}" and its ${col.requests.length} request(s)? This cannot be undone.`,
+          `Delete collection "${col.name}" and its ${countRequests(col)} request(s)? This cannot be undone.`,
           { tool: 'delete_collection', workspaceId, collectionId }
         );
       }
@@ -506,6 +581,41 @@ function buildServer(): McpServer {
     }
   );
 
+  reg(
+    'delete_folder',
+    {
+      description:
+        'Delete a folder and everything inside it (subfolders and requests). This cannot be undone. Two-step: call without confirm to get a summary, then call again with confirm: true to actually delete.',
+      inputSchema: {
+        workspaceId: z.string(),
+        collectionId: z.string(),
+        folderPath,
+        confirm: z.boolean().default(false),
+      },
+      annotations: destructive,
+    },
+    ({ workspaceId, collectionId, folderPath: fp, confirm }: Args) => {
+      const ws = resolveWorkspace(workspaceId);
+      const path = fp ?? [];
+      if (path.length === 0) throw new Error('A folderPath is required');
+      const col = wsfs.getCollection(ws, collectionId);
+      let node: { folders: import('./types.js').Folder[] } = col;
+      for (const slug of path) {
+        const next = node.folders.find((f) => f.id === slug);
+        if (!next) throw new Error(`Folder "${path.join('/')}" not found`);
+        node = next;
+      }
+      if (!confirm) {
+        return needsConfirmation(
+          `Delete folder "${path.join('/')}" and its ${countRequests(node as never)} request(s)? This cannot be undone.`,
+          { tool: 'delete_folder', workspaceId, collectionId, folderPath: path }
+        );
+      }
+      wsfs.deleteFolder(ws, collectionId, path);
+      return { deleted: path.join('/') };
+    }
+  );
+
   reg(
     'clear_cookies',
     {
diff --git a/server/src/postmanImport.test.ts b/server/src/postmanImport.test.ts
index fcd3c64..decff5a 100644
--- a/server/src/postmanImport.test.ts
+++ b/server/src/postmanImport.test.ts
@@ -56,23 +56,49 @@ describe('convertCollection', () => {
     ],
   };
 
-  const { groups } = convertCollection(collection as never);
-  const folder = groups.find((g) => g.name === 'Folder')!;
-  const root = groups.find((g) => g.name === 'My API')!;
+  const converted = convertCollection(collection as never);
+  const folder = converted.folders.find((f) => f.name === 'Folder')!;
   const req = folder.requests[0];
 
-  it('groups folders into collections and root requests under the collection name', () => {
-    expect(groups.map((g) => g.name).sort()).toEqual(['Folder', 'My API']);
-    expect(root.requests[0].name).toBe('Root req');
+  it('maps the collection to one collection, nesting folders and root requests', () => {
+    expect(converted.name).toBe('My API');
+    expect(converted.folders.map((f) => f.name)).toEqual(['Folder']);
+    expect(converted.requests.map((r) => r.name)).toEqual(['Root req']);
   });
 
-  it('inherits collection scripts into folders and keeps request scripts', () => {
-    expect(folder.scripts.preRequest).toBe('rootPre()'); // inherited from collection root
+  it('keeps collection-, folder- and request-level scripts on their own node', () => {
+    // Scripts are no longer combined down the chain; each node keeps its own.
+    expect(converted.scripts.preRequest).toBe('rootPre()');
+    expect(converted.scripts.postResponse).toBe('');
+    expect(folder.scripts.preRequest).toBe('');
     expect(folder.scripts.postResponse).toBe('folderTest()');
-    expect(root.scripts.preRequest).toBe('rootPre()');
     expect(req.scripts.postResponse).toBe('reqTest()');
   });
 
+  it('preserves deeper folder nesting', () => {
+    const nested = {
+      info: { name: 'N', schema: SCHEMA },
+      item: [
+        {
+          name: 'Outer',
+          item: [
+            {
+              name: 'Inner',
+              item: [
+                { name: 'Deep req', request: { method: 'GET', url: { raw: 'http://x/' } } },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+    const root = convertCollection(nested as never);
+    const inner = root.folders[0].folders[0];
+    expect(root.folders[0].name).toBe('Outer');
+    expect(inner.name).toBe('Inner');
+    expect(inner.requests[0].name).toBe('Deep req');
+  });
+
   it('maps method, URL (query split out), headers, auth, body and docs', () => {
     expect(req.method).toBe('POST');
     expect(req.url).toBe('{{base}}/things');
@@ -131,7 +157,7 @@ describe('convertCollection', () => {
         },
       ],
     };
-    const reqs = convertCollection(bodies as never).groups[0].requests;
+    const reqs = convertCollection(bodies as never).requests;
     const byName = Object.fromEntries(reqs.map((r) => [r.name, r]));
     expect(byName.form.body).toMatchObject({
       mode: 'form',
diff --git a/server/src/postmanImport.ts b/server/src/postmanImport.ts
index 1936191..661263e 100644
--- a/server/src/postmanImport.ts
+++ b/server/src/postmanImport.ts
@@ -85,7 +85,7 @@ interface PostmanItem {
 }
 
 interface PostmanCollection {
-  info?: { name?: string; schema?: string };
+  info?: { name?: string; schema?: string; description?: Described };
   item?: PostmanItem[];
   event?: PostmanEvent[];
 }
@@ -146,14 +146,6 @@ function joinScript(a: string, b: string): string {
   return a || b;
 }
 
-/** Combines an ancestor's scripts with a descendant folder's scripts. */
-function combineScripts(parent: Scripts, child: Scripts): Scripts {
-  return {
-    preRequest: joinScript(parent.preRequest, child.preRequest),
-    postResponse: joinScript(parent.postResponse, child.postResponse),
-  };
-}
-
 export function hasScripts(scripts: Scripts): boolean {
   return Boolean(scripts.preRequest || scripts.postResponse);
 }
@@ -297,69 +289,65 @@ function convertRequest(item: PostmanItem): ConvertedRequest {
   };
 }
 
-export interface ConvertedCollectionGroup {
+export interface ConvertedFolder {
   name: string;
   description: string;
   scripts: Scripts;
+  folders: ConvertedFolder[];
   requests: ConvertedRequest[];
 }
 
 export interface ConvertedCollection {
   name: string;
-  groups: ConvertedCollectionGroup[];
+  description: string;
+  scripts: Scripts;
+  folders: ConvertedFolder[];
+  requests: ConvertedRequest[];
+}
+
+interface ConvertedNode {
+  folders: ConvertedFolder[];
+  requests: ConvertedRequest[];
 }
 
 /**
- * Postman folders can nest, but our model has a single collection level, so
- * nested folders are flattened into collections named by their path
- * ("Parent / Child"). Requests sitting directly at the collection root go
- * into a collection named after the Postman collection itself.
+ * Postman items are either folders (they have a nested `item` array) or
+ * requests. We mirror that structure directly: folders become folders (keeping
+ * their own pre-request/test scripts and description) and requests become
+ * requests in the node that contains them. Postman runs collection- and
+ * folder-level scripts around each request; we preserve them per node and the
+ * runtime combines the chain at execution time.
  */
-export function convertCollection(json: PostmanCollection): ConvertedCollection {
-  const rootName = json.info?.name?.trim() || 'Imported';
-  const order: string[] = [];
-  const groups = new Map<string, ConvertedCollectionGroup>();
-
-  const ensure = (name: string, scripts: Scripts): ConvertedCollectionGroup => {
-    let group = groups.get(name);
-    if (!group) {
-      group = { name, description: '', scripts, requests: [] };
-      groups.set(name, group);
-      order.push(name);
+function convertNode(items: PostmanItem[]): ConvertedNode {
+  const folders: ConvertedFolder[] = [];
+  const requests: ConvertedRequest[] = [];
+  for (const item of items) {
+    if (Array.isArray(item.item)) {
+      const child = convertNode(item.item);
+      folders.push({
+        name: item.name ?? 'Folder',
+        description: describe(item.description),
+        scripts: eventsToScripts(item.event),
+        folders: child.folders,
+        requests: child.requests,
+      });
+    } else if (item.request) {
+      requests.push(convertRequest(item));
     }
-    return group;
-  };
+  }
+  return { folders, requests };
+}
 
-  // Postman runs collection- and folder-level scripts around every request;
-  // since folders are flattened into collections, each collection inherits the
-  // combined scripts of its ancestor chain (collection root → folders).
-  const walk = (
-    items: PostmanItem[],
-    pathParts: string[],
-    parentScripts: Scripts
-  ): void => {
-    for (const item of items) {
-      if (Array.isArray(item.item)) {
-        const childPath = [...pathParts, item.name ?? 'Folder'];
-        const childScripts = combineScripts(
-          parentScripts,
-          eventsToScripts(item.event)
-        );
-        walk(item.item, childPath, childScripts);
-        const desc = describe(item.description);
-        if (desc) {
-          const key = childPath.join(' / ');
-          if (groups.has(key)) groups.get(key)!.description = desc;
-        }
-      } else if (item.request) {
-        const key = pathParts.length ? pathParts.join(' / ') : rootName;
-        ensure(key, parentScripts).requests.push(convertRequest(item));
-      }
-    }
+/** A whole Postman collection maps to one of our collections, nesting intact. */
+export function convertCollection(json: PostmanCollection): ConvertedCollection {
+  const { folders, requests } = convertNode(json.item ?? []);
+  return {
+    name: json.info?.name?.trim() || 'Imported',
+    description: describe(json.info?.description),
+    scripts: eventsToScripts(json.event),
+    folders,
+    requests,
   };
-
-  walk(json.item ?? [], [], eventsToScripts(json.event));
-  return { name: rootName, groups: order.map((k) => groups.get(k)!) };
 }
 
 export interface ConvertedEnvironment {
diff --git a/server/src/router.integration.test.ts b/server/src/router.integration.test.ts
index c458656..808872b 100644
--- a/server/src/router.integration.test.ts
+++ b/server/src/router.integration.test.ts
@@ -129,3 +129,133 @@ describe('workspace/collection/request endpoints', () => {
     expect(res.body.script.tests[0]).toMatchObject({ name: 'ok', passed: true });
   });
 });
+
+describe('folder endpoints', () => {
+  let wsId: string;
+  let cid: string;
+  let folderId: string;
+
+  beforeAll(async () => {
+    const wd = fs.mkdtempSync(path.join(os.tmpdir(), 'apinb-folders-'));
+    const ws = await request(app)
+      .post('/api/workspaces')
+      .send({ name: 'Folders WS', path: wd })
+      .expect(201);
+    wsId = ws.body.id;
+    const col = await request(app)
+      .post(`/api/workspaces/${wsId}/collections`)
+      .send({ name: 'C' })
+      .expect(201);
+    cid = col.body.id;
+  });
+
+  it('creates a folder, a nested folder, and a request inside it', async () => {
+    const folder = await request(app)
+      .post(`/api/workspaces/${wsId}/collections/${cid}/folders`)
+      .send({ name: 'Admin' })
+      .expect(201);
+    folderId = folder.body.id;
+    const sub = await request(app)
+      .post(`/api/workspaces/${wsId}/collections/${cid}/folders`)
+      .send({ name: 'Users', folderPath: folderId })
+      .expect(201);
+
+    await request(app)
+      .post(`/api/workspaces/${wsId}/collections/${cid}/requests`)
+      .send({ name: 'List', type: 'http', folderPath: `${folderId}/${sub.body.id}` })
+      .expect(201);
+
+    const tree = await request(app).get(`/api/workspaces/${wsId}`).expect(200);
+    const col = tree.body.collections.find((c: { id: string }) => c.id === cid);
+    const admin = col.folders.find((f: { id: string }) => f.id === folderId);
+    expect(admin.name).toBe('Admin');
+    expect(admin.folders[0].name).toBe('Users');
+    expect(admin.folders[0].requests.map((r: { name: string }) => r.name)).toEqual([
+      'List',
+    ]);
+  });
+
+  it("runs a folder's scripts in the execution chain", async () => {
+    await request(app)
+      .patch(`/api/workspaces/${wsId}/collections/${cid}/folders?folderPath=${folderId}`)
+      .send({
+        scripts: {
+          preRequest: '',
+          postResponse: 'pm.test("folder", () => pm.expect(true).to.be.ok);',
+        },
+      })
+      .expect(204);
+
+    const full = {
+      id: 'r',
+      name: 'r',
+      type: 'http',
+      method: 'GET',
+      url: `${targetBase}/x`,
+      params: [],
+      headers: [],
+      auth: { type: 'none' },
+      body: { mode: 'none', content: '', form: [], formData: [], binaryPath: '' },
+      graphql: { query: '', variables: '' },
+      docs: '',
+      scripts: { preRequest: '', postResponse: '' },
+    };
+    const res = await request(app)
+      .post(`/api/workspaces/${wsId}/execute`)
+      .send({ request: full, collectionId: cid, folderPath: folderId })
+      .expect(200);
+    expect(res.body.script.tests.map((t: { name: string }) => t.name)).toContain(
+      'folder'
+    );
+  });
+
+  it('deletes a folder and its contents', async () => {
+    await request(app)
+      .delete(`/api/workspaces/${wsId}/collections/${cid}/folders?folderPath=${folderId}`)
+      .expect(204);
+    const tree = await request(app).get(`/api/workspaces/${wsId}`).expect(200);
+    const col = tree.body.collections.find((c: { id: string }) => c.id === cid);
+    expect(col.folders).toEqual([]);
+  });
+
+  it('imports a Postman collection preserving folder nesting', async () => {
+    const fixture = path.join(wsDir, 'export.json');
+    fs.writeFileSync(
+      fixture,
+      JSON.stringify({
+        info: {
+          name: 'Imported',
+          schema:
+            'https://schema.getpostman.com/json/collection/v2.1.0/collection.json',
+        },
+        item: [
+          {
+            name: 'Group',
+            item: [
+              { name: 'Ping', request: { method: 'GET', url: { raw: 'http://x/ping' } } },
+            ],
+          },
+          { name: 'Root', request: { method: 'GET', url: { raw: 'http://x/root' } } },
+        ],
+      })
+    );
+    const res = await request(app)
+      .post(`/api/workspaces/${wsId}/import/postman`)
+      .send({ path: fixture })
+      .expect(200);
+    expect(res.body).toMatchObject({
+      kind: 'collection',
+      collections: 1,
+      folders: 1,
+      requests: 2,
+    });
+
+    const tree = await request(app).get(`/api/workspaces/${wsId}`).expect(200);
+    const imported = tree.body.collections.find(
+      (c: { name: string }) => c.name === 'Imported'
+    );
+    expect(imported.folders[0].name).toBe('Group');
+    expect(imported.folders[0].requests[0].name).toBe('Ping');
+    expect(imported.requests.map((r: { name: string }) => r.name)).toEqual(['Root']);
+  });
+});
diff --git a/server/src/router.ts b/server/src/router.ts
index 299fd76..8235883 100644
--- a/server/src/router.ts
+++ b/server/src/router.ts
@@ -27,6 +27,12 @@ function requireString(value: unknown, field: string): string {
   return value.trim();
 }
 
+/** A folder path is a slash-joined string of folder slugs ("" means root). */
+function parseFolderPath(value: unknown): string[] {
+  if (typeof value !== 'string' || !value) return [];
+  return value.split('/').filter(Boolean);
+}
+
 export const router = Router();
 
 router.post(
@@ -147,13 +153,48 @@ router.delete(
   })
 );
 
+router.post(
+  '/workspaces/:id/collections/:cid/folders',
+  wrap((req, res) => {
+    const ws = getWorkspace(req.params.id);
+    const name = requireString(req.body.name, 'name');
+    const parentPath = parseFolderPath(req.body.folderPath);
+    res.status(201).json(wsfs.createFolder(ws, req.params.cid, parentPath, name));
+  })
+);
+
+router.patch(
+  '/workspaces/:id/collections/:cid/folders',
+  wrap((req, res) => {
+    const ws = getWorkspace(req.params.id);
+    wsfs.updateFolder(ws, req.params.cid, parseFolderPath(req.query.folderPath), {
+      name: req.body.name,
+      description: req.body.description,
+      scripts: req.body.scripts,
+    });
+    res.status(204).end();
+  })
+);
+
+router.delete(
+  '/workspaces/:id/collections/:cid/folders',
+  wrap((req, res) => {
+    const ws = getWorkspace(req.params.id);
+    wsfs.deleteFolder(ws, req.params.cid, parseFolderPath(req.query.folderPath));
+    res.status(204).end();
+  })
+);
+
 router.post(
   '/workspaces/:id/collections/:cid/requests',
   wrap((req, res) => {
     const ws = getWorkspace(req.params.id);
     const name = requireString(req.body.name, 'name');
     const type = req.body.type === 'graphql' ? 'graphql' : 'http';
-    res.status(201).json(wsfs.createRequest(ws, req.params.cid, name, type));
+    const folderPath = parseFolderPath(req.body.folderPath);
+    res
+      .status(201)
+      .json(wsfs.createRequest(ws, req.params.cid, folderPath, name, type));
   })
 );
 
@@ -164,6 +205,7 @@ router.put(
     wsfs.updateRequest(
       ws,
       req.params.cid,
+      parseFolderPath(req.query.folderPath),
       req.params.rid,
       req.body as ApiRequest
     );
@@ -175,7 +217,12 @@ router.delete(
   '/workspaces/:id/collections/:cid/requests/:rid',
   wrap((req, res) => {
     const ws = getWorkspace(req.params.id);
-    wsfs.deleteRequest(ws, req.params.cid, req.params.rid);
+    wsfs.deleteRequest(
+      ws,
+      req.params.cid,
+      parseFolderPath(req.query.folderPath),
+      req.params.rid
+    );
     res.status(204).end();
   })
 );
@@ -231,8 +278,9 @@ router.post(
     }
     const collectionId =
       typeof req.body.collectionId === 'string' ? req.body.collectionId : null;
+    const folderPath = parseFolderPath(req.body.folderPath);
     const collectionScripts = collectionId
-      ? wsfs.getCollectionScripts(ws, collectionId)
+      ? wsfs.getScriptChain(ws, collectionId, folderPath)
       : { preRequest: '', postResponse: '' };
 
     const activeId = appData.getActiveEnvironmentId(ws.id);
diff --git a/server/src/types.ts b/server/src/types.ts
index 10ee122..39fdb81 100644
--- a/server/src/types.ts
+++ b/server/src/types.ts
@@ -73,11 +73,22 @@ export interface ApiRequest {
   scripts: Scripts;
 }
 
+export interface Folder {
+  id: string;
+  name: string;
+  description: string;
+  scripts: Scripts;
+  folders: Folder[];
+  requests: ApiRequest[];
+}
+
 export interface Collection {
   id: string;
   name: string;
   description: string;
   scripts: Scripts;
+  folders: Folder[];
+  /** Requests sitting directly at the collection root (outside any folder). */
   requests: ApiRequest[];
 }
 
diff --git a/server/src/workspaceFs.test.ts b/server/src/workspaceFs.test.ts
index 6643556..87e121c 100644
--- a/server/src/workspaceFs.test.ts
+++ b/server/src/workspaceFs.test.ts
@@ -33,7 +33,7 @@ describe('collections & requests (round-trip)', () => {
 
   it('persists a request (incl. scripts and docs) and reads it back', () => {
     const col = wsfs.createCollection(ws, 'C');
-    const created = wsfs.createRequest(ws, col.id, 'Get user', 'http');
+    const created = wsfs.createRequest(ws, col.id, [], 'Get user', 'http');
     const full = {
       ...created,
       method: 'POST' as const,
@@ -42,26 +42,74 @@ describe('collections & requests (round-trip)', () => {
       scripts: { preRequest: 'a()', postResponse: 'b()' },
       docs: '# Title\n\nbody',
     };
-    wsfs.updateRequest(ws, col.id, created.id, full);
+    wsfs.updateRequest(ws, col.id, [], created.id, full);
 
-    const read = wsfs.getRequest(ws, col.id, created.id);
+    const read = wsfs.getRequest(ws, col.id, [], created.id);
     expect(read.method).toBe('POST');
     expect(read.url).toBe('{{base}}/users/1');
     expect(read.scripts).toEqual({ preRequest: 'a()', postResponse: 'b()' });
     expect(read.docs).toContain('# Title');
-    // docs are stored as a sibling .md file
+    // docs are stored as a sibling .md file in the collection directory
     expect(
-      fs.existsSync(path.join(dir, 'collections', col.id, 'requests', `${created.id}.md`))
+      fs.existsSync(path.join(dir, 'collections', col.id, `${created.id}.md`))
     ).toBe(true);
 
     const tree = wsfs.readTree(ws, null);
     expect(tree.collections[0].requests.map((r) => r.name)).toContain('Get user');
   });
 
-  it('back-fills missing fields when reading an older request file', () => {
+  it('round-trips folders, nesting and folder-level metadata', () => {
+    const col = wsfs.createCollection(ws, 'API');
+    const outer = wsfs.createFolder(ws, col.id, [], 'Outer');
+    const inner = wsfs.createFolder(ws, col.id, [outer.id], 'Inner');
+    wsfs.updateFolder(ws, col.id, [outer.id, inner.id], {
+      description: 'inner docs',
+      scripts: { preRequest: 'inPre()', postResponse: '' },
+    });
+    const req = wsfs.createRequest(ws, col.id, [outer.id, inner.id], 'Deep', 'http');
+
+    expect(wsfs.getRequest(ws, col.id, [outer.id, inner.id], req.id).name).toBe('Deep');
+
+    const collection = wsfs
+      .readTree(ws, null)
+      .collections.find((c) => c.id === col.id)!;
+    const readInner = collection.folders[0].folders[0];
+    expect(collection.folders[0].name).toBe('Outer');
+    expect(readInner.name).toBe('Inner');
+    expect(readInner.description).toBe('inner docs');
+    expect(readInner.requests.map((r) => r.name)).toEqual(['Deep']);
+  });
+
+  it('combines collection and folder scripts down the chain', () => {
+    const col = wsfs.createCollection(ws, 'Chain');
+    wsfs.updateCollection(ws, col.id, {
+      scripts: { preRequest: 'colPre()', postResponse: 'colTest()' },
+    });
+    const f = wsfs.createFolder(ws, col.id, [], 'F');
+    wsfs.updateFolder(ws, col.id, [f.id], {
+      scripts: { preRequest: 'fPre()', postResponse: '' },
+    });
+    const chain = wsfs.getScriptChain(ws, col.id, [f.id]);
+    expect(chain.preRequest).toBe('colPre()\n\nfPre()');
+    expect(chain.postResponse).toBe('colTest()');
+  });
+
+  it('deletes a folder and everything inside it', () => {
+    const col = wsfs.createCollection(ws, 'Del');
+    const f = wsfs.createFolder(ws, col.id, [], 'Gone');
+    wsfs.createRequest(ws, col.id, [f.id], 'Doomed', 'http');
+    wsfs.deleteFolder(ws, col.id, [f.id]);
+    const collection = wsfs
+      .readTree(ws, null)
+      .collections.find((c) => c.id === col.id)!;
+    expect(collection.folders).toEqual([]);
+  });
+
+  it('back-fills missing fields and reads a legacy requests/ subdir', () => {
     const col = wsfs.createCollection(ws, 'Old');
+    // Pre-folders workspaces stored requests in a legacy requests/ subdir.
     const reqDir = path.join(dir, 'collections', col.id, 'requests');
-    // A request written before body/scripts/graphql fields existed.
+    fs.mkdirSync(reqDir, { recursive: true });
     fs.writeFileSync(
       path.join(reqDir, 'legacy.json'),
       JSON.stringify({
@@ -74,7 +122,13 @@ describe('collections & requests (round-trip)', () => {
         auth: { type: 'none' },
       })
     );
-    const read = wsfs.getRequest(ws, col.id, 'legacy');
+    // The legacy request still surfaces at the collection root.
+    const collection = wsfs
+      .readTree(ws, null)
+      .collections.find((c) => c.id === col.id)!;
+    expect(collection.requests.map((r) => r.id)).toContain('legacy');
+
+    const read = wsfs.getRequest(ws, col.id, [], 'legacy');
     expect(read.body).toEqual({
       mode: 'none',
       content: '',
diff --git a/server/src/workspaceFs.ts b/server/src/workspaceFs.ts
index c669829..1b9e2a9 100644
--- a/server/src/workspaceFs.ts
+++ b/server/src/workspaceFs.ts
@@ -6,12 +6,22 @@ import type {
   ApiRequest,
   Collection,
   Environment,
+  Folder,
   RequestType,
+  Scripts,
   WorkspaceMeta,
   WorkspaceTree,
 } from './types.js';
 
 const WORKSPACE_FILE = 'workspace.json';
+const FOLDER_FILE = 'folder.json';
+const COLLECTION_FILE = 'collection.json';
+/**
+ * Pre-folders workspaces stored a collection's requests in a `requests/`
+ * subdirectory. We still read that layout, but never write to it.
+ */
+const LEGACY_REQUESTS_DIR = 'requests';
+const emptyScripts = (): Scripts => ({ preRequest: '', postResponse: '' });
 const LOCAL_ENV_IGNORE = 'environments/*.local.json';
 
 export class HttpError extends Error {
@@ -63,14 +73,32 @@ function environmentsDir(ws: WorkspaceMeta): string {
 
 function collectionDir(ws: WorkspaceMeta, collectionId: string): string {
   const dir = path.join(collectionsDir(ws), collectionId);
-  if (!fs.existsSync(path.join(dir, 'collection.json'))) {
+  if (!fs.existsSync(path.join(dir, COLLECTION_FILE))) {
     throw new HttpError(404, `Collection "${collectionId}" not found`);
   }
   return dir;
 }
 
-function requestsDir(ws: WorkspaceMeta, collectionId: string): string {
-  return path.join(collectionDir(ws, collectionId), 'requests');
+/**
+ * Resolves the on-disk directory for a node (a collection root when folderPath
+ * is empty, or a nested folder), validating that each folder in the path exists.
+ */
+function nodeDir(
+  ws: WorkspaceMeta,
+  collectionId: string,
+  folderPath: string[]
+): string {
+  let dir = collectionDir(ws, collectionId);
+  for (const slug of folderPath) {
+    dir = path.join(dir, slug);
+    if (!fs.existsSync(path.join(dir, FOLDER_FILE))) {
+      throw new HttpError(
+        404,
+        `Folder "${folderPath.join('/')}" not found in collection "${collectionId}"`
+      );
+    }
+  }
+  return dir;
 }
 
 function listJsonFiles(dir: string): string[] {
@@ -90,6 +118,40 @@ function listDirs(dir: string): string[] {
     .sort();
 }
 
+/** Names (without .json) of request files directly inside a node directory. */
+function requestIdsIn(dir: string): string[] {
+  return listJsonFiles(dir)
+    .filter((f) => f !== COLLECTION_FILE && f !== FOLDER_FILE)
+    .map((f) => f.replace(/\.json$/, ''));
+}
+
+/** Slugs of the subfolders inside a node directory (dirs holding a folder.json). */
+function subfolderSlugsIn(dir: string): string[] {
+  return listDirs(dir).filter((d) =>
+    fs.existsSync(path.join(dir, d, FOLDER_FILE))
+  );
+}
+
+/**
+ * Resolves the directory a request file lives in. Requests written by the
+ * current version sit directly in their node directory; older root-level
+ * requests may still live in a legacy `requests/` subdirectory.
+ */
+function requestFileDir(
+  ws: WorkspaceMeta,
+  collectionId: string,
+  folderPath: string[],
+  id: string
+): string {
+  const dir = nodeDir(ws, collectionId, folderPath);
+  if (fs.existsSync(path.join(dir, `${id}.json`))) return dir;
+  if (folderPath.length === 0) {
+    const legacy = path.join(dir, LEGACY_REQUESTS_DIR);
+    if (fs.existsSync(path.join(legacy, `${id}.json`))) return legacy;
+  }
+  return dir;
+}
+
 export function createWorkspace(name: string, dirPath: string): WorkspaceMeta {
   const abs = path.resolve(expandHome(dirPath));
   const wsFile = path.join(abs, WORKSPACE_FILE);
@@ -172,22 +234,55 @@ function readRequest(
   };
 }
 
+/** Reads the requests and subfolders contained directly in a node directory. */
+function readNodeChildren(dir: string): {
+  folders: Folder[];
+  requests: ApiRequest[];
+} {
+  const requests = requestIdsIn(dir).map((id) => readRequest(dir, id));
+  // Older root-level requests may still live in a legacy `requests/` subdir.
+  const legacy = path.join(dir, LEGACY_REQUESTS_DIR);
+  if (!fs.existsSync(path.join(legacy, FOLDER_FILE))) {
+    for (const id of requestIdsIn(legacy)) requests.push(readRequest(legacy, id));
+  }
+  requests.sort((a, b) => a.id.localeCompare(b.id));
+  const folders = subfolderSlugsIn(dir).map((slug) =>
+    readFolder(path.join(dir, slug), slug)
+  );
+  return { folders, requests };
+}
+
+function readFolder(dir: string, id: string): Folder {
+  const meta = readJson<{
+    name: string;
+    description?: string;
+    scripts?: Partial<Scripts>;
+  }>(path.join(dir, FOLDER_FILE));
+  const { folders, requests } = readNodeChildren(dir);
+  return {
+    id,
+    name: meta.name,
+    description: meta.description ?? '',
+    scripts: { ...emptyScripts(), ...meta.scripts },
+    folders,
+    requests,
+  };
+}
+
 function readCollection(ws: WorkspaceMeta, id: string): Collection {
   const dir = path.join(collectionsDir(ws), id);
   const meta = readJson<{
     name: string;
     description?: string;
-    scripts?: Partial<Collection['scripts']>;
-  }>(path.join(dir, 'collection.json'));
-  const reqDir = path.join(dir, 'requests');
-  const requests = listJsonFiles(reqDir).map((f) =>
-    readRequest(reqDir, f.replace(/\.json$/, ''))
-  );
+    scripts?: Partial<Scripts>;
+  }>(path.join(dir, COLLECTION_FILE));
+  const { folders, requests } = readNodeChildren(dir);
   return {
     id,
     name: meta.name,
     description: meta.description ?? '',
-    scripts: { preRequest: '', postResponse: '', ...meta.scripts },
+    scripts: { ...emptyScripts(), ...meta.scripts },
+    folders,
     requests,
   };
 }
@@ -225,7 +320,7 @@ export function readTree(
 ): WorkspaceTree {
   const collections = listDirs(collectionsDir(ws))
     .filter((d) =>
-      fs.existsSync(path.join(collectionsDir(ws), d, 'collection.json'))
+      fs.existsSync(path.join(collectionsDir(ws), d, COLLECTION_FILE))
     )
     .map((d) => readCollection(ws, d));
   const environments = listJsonFiles(environmentsDir(ws))
@@ -244,10 +339,10 @@ export function createCollection(ws: WorkspaceMeta, name: string): Collection {
   const taken = new Set(listDirs(collectionsDir(ws)));
   const id = uniqueSlug(slugify(name), taken);
   const dir = path.join(collectionsDir(ws), id);
-  const scripts = { preRequest: '', postResponse: '' };
-  fs.mkdirSync(path.join(dir, 'requests'), { recursive: true });
-  writeJson(path.join(dir, 'collection.json'), { name, description: '', scripts });
-  return { id, name, description: '', scripts, requests: [] };
+  const scripts = emptyScripts();
+  fs.mkdirSync(dir, { recursive: true });
+  writeJson(path.join(dir, COLLECTION_FILE), { name, description: '', scripts });
+  return { id, name, description: '', scripts, folders: [], requests: [] };
 }
 
 export function updateCollection(
@@ -255,17 +350,16 @@ export function updateCollection(
   id: string,
   changes: { name?: string; description?: string; scripts?: Collection['scripts'] }
 ): void {
-  const file = path.join(collectionDir(ws, id), 'collection.json');
+  const file = path.join(collectionDir(ws, id), COLLECTION_FILE);
   const meta = readJson<{
     name: string;
     description?: string;
-    scripts?: Collection['scripts'];
+    scripts?: Scripts;
   }>(file);
   writeJson(file, {
     name: changes.name ?? meta.name,
     description: changes.description ?? meta.description ?? '',
-    scripts: changes.scripts ??
-      meta.scripts ?? { preRequest: '', postResponse: '' },
+    scripts: changes.scripts ?? meta.scripts ?? emptyScripts(),
   });
 }
 
@@ -273,26 +367,104 @@ export function deleteCollection(ws: WorkspaceMeta, id: string): void {
   fs.rmSync(collectionDir(ws, id), { recursive: true, force: true });
 }
 
-export function getCollectionScripts(
+export function getCollection(ws: WorkspaceMeta, id: string): Collection {
+  return readCollection(ws, id);
+}
+
+// ----- folders -----
+
+export function createFolder(
   ws: WorkspaceMeta,
-  id: string
-): Collection['scripts'] {
-  const file = path.join(collectionDir(ws, id), 'collection.json');
-  if (!fs.existsSync(file)) return { preRequest: '', postResponse: '' };
-  const meta = readJson<{ scripts?: Partial<Collection['scripts']> }>(file);
-  return { preRequest: '', postResponse: '', ...meta.scripts };
+  collectionId: string,
+  parentPath: string[],
+  name: string
+): Folder {
+  const parent = nodeDir(ws, collectionId, parentPath);
+  const taken = new Set(subfolderSlugsIn(parent));
+  const id = uniqueSlug(slugify(name), taken);
+  const dir = path.join(parent, id);
+  const scripts = emptyScripts();
+  fs.mkdirSync(dir, { recursive: true });
+  writeJson(path.join(dir, FOLDER_FILE), { name, description: '', scripts });
+  return { id, name, description: '', scripts, folders: [], requests: [] };
 }
 
-export function getCollection(ws: WorkspaceMeta, id: string): Collection {
-  return readCollection(ws, id);
+export function updateFolder(
+  ws: WorkspaceMeta,
+  collectionId: string,
+  folderPath: string[],
+  changes: { name?: string; description?: string; scripts?: Scripts }
+): void {
+  if (folderPath.length === 0) {
+    throw new HttpError(400, 'A folder path is required');
+  }
+  const dir = nodeDir(ws, collectionId, folderPath);
+  const file = path.join(dir, FOLDER_FILE);
+  const meta = readJson<{
+    name: string;
+    description?: string;
+    scripts?: Scripts;
+  }>(file);
+  writeJson(file, {
+    name: changes.name ?? meta.name,
+    description: changes.description ?? meta.description ?? '',
+    scripts: changes.scripts ?? meta.scripts ?? emptyScripts(),
+  });
+}
+
+export function deleteFolder(
+  ws: WorkspaceMeta,
+  collectionId: string,
+  folderPath: string[]
+): void {
+  if (folderPath.length === 0) {
+    throw new HttpError(400, 'A folder path is required');
+  }
+  fs.rmSync(nodeDir(ws, collectionId, folderPath), {
+    recursive: true,
+    force: true,
+  });
+}
+
+/**
+ * Combines the pre-request/post-response scripts that wrap a request: the
+ * collection's, then each folder's down the path. Postman runs these outer →
+ * inner around every request.
+ */
+export function getScriptChain(
+  ws: WorkspaceMeta,
+  collectionId: string,
+  folderPath: string[]
+): Scripts {
+  const chain = emptyScripts();
+  const append = (file: string) => {
+    if (!fs.existsSync(file)) return;
+    const meta = readJson<{ scripts?: Partial<Scripts> }>(file);
+    const s = { ...emptyScripts(), ...meta.scripts };
+    chain.preRequest = joinScripts(chain.preRequest, s.preRequest);
+    chain.postResponse = joinScripts(chain.postResponse, s.postResponse);
+  };
+  let dir = collectionDir(ws, collectionId);
+  append(path.join(dir, COLLECTION_FILE));
+  for (const slug of folderPath) {
+    dir = path.join(dir, slug);
+    append(path.join(dir, FOLDER_FILE));
+  }
+  return chain;
+}
+
+function joinScripts(a: string, b: string): string {
+  if (a.trim() && b.trim()) return `${a}\n\n${b}`;
+  return a.trim() ? a : b;
 }
 
 export function getRequest(
   ws: WorkspaceMeta,
   collectionId: string,
+  folderPath: string[],
   id: string
 ): ApiRequest {
-  const dir = requestsDir(ws, collectionId);
+  const dir = requestFileDir(ws, collectionId, folderPath, id);
   if (!fs.existsSync(path.join(dir, `${id}.json`))) {
     throw new HttpError(404, `Request "${id}" not found`);
   }
@@ -323,13 +495,19 @@ export function defaultRequest(
 export function createRequest(
   ws: WorkspaceMeta,
   collectionId: string,
+  folderPath: string[],
   name: string,
   type: RequestType
 ): ApiRequest {
-  const dir = requestsDir(ws, collectionId);
-  const taken = new Set(
-    listJsonFiles(dir).map((f) => f.replace(/\.json$/, ''))
-  );
+  const dir = nodeDir(ws, collectionId, folderPath);
+  const taken = new Set(requestIdsIn(dir));
+  // Avoid colliding with a root-level request still in the legacy requests/ dir.
+  if (folderPath.length === 0) {
+    const legacy = path.join(dir, LEGACY_REQUESTS_DIR);
+    if (!fs.existsSync(path.join(legacy, FOLDER_FILE))) {
+      for (const legacyId of requestIdsIn(legacy)) taken.add(legacyId);
+    }
+  }
   const id = uniqueSlug(slugify(name), taken);
   const request = defaultRequest(id, name, type);
   writeRequestFiles(dir, request);
@@ -350,10 +528,11 @@ function writeRequestFiles(dir: string, request: ApiRequest): void {
 export function updateRequest(
   ws: WorkspaceMeta,
   collectionId: string,
+  folderPath: string[],
   id: string,
   request: ApiRequest
 ): void {
-  const dir = requestsDir(ws, collectionId);
+  const dir = requestFileDir(ws, collectionId, folderPath, id);
   if (!fs.existsSync(path.join(dir, `${id}.json`))) {
     throw new HttpError(404, `Request "${id}" not found`);
   }
@@ -363,9 +542,10 @@ export function updateRequest(
 export function deleteRequest(
   ws: WorkspaceMeta,
   collectionId: string,
+  folderPath: string[],
   id: string
 ): void {
-  const dir = requestsDir(ws, collectionId);
+  const dir = requestFileDir(ws, collectionId, folderPath, id);
   fs.rmSync(path.join(dir, `${id}.json`), { force: true });
   fs.rmSync(path.join(dir, `${id}.md`), { force: true });
 }

From f39afa420b7bc919badd022730a18f766ddeb18e Mon Sep 17 00:00:00 2001
From: Tapiwa Muzira <tapsmuzira@gmail.com>
Date: Wed, 17 Jun 2026 14:48:18 +0200
Subject: [PATCH 2/8] Add drag-and-drop reparenting of requests and folders
 (move endpoint, MCP tools, sidebar DnD, tests).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 CHANGELOG.md                          |   2 +
 client/src/App.tsx                    |  57 +++++++++++++
 client/src/api.ts                     |  28 +++++++
 client/src/components/Sidebar.tsx     | 111 +++++++++++++++++++++++---
 client/src/styles.css                 |   6 ++
 server/src/mcp.ts                     |  47 +++++++++++
 server/src/router.integration.test.ts |  23 ++++++
 server/src/router.ts                  |  37 +++++++++
 server/src/workspaceFs.test.ts        |  73 +++++++++++++++++
 server/src/workspaceFs.ts             |  93 +++++++++++++++++++++
 10 files changed, 468 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 58dcf0a..11ad0c3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ See [RELEASING.md](RELEASING.md) for the release process.
   preserve their folder structure instead of flattening it into separate
   collections. On disk, folders are mirrored as nested directories; pre-folders
   workspaces still load (their requests appear at the collection root).
+- **Drag-and-drop** to move requests and folders between folders and
+  collections in the sidebar (moving a folder takes its contents along).
 - Documentation now has **edit** and **preview** modes (request docs and
   collection descriptions). Existing docs open in a read-only rendered preview
   with an **Edit** button; empty docs open straight in the editor; a **Done**
diff --git a/client/src/App.tsx b/client/src/App.tsx
index f778a39..a407ec8 100644
--- a/client/src/App.tsx
+++ b/client/src/App.tsx
@@ -549,6 +549,61 @@ export default function App() {
     }
   }
 
+  async function moveRequestAction(
+    from: { collectionId: string; folderPath: string[]; requestId: string },
+    to: { collectionId: string; folderPath: string[] }
+  ) {
+    if (!workspaceId) return;
+    try {
+      const result = await api.moveRequest(workspaceId, from, to);
+      await loadTree(workspaceId, true);
+      setSelection((sel) =>
+        sel?.kind === 'request' &&
+        sel.collectionId === from.collectionId &&
+        sel.requestId === from.requestId &&
+        sel.folderPath.join('/') === from.folderPath.join('/')
+          ? {
+              kind: 'request',
+              collectionId: result.collectionId,
+              folderPath: result.folderPath,
+              requestId: result.requestId,
+            }
+          : sel
+      );
+    } catch (err) {
+      showError(err);
+    }
+  }
+
+  async function moveFolderAction(
+    from: { collectionId: string; folderPath: string[] },
+    to: { collectionId: string; folderPath: string[] }
+  ) {
+    if (!workspaceId) return;
+    try {
+      const result = await api.moveFolder(workspaceId, from, to);
+      await loadTree(workspaceId, true);
+      // Remap a selection that pointed inside the moved subtree to its new path.
+      setSelection((sel) => {
+        if (!sel || sel.kind === 'environment' || sel.kind === 'collection') {
+          return sel;
+        }
+        if (sel.collectionId !== from.collectionId) return sel;
+        const fromKey = from.folderPath.join('/');
+        const selKey = sel.folderPath.join('/');
+        if (selKey !== fromKey && !selKey.startsWith(fromKey + '/')) return sel;
+        const suffix = sel.folderPath.slice(from.folderPath.length);
+        return {
+          ...sel,
+          collectionId: result.collectionId,
+          folderPath: [...result.folderPath, ...suffix],
+        };
+      });
+    } catch (err) {
+      showError(err);
+    }
+  }
+
   async function selectEnvironment(environmentId: string | null) {
     if (!workspaceId) return;
     try {
@@ -749,6 +804,8 @@ export default function App() {
                   onImportCurl: promptImportCurl,
                   onDelete: deleteNode,
                 }}
+                onMoveRequest={moveRequestAction}
+                onMoveFolder={moveFolderAction}
                 onSelect={selectGuarded}
                 onNewCollection={promptNewCollection}
                 onNewEnvironment={promptNewEnvironment}
diff --git a/client/src/api.ts b/client/src/api.ts
index 30207d2..f0bc147 100644
--- a/client/src/api.ts
+++ b/client/src/api.ts
@@ -111,6 +111,34 @@ export const api = {
       { method: 'DELETE' }
     ),
 
+  moveRequest: (
+    id: string,
+    from: { collectionId: string; folderPath: string[]; requestId: string },
+    to: { collectionId: string; folderPath: string[] }
+  ) =>
+    http<{ collectionId: string; folderPath: string[]; requestId: string }>(
+      `/api/workspaces/${id}/move`,
+      json({
+        kind: 'request',
+        from: { ...from, folderPath: from.folderPath.join('/') },
+        to: { ...to, folderPath: to.folderPath.join('/') },
+      })
+    ),
+
+  moveFolder: (
+    id: string,
+    from: { collectionId: string; folderPath: string[] },
+    to: { collectionId: string; folderPath: string[] }
+  ) =>
+    http<{ collectionId: string; folderPath: string[] }>(
+      `/api/workspaces/${id}/move`,
+      json({
+        kind: 'folder',
+        from: { ...from, folderPath: from.folderPath.join('/') },
+        to: { ...to, folderPath: to.folderPath.join('/') },
+      })
+    ),
+
   createRequest: (
     id: string,
     cid: string,
diff --git a/client/src/components/Sidebar.tsx b/client/src/components/Sidebar.tsx
index 10fe05c..0c60b22 100644
--- a/client/src/components/Sidebar.tsx
+++ b/client/src/components/Sidebar.tsx
@@ -1,4 +1,4 @@
-import { useState, type MouseEvent } from 'react';
+import { useState, type DragEvent, type MouseEvent } from 'react';
 import type { Selection } from '../selection';
 import type { ApiRequest, Collection, Folder, WorkspaceTree } from '../types';
 
@@ -26,12 +26,24 @@ interface Props {
   canPaste: boolean;
   requestActions: RequestActions;
   nodeActions: NodeActions;
+  onMoveRequest: (
+    from: { collectionId: string; folderPath: string[]; requestId: string },
+    to: { collectionId: string; folderPath: string[] }
+  ) => void;
+  onMoveFolder: (
+    from: { collectionId: string; folderPath: string[] },
+    to: { collectionId: string; folderPath: string[] }
+  ) => void;
   onSelect: (selection: Selection) => void;
   onNewCollection: () => void;
   onNewEnvironment: () => void;
   onImportPostman: () => void;
 }
 
+type DragItem =
+  | { kind: 'request'; collectionId: string; folderPath: string[]; requestId: string }
+  | { kind: 'folder'; collectionId: string; folderPath: string[] };
+
 interface MenuState {
   kind: 'request' | 'node';
   collectionId: string;
@@ -62,6 +74,8 @@ export function Sidebar({
   canPaste,
   requestActions,
   nodeActions,
+  onMoveRequest,
+  onMoveFolder,
   onSelect,
   onNewCollection,
   onNewEnvironment,
@@ -69,6 +83,8 @@ export function Sidebar({
 }: Props) {
   const [collapsed, setCollapsed] = useState<Record<string, boolean>>({});
   const [menu, setMenu] = useState<MenuState | null>(null);
+  const [drag, setDrag] = useState<DragItem | null>(null);
+  const [dropKey, setDropKey] = useState<string | null>(null);
 
   const isSelected = (sel: Selection): boolean =>
     JSON.stringify(sel) === JSON.stringify(selection);
@@ -76,6 +92,79 @@ export function Sidebar({
   const toggle = (key: string) =>
     setCollapsed((c) => ({ ...c, [key]: !c[key] }));
 
+  /** Whether the dragged item may drop into the given node (not a no-op/cycle). */
+  function canDrop(item: DragItem, cid: string, folderPath: string[]): boolean {
+    if (item.kind === 'folder') {
+      if (item.collectionId !== cid) return true;
+      const fromKey = item.folderPath.join('/');
+      const intoKey = folderPath.slice(0, item.folderPath.length).join('/');
+      // Into itself or a descendant.
+      if (folderPath.length >= item.folderPath.length && intoKey === fromKey) {
+        return false;
+      }
+      // Into its current parent (no change).
+      return item.folderPath.slice(0, -1).join('/') !== folderPath.join('/');
+    }
+    // Request: a no-op when it's already in this node.
+    return !(
+      item.collectionId === cid &&
+      item.folderPath.join('/') === folderPath.join('/')
+    );
+  }
+
+  function onDropInto(cid: string, folderPath: string[]) {
+    const item = drag;
+    setDrag(null);
+    setDropKey(null);
+    if (!item || !canDrop(item, cid, folderPath)) return;
+    if (item.kind === 'request') {
+      onMoveRequest(
+        {
+          collectionId: item.collectionId,
+          folderPath: item.folderPath,
+          requestId: item.requestId,
+        },
+        { collectionId: cid, folderPath }
+      );
+    } else {
+      onMoveFolder(
+        { collectionId: item.collectionId, folderPath: item.folderPath },
+        { collectionId: cid, folderPath }
+      );
+    }
+  }
+
+  /** Drop-target handlers for a node (collection or folder). */
+  function dropTarget(cid: string, folderPath: string[], key: string) {
+    return {
+      onDragOver: (e: DragEvent) => {
+        if (!drag || !canDrop(drag, cid, folderPath)) return;
+        e.preventDefault();
+        if (dropKey !== key) setDropKey(key);
+      },
+      onDragLeave: () => setDropKey((k) => (k === key ? null : k)),
+      onDrop: (e: DragEvent) => {
+        e.preventDefault();
+        onDropInto(cid, folderPath);
+      },
+    };
+  }
+
+  function dragSource(item: DragItem) {
+    return {
+      draggable: true,
+      onDragStart: (e: DragEvent) => {
+        e.dataTransfer.effectAllowed = 'move';
+        e.dataTransfer.setData('text/plain', '');
+        setDrag(item);
+      },
+      onDragEnd: () => {
+        setDrag(null);
+        setDropKey(null);
+      },
+    };
+  }
+
   function openMenu(
     e: MouseEvent<HTMLButtonElement>,
     state: Omit<MenuState, 'x' | 'y'>
@@ -131,6 +220,7 @@ export function Sidebar({
         key={`r:${request.id}`}
         className={isSelected(sel) ? 'sidebar-row request-row selected' : 'sidebar-row request-row'}
         style={{ paddingLeft: depth * INDENT + 22 }}
+        {...dragSource({ kind: 'request', collectionId, folderPath, requestId: request.id })}
       >
         <button className="row-label" onClick={() => onSelect(sel)}>
           <span
@@ -171,11 +261,16 @@ export function Sidebar({
     const folderPath = [...parentPath, folder.id];
     const key = pathKey(collectionId, folderPath);
     const sel: Selection = { kind: 'folder', collectionId, folderPath };
+    const cls =
+      (isSelected(sel) ? 'sidebar-row selected' : 'sidebar-row') +
+      (dropKey === key ? ' drop-target' : '');
     return (
       <div key={`f:${folder.id}`}>
         <div
-          className={isSelected(sel) ? 'sidebar-row selected' : 'sidebar-row'}
+          className={cls}
           style={{ paddingLeft: depth * INDENT }}
+          {...dragSource({ kind: 'folder', collectionId, folderPath })}
+          {...dropTarget(collectionId, folderPath, key)}
         >
           <button className="icon-btn chevron" onClick={() => toggle(key)}>
             {collapsed[key] ? '▸' : '▾'}
@@ -214,15 +309,13 @@ export function Sidebar({
 
   function renderCollection(collection: Collection) {
     const key = pathKey(collection.id, []);
+    const cls =
+      (isSelected({ kind: 'collection', collectionId: collection.id })
+        ? 'sidebar-row selected'
+        : 'sidebar-row') + (dropKey === key ? ' drop-target' : '');
     return (
       <div key={collection.id}>
-        <div
-          className={
-            isSelected({ kind: 'collection', collectionId: collection.id })
-              ? 'sidebar-row selected'
-              : 'sidebar-row'
-          }
-        >
+        <div className={cls} {...dropTarget(collection.id, [], key)}>
           <button className="icon-btn chevron" onClick={() => toggle(key)}>
             {collapsed[key] ? '▸' : '▾'}
           </button>
diff --git a/client/src/styles.css b/client/src/styles.css
index afdd609..061d825 100644
--- a/client/src/styles.css
+++ b/client/src/styles.css
@@ -149,6 +149,12 @@ pre,
   background: rgba(255, 122, 69, 0.13);
 }
 
+.sidebar-row.drop-target {
+  outline: 1px dashed var(--accent, #ff7a45);
+  outline-offset: -1px;
+  background: rgba(255, 122, 69, 0.08);
+}
+
 .sidebar-row .icon-btn {
   visibility: hidden;
 }
diff --git a/server/src/mcp.ts b/server/src/mcp.ts
index 5291e0e..7e952f8 100644
--- a/server/src/mcp.ts
+++ b/server/src/mcp.ts
@@ -394,6 +394,53 @@ function buildServer(): McpServer {
     }
   );
 
+  reg(
+    'move_request',
+    {
+      description:
+        'Move a request into another folder or collection. folderPath/toFolderPath are folder slugs (omit or [] for a collection root); toCollectionId defaults to the source collection. Returns the new location (the id may change if it collided).',
+      inputSchema: {
+        workspaceId: z.string(),
+        collectionId: z.string(),
+        folderPath,
+        requestId: z.string(),
+        toCollectionId: z.string().optional(),
+        toFolderPath: z.array(z.string()).default([]),
+      },
+    },
+    (a: Args) => {
+      const ws = resolveWorkspace(a.workspaceId);
+      return wsfs.moveRequest(
+        ws,
+        { collectionId: a.collectionId, folderPath: a.folderPath ?? [], requestId: a.requestId },
+        { collectionId: a.toCollectionId ?? a.collectionId, folderPath: a.toFolderPath ?? [] }
+      );
+    }
+  );
+
+  reg(
+    'move_folder',
+    {
+      description:
+        'Move a folder (with everything inside it) under a new parent folder or collection. Cannot move a folder into itself or its own subfolder. Returns the new folder path.',
+      inputSchema: {
+        workspaceId: z.string(),
+        collectionId: z.string(),
+        folderPath,
+        toCollectionId: z.string().optional(),
+        toFolderPath: z.array(z.string()).default([]),
+      },
+    },
+    (a: Args) => {
+      const ws = resolveWorkspace(a.workspaceId);
+      return wsfs.moveFolder(
+        ws,
+        { collectionId: a.collectionId, folderPath: a.folderPath ?? [] },
+        { collectionId: a.toCollectionId ?? a.collectionId, folderPath: a.toFolderPath ?? [] }
+      );
+    }
+  );
+
   // ---- execute ----
 
   reg(
diff --git a/server/src/router.integration.test.ts b/server/src/router.integration.test.ts
index 808872b..220f896 100644
--- a/server/src/router.integration.test.ts
+++ b/server/src/router.integration.test.ts
@@ -209,6 +209,29 @@ describe('folder endpoints', () => {
     );
   });
 
+  it('moves a request into a folder via the move endpoint', async () => {
+    const r = await request(app)
+      .post(`/api/workspaces/${wsId}/collections/${cid}/requests`)
+      .send({ name: 'Loose', type: 'http' })
+      .expect(201);
+
+    const moved = await request(app)
+      .post(`/api/workspaces/${wsId}/move`)
+      .send({
+        kind: 'request',
+        from: { collectionId: cid, folderPath: '', requestId: r.body.id },
+        to: { collectionId: cid, folderPath: folderId },
+      })
+      .expect(200);
+    expect(moved.body.folderPath).toEqual([folderId]);
+
+    const tree = await request(app).get(`/api/workspaces/${wsId}`).expect(200);
+    const col = tree.body.collections.find((c: { id: string }) => c.id === cid);
+    const admin = col.folders.find((f: { id: string }) => f.id === folderId);
+    expect(admin.requests.map((x: { id: string }) => x.id)).toContain(r.body.id);
+    expect(col.requests.map((x: { id: string }) => x.id)).not.toContain(r.body.id);
+  });
+
   it('deletes a folder and its contents', async () => {
     await request(app)
       .delete(`/api/workspaces/${wsId}/collections/${cid}/folders?folderPath=${folderId}`)
diff --git a/server/src/router.ts b/server/src/router.ts
index 8235883..639bfc4 100644
--- a/server/src/router.ts
+++ b/server/src/router.ts
@@ -260,6 +260,43 @@ router.delete(
   })
 );
 
+router.post(
+  '/workspaces/:id/move',
+  wrap((req, res) => {
+    const ws = getWorkspace(req.params.id);
+    const from = req.body.from ?? {};
+    const to = req.body.to ?? {};
+    const dest = {
+      collectionId: requireString(to.collectionId, 'to.collectionId'),
+      folderPath: parseFolderPath(to.folderPath),
+    };
+    if (req.body.kind === 'folder') {
+      res.json(
+        wsfs.moveFolder(
+          ws,
+          {
+            collectionId: requireString(from.collectionId, 'from.collectionId'),
+            folderPath: parseFolderPath(from.folderPath),
+          },
+          dest
+        )
+      );
+    } else {
+      res.json(
+        wsfs.moveRequest(
+          ws,
+          {
+            collectionId: requireString(from.collectionId, 'from.collectionId'),
+            folderPath: parseFolderPath(from.folderPath),
+            requestId: requireString(from.requestId, 'from.requestId'),
+          },
+          dest
+        )
+      );
+    }
+  })
+);
+
 router.post(
   '/workspaces/:id/import/postman',
   wrap((req, res) => {
diff --git a/server/src/workspaceFs.test.ts b/server/src/workspaceFs.test.ts
index 87e121c..86fe19a 100644
--- a/server/src/workspaceFs.test.ts
+++ b/server/src/workspaceFs.test.ts
@@ -141,6 +141,79 @@ describe('collections & requests (round-trip)', () => {
   });
 });
 
+describe('move (reparent)', () => {
+  it('moves a request into a folder and back out', () => {
+    const col = wsfs.createCollection(ws, 'M');
+    const folder = wsfs.createFolder(ws, col.id, [], 'Sub');
+    const req = wsfs.createRequest(ws, col.id, [], 'Item', 'http');
+
+    const moved = wsfs.moveRequest(
+      ws,
+      { collectionId: col.id, folderPath: [], requestId: req.id },
+      { collectionId: col.id, folderPath: [folder.id] }
+    );
+    expect(moved.folderPath).toEqual([folder.id]);
+
+    const collection = wsfs
+      .readTree(ws, null)
+      .collections.find((c) => c.id === col.id)!;
+    expect(collection.requests).toEqual([]);
+    expect(collection.folders[0].requests.map((r) => r.id)).toEqual([req.id]);
+  });
+
+  it('moves a request across collections, uniquifying a colliding slug', () => {
+    const a = wsfs.createCollection(ws, 'A');
+    const b = wsfs.createCollection(ws, 'B');
+    const src = wsfs.createRequest(ws, a.id, [], 'Get', 'http');
+    wsfs.createRequest(ws, b.id, [], 'Get', 'http'); // occupies the "get" slug in B
+
+    const moved = wsfs.moveRequest(
+      ws,
+      { collectionId: a.id, folderPath: [], requestId: src.id },
+      { collectionId: b.id, folderPath: [] }
+    );
+    expect(moved.collectionId).toBe(b.id);
+    expect(moved.requestId).toBe('get-2');
+    const bCol = wsfs.readTree(ws, null).collections.find((c) => c.id === b.id)!;
+    expect(bCol.requests.map((r) => r.id).sort()).toEqual(['get', 'get-2']);
+  });
+
+  it('moves a folder under another folder', () => {
+    const col = wsfs.createCollection(ws, 'F');
+    const outer = wsfs.createFolder(ws, col.id, [], 'Outer');
+    const loose = wsfs.createFolder(ws, col.id, [], 'Loose');
+    wsfs.createRequest(ws, col.id, [loose.id], 'Inside', 'http');
+
+    const moved = wsfs.moveFolder(
+      ws,
+      { collectionId: col.id, folderPath: [loose.id] },
+      { collectionId: col.id, folderPath: [outer.id] }
+    );
+    expect(moved.folderPath).toEqual([outer.id, loose.id]);
+
+    const collection = wsfs
+      .readTree(ws, null)
+      .collections.find((c) => c.id === col.id)!;
+    expect(collection.folders.map((f) => f.id)).toEqual([outer.id]);
+    const nested = collection.folders[0].folders[0];
+    expect(nested.id).toBe(loose.id);
+    expect(nested.requests.map((r) => r.name)).toEqual(['Inside']);
+  });
+
+  it('refuses to move a folder into its own descendant', () => {
+    const col = wsfs.createCollection(ws, 'G');
+    const parent = wsfs.createFolder(ws, col.id, [], 'Parent');
+    const child = wsfs.createFolder(ws, col.id, [parent.id], 'Child');
+    expect(() =>
+      wsfs.moveFolder(
+        ws,
+        { collectionId: col.id, folderPath: [parent.id] },
+        { collectionId: col.id, folderPath: [parent.id, child.id] }
+      )
+    ).toThrow(/itself or its own subfolder/);
+  });
+});
+
 describe('environment secret split', () => {
   it('keeps secret values out of the shared file and merges them back on read', () => {
     const env = wsfs.createEnvironment(ws, 'dev');
diff --git a/server/src/workspaceFs.ts b/server/src/workspaceFs.ts
index 1b9e2a9..ec4a074 100644
--- a/server/src/workspaceFs.ts
+++ b/server/src/workspaceFs.ts
@@ -550,6 +550,99 @@ export function deleteRequest(
   fs.rmSync(path.join(dir, `${id}.md`), { force: true });
 }
 
+// ----- move (reparent) -----
+
+export interface RequestLocation {
+  collectionId: string;
+  folderPath: string[];
+  requestId: string;
+}
+
+export interface FolderLocation {
+  collectionId: string;
+  folderPath: string[];
+}
+
+/** Request ids already taken in a node (incl. a legacy requests/ dir at root). */
+function takenRequestIds(dir: string, isRoot: boolean): Set<string> {
+  const taken = new Set(requestIdsIn(dir));
+  if (isRoot) {
+    const legacy = path.join(dir, LEGACY_REQUESTS_DIR);
+    if (!fs.existsSync(path.join(legacy, FOLDER_FILE))) {
+      for (const id of requestIdsIn(legacy)) taken.add(id);
+    }
+  }
+  return taken;
+}
+
+/**
+ * Moves a request (its .json and any .md sibling) into another node, possibly
+ * in another collection. The slug is kept unless it collides at the
+ * destination, in which case it is uniquified. Returns the new location.
+ */
+export function moveRequest(
+  ws: WorkspaceMeta,
+  from: RequestLocation,
+  to: FolderLocation
+): RequestLocation {
+  const srcDir = requestFileDir(ws, from.collectionId, from.folderPath, from.requestId);
+  const srcJson = path.join(srcDir, `${from.requestId}.json`);
+  if (!fs.existsSync(srcJson)) {
+    throw new HttpError(404, `Request "${from.requestId}" not found`);
+  }
+  const destDir = nodeDir(ws, to.collectionId, to.folderPath);
+  if (path.resolve(srcDir) === path.resolve(destDir)) {
+    return { ...to, requestId: from.requestId };
+  }
+  const newId = uniqueSlug(
+    from.requestId,
+    takenRequestIds(destDir, to.folderPath.length === 0)
+  );
+  fs.renameSync(srcJson, path.join(destDir, `${newId}.json`));
+  const srcMd = path.join(srcDir, `${from.requestId}.md`);
+  if (fs.existsSync(srcMd)) {
+    fs.renameSync(srcMd, path.join(destDir, `${newId}.md`));
+  }
+  return { ...to, requestId: newId };
+}
+
+/**
+ * Moves a folder (with everything inside it) under a new parent, possibly in
+ * another collection. Rejects moving a folder into itself or a descendant.
+ * Returns the new folder path.
+ */
+export function moveFolder(
+  ws: WorkspaceMeta,
+  from: FolderLocation,
+  to: FolderLocation
+): FolderLocation {
+  if (from.folderPath.length === 0) {
+    throw new HttpError(400, 'No folder to move');
+  }
+  const srcDir = nodeDir(ws, from.collectionId, from.folderPath);
+  const parentPath = from.folderPath.slice(0, -1);
+
+  if (from.collectionId === to.collectionId) {
+    // Into the same parent — nothing to do.
+    if (parentPath.join('/') === to.folderPath.join('/')) return from;
+    // Into itself or one of its own descendants — not allowed.
+    const fromKey = from.folderPath.join('/');
+    const destKey = to.folderPath.slice(0, from.folderPath.length).join('/');
+    if (
+      to.folderPath.length >= from.folderPath.length &&
+      destKey === fromKey
+    ) {
+      throw new HttpError(400, 'Cannot move a folder into itself or its own subfolder');
+    }
+  }
+
+  const destParent = nodeDir(ws, to.collectionId, to.folderPath);
+  const slug = from.folderPath[from.folderPath.length - 1];
+  const newSlug = uniqueSlug(slug, new Set(subfolderSlugsIn(destParent)));
+  fs.renameSync(srcDir, path.join(destParent, newSlug));
+  return { collectionId: to.collectionId, folderPath: [...to.folderPath, newSlug] };
+}
+
 export function createEnvironment(ws: WorkspaceMeta, name: string): Environment {
   const dir = environmentsDir(ws);
   const taken = new Set(

From 663ec8e4c908d25ea04a1a22d6e8748dc164681e Mon Sep 17 00:00:00 2001
From: Tapiwa Muzira <tapsmuzira@gmail.com>
Date: Wed, 17 Jun 2026 15:19:14 +0200
Subject: [PATCH 3/8] Add batch Postman import from a folder (recursive scan,
 import-file/folder menu, endpoint, MCP tool, tests).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 CHANGELOG.md                          |   4 +
 client/src/App.tsx                    |  33 +++-
 client/src/api.ts                     |  17 ++
 client/src/components/Sidebar.tsx     |  46 +++++-
 server/src/importer.ts                | 226 ++++++++++++++++++--------
 server/src/mcp.ts                     |  13 +-
 server/src/router.integration.test.ts |  72 ++++++++
 server/src/router.ts                  |  10 +-
 8 files changed, 346 insertions(+), 75 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 11ad0c3..d6a918f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,10 @@ See [RELEASING.md](RELEASING.md) for the release process.
   workspaces still load (their requests appear at the collection root).
 - **Drag-and-drop** to move requests and folders between folders and
   collections in the sidebar (moving a folder takes its contents along).
+- **Batch import**: the sidebar import button now offers *Import file…* or
+  *Import folder…* — the latter recursively imports every Postman
+  collection/environment export found in a chosen folder (skipping anything
+  that isn't a recognised export).
 - Documentation now has **edit** and **preview** modes (request docs and
   collection descriptions). Existing docs open in a read-only rendered preview
   with an **Edit** button; empty docs open straight in the editor; a **Done**
diff --git a/client/src/App.tsx b/client/src/App.tsx
index a407ec8..f1c6083 100644
--- a/client/src/App.tsx
+++ b/client/src/App.tsx
@@ -461,6 +461,36 @@ export default function App() {
     }
   }
 
+  async function importPostmanFolder() {
+    if (!workspaceId) return;
+    try {
+      const picked = await api.pickFolder(
+        'Choose a folder of Postman exports to import'
+      );
+      if (!picked.path) return;
+      const r = await api.importPostmanDir(workspaceId, picked.path);
+      await loadTree(workspaceId, true);
+      if (r.collections === 0 && r.environments === 0) {
+        setToast(
+          r.files === 0
+            ? 'No JSON files found in that folder.'
+            : `No Postman exports found (skipped ${r.skipped} file${r.skipped === 1 ? '' : 's'}).`
+        );
+        return;
+      }
+      const parts: string[] = [];
+      if (r.collections)
+        parts.push(`${r.collections} collection${r.collections === 1 ? '' : 's'} (${r.requests} request${r.requests === 1 ? '' : 's'})`);
+      if (r.environments)
+        parts.push(`${r.environments} environment${r.environments === 1 ? '' : 's'}`);
+      setToast(
+        `Imported ${parts.join(' and ')}${r.skipped ? `; skipped ${r.skipped}` : ''}.`
+      );
+    } catch (err) {
+      showError(err);
+    }
+  }
+
   async function copyRequestInto(
     collectionId: string,
     folderPath: string[],
@@ -809,7 +839,8 @@ export default function App() {
                 onSelect={selectGuarded}
                 onNewCollection={promptNewCollection}
                 onNewEnvironment={promptNewEnvironment}
-                onImportPostman={importPostman}
+                onImportFile={importPostman}
+                onImportFolder={importPostmanFolder}
               />
               <div
                 className="sidebar-resizer"
diff --git a/client/src/api.ts b/client/src/api.ts
index f0bc147..6d8a7e5 100644
--- a/client/src/api.ts
+++ b/client/src/api.ts
@@ -197,6 +197,12 @@ export const api = {
       json({ path })
     ),
 
+  importPostmanDir: (id: string, path: string) =>
+    http<BatchImportResult>(
+      `/api/workspaces/${id}/import/postman-dir`,
+      json({ path })
+    ),
+
   execute: (
     id: string,
     request: ApiRequest,
@@ -233,3 +239,14 @@ export interface StoredCookie {
 export type PostmanImportResult =
   | { kind: 'collection'; collections: number; folders: number; requests: number }
   | { kind: 'environment'; name: string; variables: number };
+
+export interface BatchImportResult {
+  kind: 'batch';
+  files: number;
+  collections: number;
+  folders: number;
+  requests: number;
+  environments: number;
+  variables: number;
+  skipped: number;
+}
diff --git a/client/src/components/Sidebar.tsx b/client/src/components/Sidebar.tsx
index 0c60b22..08a7041 100644
--- a/client/src/components/Sidebar.tsx
+++ b/client/src/components/Sidebar.tsx
@@ -37,7 +37,8 @@ interface Props {
   onSelect: (selection: Selection) => void;
   onNewCollection: () => void;
   onNewEnvironment: () => void;
-  onImportPostman: () => void;
+  onImportFile: () => void;
+  onImportFolder: () => void;
 }
 
 type DragItem =
@@ -79,10 +80,12 @@ export function Sidebar({
   onSelect,
   onNewCollection,
   onNewEnvironment,
-  onImportPostman,
+  onImportFile,
+  onImportFolder,
 }: Props) {
   const [collapsed, setCollapsed] = useState<Record<string, boolean>>({});
   const [menu, setMenu] = useState<MenuState | null>(null);
+  const [importMenu, setImportMenu] = useState<{ x: number; y: number } | null>(null);
   const [drag, setDrag] = useState<DragItem | null>(null);
   const [dropKey, setDropKey] = useState<string | null>(null);
 
@@ -355,8 +358,11 @@ export function Sidebar({
           <span className="sidebar-heading-actions">
             <button
               className="icon-btn"
-              title="Import a Postman collection or environment export"
-              onClick={onImportPostman}
+              title="Import Postman exports"
+              onClick={(e) => {
+                const rect = e.currentTarget.getBoundingClientRect();
+                setImportMenu({ x: rect.right, y: rect.bottom + 2 });
+              }}
             >
               ⤓
             </button>
@@ -441,6 +447,38 @@ export function Sidebar({
           </div>
         </>
       )}
+
+      {importMenu && (
+        <>
+          <div className="ctx-backdrop" onMouseDown={() => setImportMenu(null)} />
+          <div
+            className="ctx-menu"
+            style={{
+              top: importMenu.y,
+              left: Math.min(importMenu.x, window.innerWidth - 190),
+            }}
+          >
+            <button
+              className="ctx-item"
+              onClick={() => {
+                setImportMenu(null);
+                onImportFile();
+              }}
+            >
+              Import file…
+            </button>
+            <button
+              className="ctx-item"
+              onClick={() => {
+                setImportMenu(null);
+                onImportFolder();
+              }}
+            >
+              Import folder…
+            </button>
+          </div>
+        </>
+      )}
     </aside>
   );
 }
diff --git a/server/src/importer.ts b/server/src/importer.ts
index ef2f86e..a12f59e 100644
--- a/server/src/importer.ts
+++ b/server/src/importer.ts
@@ -15,6 +15,93 @@ export type PostmanImportSummary =
   | { kind: 'collection'; collections: number; folders: number; requests: number }
   | { kind: 'environment'; name: string; variables: number };
 
+export interface BatchImportSummary {
+  kind: 'batch';
+  /** JSON files found and considered. */
+  files: number;
+  collections: number;
+  folders: number;
+  requests: number;
+  environments: number;
+  variables: number;
+  /** Files that were not a recognised export (or failed to parse). */
+  skipped: number;
+}
+
+interface CollectionCounts {
+  collections: number;
+  folders: number;
+  requests: number;
+}
+
+/** Imports an already-parsed Postman collection into the workspace. */
+function importCollection(ws: WorkspaceMeta, json: unknown): CollectionCounts {
+  const converted = convertCollection(json as never);
+  const collection = wsfs.createCollection(ws, converted.name);
+  if (converted.description || hasScripts(converted.scripts)) {
+    wsfs.updateCollection(ws, collection.id, {
+      description: converted.description || undefined,
+      scripts: hasScripts(converted.scripts) ? converted.scripts : undefined,
+    });
+  }
+
+  const counts = { collections: 1, folders: 0, requests: 0 };
+
+  const writeRequests = (
+    folderPath: string[],
+    requests: ReturnType<typeof convertCollection>['requests']
+  ) => {
+    for (const request of requests) {
+      const created = wsfs.createRequest(
+        ws,
+        collection.id,
+        folderPath,
+        request.name,
+        request.type
+      );
+      wsfs.updateRequest(ws, collection.id, folderPath, created.id, {
+        ...request,
+        id: created.id,
+      });
+      counts.requests += 1;
+    }
+  };
+
+  const writeFolders = (parentPath: string[], folders: ConvertedFolder[]) => {
+    for (const folder of folders) {
+      const created = wsfs.createFolder(ws, collection.id, parentPath, folder.name);
+      counts.folders += 1;
+      const folderPath = [...parentPath, created.id];
+      const scripts: Scripts | undefined = hasScripts(folder.scripts)
+        ? folder.scripts
+        : undefined;
+      if (folder.description || scripts) {
+        wsfs.updateFolder(ws, collection.id, folderPath, {
+          description: folder.description || undefined,
+          scripts,
+        });
+      }
+      writeRequests(folderPath, folder.requests);
+      writeFolders(folderPath, folder.folders);
+    }
+  };
+
+  writeRequests([], converted.requests);
+  writeFolders([], converted.folders);
+  return counts;
+}
+
+/** Imports an already-parsed Postman environment into the workspace. */
+function importEnvironment(
+  ws: WorkspaceMeta,
+  json: unknown
+): { name: string; variables: number } {
+  const { name, variables } = convertEnvironment(json as never);
+  const env = wsfs.createEnvironment(ws, name);
+  wsfs.updateEnvironment(ws, env.id, { name, variables });
+  return { name, variables: variables.length };
+}
+
 /**
  * Reads a Postman collection/environment export from disk and imports it into
  * the workspace. Shared by the REST endpoint and the MCP server.
@@ -33,76 +120,12 @@ export function importPostmanFile(
 
   const kind = detectPostmanKind(json);
   if (kind === 'collection') {
-    const converted = convertCollection(json as never);
-    const collection = wsfs.createCollection(ws, converted.name);
-    if (converted.description || hasScripts(converted.scripts)) {
-      wsfs.updateCollection(ws, collection.id, {
-        description: converted.description || undefined,
-        scripts: hasScripts(converted.scripts) ? converted.scripts : undefined,
-      });
-    }
-
-    const counts = { folders: 0, requests: 0 };
-
-    const writeRequests = (
-      folderPath: string[],
-      requests: ReturnType<typeof convertCollection>['requests']
-    ) => {
-      for (const request of requests) {
-        const created = wsfs.createRequest(
-          ws,
-          collection.id,
-          folderPath,
-          request.name,
-          request.type
-        );
-        wsfs.updateRequest(ws, collection.id, folderPath, created.id, {
-          ...request,
-          id: created.id,
-        });
-        counts.requests += 1;
-      }
-    };
-
-    const writeFolders = (parentPath: string[], folders: ConvertedFolder[]) => {
-      for (const folder of folders) {
-        const created = wsfs.createFolder(
-          ws,
-          collection.id,
-          parentPath,
-          folder.name
-        );
-        counts.folders += 1;
-        const folderPath = [...parentPath, created.id];
-        const scripts: Scripts | undefined = hasScripts(folder.scripts)
-          ? folder.scripts
-          : undefined;
-        if (folder.description || scripts) {
-          wsfs.updateFolder(ws, collection.id, folderPath, {
-            description: folder.description || undefined,
-            scripts,
-          });
-        }
-        writeRequests(folderPath, folder.requests);
-        writeFolders(folderPath, folder.folders);
-      }
-    };
-
-    writeRequests([], converted.requests);
-    writeFolders([], converted.folders);
-    return {
-      kind,
-      collections: 1,
-      folders: counts.folders,
-      requests: counts.requests,
-    };
+    const { collections, folders, requests } = importCollection(ws, json);
+    return { kind, collections, folders, requests };
   }
-
   if (kind === 'environment') {
-    const { name, variables } = convertEnvironment(json as never);
-    const env = wsfs.createEnvironment(ws, name);
-    wsfs.updateEnvironment(ws, env.id, { name, variables });
-    return { kind, name, variables: variables.length };
+    const { name, variables } = importEnvironment(ws, json);
+    return { kind, name, variables };
   }
 
   throw new HttpError(
@@ -110,3 +133,70 @@ export function importPostmanFile(
     'This file is not a recognised Postman collection or environment export'
   );
 }
+
+/** Recursively lists every .json file under a directory, sorted for stability. */
+function findJsonFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...findJsonFiles(full));
+    else if (entry.isFile() && entry.name.toLowerCase().endsWith('.json')) {
+      out.push(full);
+    }
+  }
+  return out.sort();
+}
+
+/**
+ * Imports every Postman collection/environment export found under a directory
+ * (recursively). Files that are not recognised exports — or fail to parse — are
+ * skipped rather than aborting the batch. Returns aggregate counts.
+ */
+export function importPostmanDir(
+  ws: WorkspaceMeta,
+  dirPath: string
+): BatchImportSummary {
+  const resolved = path.resolve(expandHome(dirPath));
+  let files: string[];
+  try {
+    files = findJsonFiles(resolved);
+  } catch {
+    throw new HttpError(400, `Could not read the folder "${dirPath}"`);
+  }
+
+  const summary: BatchImportSummary = {
+    kind: 'batch',
+    files: files.length,
+    collections: 0,
+    folders: 0,
+    requests: 0,
+    environments: 0,
+    variables: 0,
+    skipped: 0,
+  };
+
+  for (const file of files) {
+    let json: unknown;
+    try {
+      json = JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch {
+      summary.skipped += 1;
+      continue;
+    }
+    const kind = detectPostmanKind(json);
+    if (kind === 'collection') {
+      const counts = importCollection(ws, json);
+      summary.collections += counts.collections;
+      summary.folders += counts.folders;
+      summary.requests += counts.requests;
+    } else if (kind === 'environment') {
+      const { variables } = importEnvironment(ws, json);
+      summary.environments += 1;
+      summary.variables += variables;
+    } else {
+      summary.skipped += 1;
+    }
+  }
+
+  return summary;
+}
diff --git a/server/src/mcp.ts b/server/src/mcp.ts
index 7e952f8..4fd28f8 100644
--- a/server/src/mcp.ts
+++ b/server/src/mcp.ts
@@ -5,7 +5,7 @@ import { z } from 'zod';
 import * as appData from './appData.js';
 import * as cookies from './cookies.js';
 import { applyEnvChanges, runRequest } from './execute.js';
-import { importPostmanFile } from './importer.js';
+import { importPostmanDir, importPostmanFile } from './importer.js';
 import type { ApiRequest, WorkspaceMeta } from './types.js';
 import * as wsfs from './workspaceFs.js';
 
@@ -571,6 +571,17 @@ function buildServer(): McpServer {
       importPostmanFile(resolveWorkspace(workspaceId), path)
   );
 
+  reg(
+    'import_postman_dir',
+    {
+      description:
+        'Batch-import every Postman collection/environment export found under a folder on this machine (recursively). Unrecognised or unparseable JSON files are skipped. Returns aggregate counts.',
+      inputSchema: { workspaceId: z.string(), path: z.string() },
+    },
+    ({ workspaceId, path }: Args) =>
+      importPostmanDir(resolveWorkspace(workspaceId), path)
+  );
+
   // ---- destructive ----
 
   reg(
diff --git a/server/src/router.integration.test.ts b/server/src/router.integration.test.ts
index 220f896..d475a54 100644
--- a/server/src/router.integration.test.ts
+++ b/server/src/router.integration.test.ts
@@ -282,3 +282,75 @@ describe('folder endpoints', () => {
     expect(imported.requests.map((r: { name: string }) => r.name)).toEqual(['Root']);
   });
 });
+
+describe('batch import (folder)', () => {
+  const SCHEMA =
+    'https://schema.getpostman.com/json/collection/v2.1.0/collection.json';
+  let wsId: string;
+  let importDir: string;
+
+  beforeAll(async () => {
+    const wd = fs.mkdtempSync(path.join(os.tmpdir(), 'apinb-batchws-'));
+    const ws = await request(app)
+      .post('/api/workspaces')
+      .send({ name: 'Batch WS', path: wd })
+      .expect(201);
+    wsId = ws.body.id;
+
+    importDir = fs.mkdtempSync(path.join(os.tmpdir(), 'apinb-batch-'));
+    fs.writeFileSync(
+      path.join(importDir, 'col1.json'),
+      JSON.stringify({
+        info: { name: 'One', schema: SCHEMA },
+        item: [{ name: 'A', request: { method: 'GET', url: { raw: 'http://x/a' } } }],
+      })
+    );
+    fs.writeFileSync(
+      path.join(importDir, 'env.json'),
+      JSON.stringify({
+        name: 'dev',
+        _postman_variable_scope: 'environment',
+        values: [{ key: 'base', value: 'http://x', enabled: true }],
+      })
+    );
+    // Not a Postman export — should be skipped.
+    fs.writeFileSync(path.join(importDir, 'notes.json'), JSON.stringify({ hello: 'world' }));
+    // A non-JSON file — should be ignored entirely.
+    fs.writeFileSync(path.join(importDir, 'README.md'), '# ignore me');
+    // A nested export — recursion should pick it up.
+    const sub = path.join(importDir, 'nested');
+    fs.mkdirSync(sub);
+    fs.writeFileSync(
+      path.join(sub, 'col2.json'),
+      JSON.stringify({
+        info: { name: 'Two', schema: SCHEMA },
+        item: [{ name: 'B', request: { method: 'GET', url: { raw: 'http://x/b' } } }],
+      })
+    );
+  });
+
+  afterAll(() => fs.rmSync(importDir, { recursive: true, force: true }));
+
+  it('imports every recognised export recursively and reports counts', async () => {
+    const res = await request(app)
+      .post(`/api/workspaces/${wsId}/import/postman-dir`)
+      .send({ path: importDir })
+      .expect(200);
+    expect(res.body).toMatchObject({
+      kind: 'batch',
+      files: 4, // col1, env, notes, nested/col2 (README.md is not .json)
+      collections: 2,
+      requests: 2,
+      environments: 1,
+      variables: 1,
+      skipped: 1, // notes.json
+    });
+
+    const tree = await request(app).get(`/api/workspaces/${wsId}`).expect(200);
+    expect(tree.body.collections.map((c: { name: string }) => c.name).sort()).toEqual([
+      'One',
+      'Two',
+    ]);
+    expect(tree.body.environments.map((e: { name: string }) => e.name)).toContain('dev');
+  });
+});
diff --git a/server/src/router.ts b/server/src/router.ts
index 639bfc4..dc2d43f 100644
--- a/server/src/router.ts
+++ b/server/src/router.ts
@@ -3,7 +3,7 @@ import * as appData from './appData.js';
 import * as cookies from './cookies.js';
 import { applyEnvChanges, runRequest } from './execute.js';
 import { pickFile, pickFolder } from './pickFolder.js';
-import { importPostmanFile } from './importer.js';
+import { importPostmanDir, importPostmanFile } from './importer.js';
 import * as wsfs from './workspaceFs.js';
 import { HttpError } from './workspaceFs.js';
 import type { ApiRequest, WorkspaceMeta } from './types.js';
@@ -305,6 +305,14 @@ router.post(
   })
 );
 
+router.post(
+  '/workspaces/:id/import/postman-dir',
+  wrap((req, res) => {
+    const ws = getWorkspace(req.params.id);
+    res.json(importPostmanDir(ws, requireString(req.body.path, 'path')));
+  })
+);
+
 router.post(
   '/workspaces/:id/execute',
   wrap(async (req, res) => {

From 441f0b5c5819316b8ff241b9344d730e1316d46d Mon Sep 17 00:00:00 2001
From: Tapiwa Muzira <tapsmuzira@gmail.com>
Date: Wed, 17 Jun 2026 15:33:15 +0200
Subject: [PATCH 4/8] Persist the last 3 responses per request (gitignored
 local cache, history endpoint/switcher, MCP, tests).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 CHANGELOG.md                            |  4 ++
 client/src/api.ts                       |  5 ++
 client/src/components/RequestEditor.tsx | 36 ++++++++++-
 client/src/components/ResponsePanel.tsx | 36 ++++++++++-
 client/src/types.ts                     |  2 +
 server/src/mcp.ts                       |  1 +
 server/src/router.integration.test.ts   | 10 +++
 server/src/router.ts                    | 20 ++++++
 server/src/types.ts                     |  2 +
 server/src/workspaceFs.test.ts          | 66 ++++++++++++++++++-
 server/src/workspaceFs.ts               | 86 +++++++++++++++++++++----
 11 files changed, 250 insertions(+), 18 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d6a918f..ee83829 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,10 @@ See [RELEASING.md](RELEASING.md) for the release process.
   *Import folder…* — the latter recursively imports every Postman
   collection/environment export found in a chosen folder (skipping anything
   that isn't a recognised export).
+- **Saved responses**: each request now keeps its last 3 responses, so reopening
+  a request shows its recent results (with a switcher to step back through them).
+  Responses are a local cache stored beside each request and are gitignored
+  (they can contain tokens/PII), like secret environment values.
 - Documentation now has **edit** and **preview** modes (request docs and
   collection descriptions). Existing docs open in a read-only rendered preview
   with an **Edit** button; empty docs open straight in the editor; a **Done**
diff --git a/client/src/api.ts b/client/src/api.ts
index 6d8a7e5..1458ad5 100644
--- a/client/src/api.ts
+++ b/client/src/api.ts
@@ -214,6 +214,11 @@ export const api = {
       json({ request, collectionId, folderPath: folderPath.join('/') })
     ),
 
+  getResponses: (id: string, cid: string, folderPath: string[], rid: string) =>
+    http<ExecutionResult[]>(
+      `/api/workspaces/${id}/collections/${cid}/requests/${rid}/responses${fpQuery(folderPath)}`
+    ),
+
   listCookies: (id: string) =>
     http<StoredCookie[]>(`/api/workspaces/${id}/cookies`),
 
diff --git a/client/src/components/RequestEditor.tsx b/client/src/components/RequestEditor.tsx
index bf134b5..b3950d9 100644
--- a/client/src/components/RequestEditor.tsx
+++ b/client/src/components/RequestEditor.tsx
@@ -71,7 +71,8 @@ export function RequestEditor({
   const [saved, setSaved] = useState(request);
   const [draft, setDraft] = useState(request);
   const [tab, setTab] = useState<Tab>('params');
-  const [response, setResponse] = useState<ExecutionResult | null>(null);
+  const [history, setHistory] = useState<ExecutionResult[]>([]);
+  const [viewIndex, setViewIndex] = useState(0);
   const [execError, setExecError] = useState<string | null>(null);
   const [executing, setExecuting] = useState(false);
   const [saveError, setSaveError] = useState<string | null>(null);
@@ -83,6 +84,26 @@ export function RequestEditor({
   const dirty =
     JSON.stringify(canonical(draft)) !== JSON.stringify(canonical(saved));
   const isGraphql = draft.type === 'graphql';
+  const response = history[viewIndex] ?? null;
+  const fpKey = folderPath.join('/');
+
+  // Load this request's persisted recent responses when it opens.
+  useEffect(() => {
+    let active = true;
+    api
+      .getResponses(workspaceId, collectionId, folderPath, request.id)
+      .then((h) => {
+        if (active) {
+          setHistory(h);
+          setViewIndex(0);
+        }
+      })
+      .catch(() => {});
+    return () => {
+      active = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [workspaceId, collectionId, fpKey, request.id]);
 
   useEffect(() => {
     onDirtyChange(dirty);
@@ -121,12 +142,15 @@ export function RequestEditor({
     setExecError(null);
     try {
       const result = await api.execute(workspaceId, draft, collectionId, folderPath);
-      setResponse(result);
+      // Mirror the server's persisted history: newest first, capped at 3.
+      setHistory((h) =>
+        [{ ...result, savedAt: new Date().toISOString() }, ...h].slice(0, 3)
+      );
+      setViewIndex(0);
       // Scripts may have persisted environment variables; refresh so the
       // sidebar, variable highlights and env editor reflect the new values.
       if (result.script?.variablesSet.length) onVariablesChanged();
     } catch (err) {
-      setResponse(null);
       setExecError(err instanceof Error ? err.message : String(err));
     } finally {
       setExecuting(false);
@@ -483,6 +507,12 @@ export function RequestEditor({
         response={response}
         error={execError}
         executing={executing}
+        history={history}
+        activeIndex={viewIndex}
+        onSelectHistory={(i) => {
+          setViewIndex(i);
+          setExecError(null);
+        }}
       />
     </div>
   );
diff --git a/client/src/components/ResponsePanel.tsx b/client/src/components/ResponsePanel.tsx
index e2eaed6..4fad656 100644
--- a/client/src/components/ResponsePanel.tsx
+++ b/client/src/components/ResponsePanel.tsx
@@ -7,6 +7,19 @@ interface Props {
   response: ExecutionResult | null;
   error: string | null;
   executing: boolean;
+  /** Recent responses (newest first); shows a switcher when more than one. */
+  history?: ExecutionResult[];
+  activeIndex?: number;
+  onSelectHistory?: (index: number) => void;
+}
+
+function historyLabel(entry: ExecutionResult, index: number): string {
+  if (index === 0) return 'Latest';
+  if (!entry.savedAt) return `#${index + 1}`;
+  return new Date(entry.savedAt).toLocaleTimeString([], {
+    hour: '2-digit',
+    minute: '2-digit',
+  });
 }
 
 // Beyond this, formatting/highlighting large bodies would jank the UI.
@@ -25,7 +38,14 @@ function formatSize(bytes: number): string {
   return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
 }
 
-export function ResponsePanel({ response, error, executing }: Props) {
+export function ResponsePanel({
+  response,
+  error,
+  executing,
+  history,
+  activeIndex = 0,
+  onSelectHistory,
+}: Props) {
   const [tab, setTab] = useState<'body' | 'headers' | 'script'>('body');
   const [view, setView] = useState<'pretty' | 'raw'>('pretty');
 
@@ -109,6 +129,20 @@ export function ResponsePanel({ response, error, executing }: Props) {
     <div className="response-panel">
       <div className="response-header">
         <span className="panel-title">Response</span>
+        {!executing && history && history.length > 1 && (
+          <div className="tab-group response-history" title="Recent responses">
+            {history.map((entry, i) => (
+              <button
+                key={i}
+                className={i === activeIndex ? 'tab active' : 'tab'}
+                title={entry.savedAt ? new Date(entry.savedAt).toLocaleString() : ''}
+                onClick={() => onSelectHistory?.(i)}
+              >
+                {historyLabel(entry, i)}
+              </button>
+            ))}
+          </div>
+        )}
         {executing && <span className="muted">Sending…</span>}
         {response && !executing && (
           <>
diff --git a/client/src/types.ts b/client/src/types.ts
index 956971b..8db2a00 100644
--- a/client/src/types.ts
+++ b/client/src/types.ts
@@ -148,4 +148,6 @@ export interface ExecutionResult {
   resolvedUrl: string;
   /** Present when pre-request or post-response scripts ran. */
   script?: ScriptOutcome;
+  /** ISO timestamp set when the response is saved to the request's history. */
+  savedAt?: string;
 }
diff --git a/server/src/mcp.ts b/server/src/mcp.ts
index 4fd28f8..6472758 100644
--- a/server/src/mcp.ts
+++ b/server/src/mcp.ts
@@ -471,6 +471,7 @@ function buildServer(): McpServer {
           variables: applyEnvChanges(env, outcome.envVars, outcome.changedEnvKeys),
         });
       }
+      wsfs.saveResponse(ws, collectionId, path, requestId, outcome.result);
       const r = outcome.result;
       const truncated = r.body.length > MAX_BODY_CHARS;
       return {
diff --git a/server/src/router.integration.test.ts b/server/src/router.integration.test.ts
index d475a54..57d32a2 100644
--- a/server/src/router.integration.test.ts
+++ b/server/src/router.integration.test.ts
@@ -128,6 +128,16 @@ describe('workspace/collection/request endpoints', () => {
     expect(res.body.status).toBe(200);
     expect(res.body.script.tests[0]).toMatchObject({ name: 'ok', passed: true });
   });
+
+  it('persists the response and serves it back from the history endpoint', async () => {
+    const before = await request(app)
+      .get(`/api/workspaces/${WID}/collections/${CID}/requests/${RID}/responses`)
+      .expect(200);
+    expect(Array.isArray(before.body)).toBe(true);
+    expect(before.body.length).toBeGreaterThan(0);
+    expect(before.body[0]).toMatchObject({ status: 200 });
+    expect(before.body[0].savedAt).toBeTruthy();
+  });
 });
 
 describe('folder endpoints', () => {
diff --git a/server/src/router.ts b/server/src/router.ts
index dc2d43f..68846b3 100644
--- a/server/src/router.ts
+++ b/server/src/router.ts
@@ -343,10 +343,30 @@ router.post(
       });
     }
 
+    // Keep the request's recent-response history (no-ops for unsaved requests).
+    if (collectionId && typeof request.id === 'string') {
+      wsfs.saveResponse(ws, collectionId, folderPath, request.id, outcome.result);
+    }
+
     res.json(outcome.result);
   })
 );
 
+router.get(
+  '/workspaces/:id/collections/:cid/requests/:rid/responses',
+  wrap((req, res) => {
+    const ws = getWorkspace(req.params.id);
+    res.json(
+      wsfs.getResponses(
+        ws,
+        req.params.cid,
+        parseFolderPath(req.query.folderPath),
+        req.params.rid
+      )
+    );
+  })
+);
+
 router.get(
   '/workspaces/:id/cookies',
   wrap((req, res) => {
diff --git a/server/src/types.ts b/server/src/types.ts
index 39fdb81..5c45ad7 100644
--- a/server/src/types.ts
+++ b/server/src/types.ts
@@ -138,4 +138,6 @@ export interface ExecutionResult {
   resolvedUrl: string;
   /** Present when pre-request or post-response scripts ran. */
   script?: ScriptOutcome;
+  /** ISO timestamp set when the response is saved to the request's history. */
+  savedAt?: string;
 }
diff --git a/server/src/workspaceFs.test.ts b/server/src/workspaceFs.test.ts
index 86fe19a..bb47fe7 100644
--- a/server/src/workspaceFs.test.ts
+++ b/server/src/workspaceFs.test.ts
@@ -3,7 +3,18 @@ import os from 'node:os';
 import path from 'node:path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import * as wsfs from './workspaceFs.js';
-import type { WorkspaceMeta } from './types.js';
+import type { ExecutionResult, WorkspaceMeta } from './types.js';
+
+const mkResult = (status: number): ExecutionResult => ({
+  status,
+  statusText: 'OK',
+  headers: {},
+  body: `{"n":${status}}`,
+  bodyEncoding: 'text',
+  timeMs: 1,
+  sizeBytes: 8,
+  resolvedUrl: 'http://x/',
+});
 
 let dir: string;
 let ws: WorkspaceMeta;
@@ -214,6 +225,59 @@ describe('move (reparent)', () => {
   });
 });
 
+describe('response history', () => {
+  it('keeps only the last 3 responses, newest first, with a savedAt', () => {
+    const col = wsfs.createCollection(ws, 'R');
+    const req = wsfs.createRequest(ws, col.id, [], 'Ping', 'http');
+    for (const code of [200, 201, 202, 500]) {
+      wsfs.saveResponse(ws, col.id, [], req.id, mkResult(code));
+    }
+    const history = wsfs.getResponses(ws, col.id, [], req.id);
+    expect(history.map((r) => r.status)).toEqual([500, 202, 201]);
+    expect(history[0].savedAt).toBeTruthy();
+  });
+
+  it('does not surface the response file as a request, and gitignores it', () => {
+    const col = wsfs.createCollection(ws, 'R2');
+    const req = wsfs.createRequest(ws, col.id, [], 'Once', 'http');
+    wsfs.saveResponse(ws, col.id, [], req.id, mkResult(200));
+
+    const collection = wsfs
+      .readTree(ws, null)
+      .collections.find((c) => c.id === col.id)!;
+    expect(collection.requests.map((r) => r.id)).toEqual([req.id]);
+
+    const gitignore = fs.readFileSync(path.join(dir, '.gitignore'), 'utf8');
+    expect(gitignore).toContain('*.response.json');
+  });
+
+  it('drops the history when the request is deleted and moves it on reparent', () => {
+    const col = wsfs.createCollection(ws, 'R3');
+    const folder = wsfs.createFolder(ws, col.id, [], 'F');
+    const req = wsfs.createRequest(ws, col.id, [], 'Move', 'http');
+    wsfs.saveResponse(ws, col.id, [], req.id, mkResult(200));
+
+    const moved = wsfs.moveRequest(
+      ws,
+      { collectionId: col.id, folderPath: [], requestId: req.id },
+      { collectionId: col.id, folderPath: [folder.id] }
+    );
+    expect(wsfs.getResponses(ws, col.id, [], req.id)).toEqual([]);
+    expect(
+      wsfs.getResponses(ws, col.id, [folder.id], moved.requestId).map((r) => r.status)
+    ).toEqual([200]);
+
+    wsfs.deleteRequest(ws, col.id, [folder.id], moved.requestId);
+    expect(wsfs.getResponses(ws, col.id, [folder.id], moved.requestId)).toEqual([]);
+  });
+
+  it('no-ops saving a response for a request that does not exist', () => {
+    const col = wsfs.createCollection(ws, 'R4');
+    wsfs.saveResponse(ws, col.id, [], 'ghost', mkResult(200));
+    expect(wsfs.getResponses(ws, col.id, [], 'ghost')).toEqual([]);
+  });
+});
+
 describe('environment secret split', () => {
   it('keeps secret values out of the shared file and merges them back on read', () => {
     const env = wsfs.createEnvironment(ws, 'dev');
diff --git a/server/src/workspaceFs.ts b/server/src/workspaceFs.ts
index ec4a074..3d40b3a 100644
--- a/server/src/workspaceFs.ts
+++ b/server/src/workspaceFs.ts
@@ -6,6 +6,7 @@ import type {
   ApiRequest,
   Collection,
   Environment,
+  ExecutionResult,
   Folder,
   RequestType,
   Scripts,
@@ -21,8 +22,14 @@ const COLLECTION_FILE = 'collection.json';
  * subdirectory. We still read that layout, but never write to it.
  */
 const LEGACY_REQUESTS_DIR = 'requests';
+/** Suffix for the persisted response-history file kept beside each request. */
+const RESPONSE_SUFFIX = '.response.json';
+/** How many recent responses to keep per request (newest first). */
+const RESPONSE_HISTORY = 3;
 const emptyScripts = (): Scripts => ({ preRequest: '', postResponse: '' });
 const LOCAL_ENV_IGNORE = 'environments/*.local.json';
+/** Saved responses are a local cache (may hold tokens/PII) — never committed. */
+const RESPONSE_IGNORE = '*.response.json';
 
 export class HttpError extends Error {
   constructor(
@@ -121,7 +128,12 @@ function listDirs(dir: string): string[] {
 /** Names (without .json) of request files directly inside a node directory. */
 function requestIdsIn(dir: string): string[] {
   return listJsonFiles(dir)
-    .filter((f) => f !== COLLECTION_FILE && f !== FOLDER_FILE)
+    .filter(
+      (f) =>
+        f !== COLLECTION_FILE &&
+        f !== FOLDER_FILE &&
+        !f.endsWith(RESPONSE_SUFFIX)
+    )
     .map((f) => f.replace(/\.json$/, ''));
 }
 
@@ -179,6 +191,9 @@ export function createWorkspace(name: string, dirPath: string): WorkspaceMeta {
         '# declare secret variable names; the values live here and stay local.',
         LOCAL_ENV_IGNORE,
         '',
+        '# Saved responses are a local cache (may hold tokens/PII).',
+        RESPONSE_IGNORE,
+        '',
         '# OS cruft',
         '.DS_Store',
         'Thumbs.db',
@@ -548,6 +563,50 @@ export function deleteRequest(
   const dir = requestFileDir(ws, collectionId, folderPath, id);
   fs.rmSync(path.join(dir, `${id}.json`), { force: true });
   fs.rmSync(path.join(dir, `${id}.md`), { force: true });
+  fs.rmSync(path.join(dir, `${id}${RESPONSE_SUFFIX}`), { force: true });
+}
+
+// ----- persisted response history -----
+
+/**
+ * Saves a response into the request's history (newest first, capped at
+ * RESPONSE_HISTORY). The history is a local cache beside the request file and
+ * is never committed (see RESPONSE_IGNORE). No-ops if the request file is gone.
+ */
+export function saveResponse(
+  ws: WorkspaceMeta,
+  collectionId: string,
+  folderPath: string[],
+  id: string,
+  result: ExecutionResult
+): void {
+  const dir = requestFileDir(ws, collectionId, folderPath, id);
+  if (!fs.existsSync(path.join(dir, `${id}.json`))) return;
+  const file = path.join(dir, `${id}${RESPONSE_SUFFIX}`);
+  const entry: ExecutionResult = { ...result, savedAt: new Date().toISOString() };
+  const history = [entry, ...readResponseHistory(file)].slice(0, RESPONSE_HISTORY);
+  writeJson(file, history);
+  ensureIgnored(ws, RESPONSE_IGNORE, 'Saved responses stay local');
+}
+
+function readResponseHistory(file: string): ExecutionResult[] {
+  if (!fs.existsSync(file)) return [];
+  try {
+    const data = readJson<unknown>(file);
+    return Array.isArray(data) ? (data as ExecutionResult[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+export function getResponses(
+  ws: WorkspaceMeta,
+  collectionId: string,
+  folderPath: string[],
+  id: string
+): ExecutionResult[] {
+  const dir = requestFileDir(ws, collectionId, folderPath, id);
+  return readResponseHistory(path.join(dir, `${id}${RESPONSE_SUFFIX}`));
 }
 
 // ----- move (reparent) -----
@@ -603,6 +662,10 @@ export function moveRequest(
   if (fs.existsSync(srcMd)) {
     fs.renameSync(srcMd, path.join(destDir, `${newId}.md`));
   }
+  const srcResp = path.join(srcDir, `${from.requestId}${RESPONSE_SUFFIX}`);
+  if (fs.existsSync(srcResp)) {
+    fs.renameSync(srcResp, path.join(destDir, `${newId}${RESPONSE_SUFFIX}`));
+  }
   return { ...to, requestId: newId };
 }
 
@@ -663,21 +726,18 @@ export function getEnvironment(
 }
 
 /**
- * Make sure the workspace's .gitignore excludes <env>.local.json files,
- * so secret values can never be committed by accident. Appends the rule
- * to workspaces created before this feature existed.
+ * Make sure the workspace's .gitignore contains a pattern, appending it (with a
+ * comment) when missing. Used to keep local-only artifacts — secret env values
+ * and saved responses — out of Git even in workspaces created before the
+ * feature existed.
  */
-function ensureLocalEnvIgnored(ws: WorkspaceMeta): void {
+function ensureIgnored(ws: WorkspaceMeta, pattern: string, comment: string): void {
   const file = path.join(ws.path, '.gitignore');
   const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
   const lines = existing.split('\n').map((l) => l.trim());
-  if (lines.includes(LOCAL_ENV_IGNORE) || lines.includes(`/${LOCAL_ENV_IGNORE}`)) {
-    return;
-  }
-  const block = `# Secret environment values stay local\n${LOCAL_ENV_IGNORE}\n`;
-  const content = existing
-    ? existing.replace(/\n*$/, '\n\n') + block
-    : block;
+  if (lines.includes(pattern) || lines.includes(`/${pattern}`)) return;
+  const block = `# ${comment}\n${pattern}\n`;
+  const content = existing ? existing.replace(/\n*$/, '\n\n') + block : block;
   fs.writeFileSync(file, content);
 }
 
@@ -701,7 +761,7 @@ export function updateEnvironment(
     writeJson(localEnvFile(ws, id), {
       values: Object.fromEntries(secrets.map((v) => [v.key, v.value])),
     });
-    ensureLocalEnvIgnored(ws);
+    ensureIgnored(ws, LOCAL_ENV_IGNORE, 'Secret environment values stay local');
   } else {
     fs.rmSync(localEnvFile(ws, id), { force: true });
   }

From 1132a285446060da3b830807298bd1dd6ffbfe3a Mon Sep 17 00:00:00 2001
From: Tapiwa Muzira <tapsmuzira@gmail.com>
Date: Wed, 17 Jun 2026 15:41:37 +0200
Subject: [PATCH 5/8] Only warn about unsaved changes on tab close, not when
 navigating between requests.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 CHANGELOG.md       |  6 ++++++
 client/src/App.tsx | 16 ++++------------
 2 files changed, 10 insertions(+), 12 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ee83829..d188e24 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -31,6 +31,12 @@ See [RELEASING.md](RELEASING.md) for the release process.
   with an **Edit** button; empty docs open straight in the editor; a **Done**
   button returns to preview.
 
+### Changed
+
+- Switching between requests/collections no longer prompts about unsaved
+  changes; unsaved edits are discarded silently on navigation. The
+  unsaved-changes warning now appears only when closing the browser tab.
+
 ## [1.0.0] - 2026-06-17
 
 First tagged release.
diff --git a/client/src/App.tsx b/client/src/App.tsx
index f1c6083..a985148 100644
--- a/client/src/App.tsx
+++ b/client/src/App.tsx
@@ -66,16 +66,9 @@ export default function App() {
     setEditorDirty(dirty);
   }, []);
 
-  /** True when it is OK to discard the current editor state. */
-  function confirmDiscard(): boolean {
-    return (
-      !editorDirtyRef.current ||
-      confirm('You have unsaved changes that will be lost. Continue?')
-    );
-  }
-
-  function selectGuarded(sel: Selection) {
-    if (!confirmDiscard()) return;
+  // Navigating between requests/collections discards unsaved edits silently —
+  // the only unsaved-changes warning is the browser tab-close prompt below.
+  function selectItem(sel: Selection) {
     handleDirtyChange(false);
     setSelection(sel);
   }
@@ -785,7 +778,6 @@ export default function App() {
         workspaces={workspaces}
         currentWorkspaceId={workspaceId}
         onSelectWorkspace={(id) => {
-          if (!confirmDiscard()) return;
           handleDirtyChange(false);
           void loadTree(id);
         }}
@@ -836,7 +828,7 @@ export default function App() {
                 }}
                 onMoveRequest={moveRequestAction}
                 onMoveFolder={moveFolderAction}
-                onSelect={selectGuarded}
+                onSelect={selectItem}
                 onNewCollection={promptNewCollection}
                 onNewEnvironment={promptNewEnvironment}
                 onImportFile={importPostman}

From 56e8524073057c43147c1e40d670b3d4d4b680b5 Mon Sep 17 00:00:00 2001
From: Tapiwa Muzira <tapsmuzira@gmail.com>
Date: Wed, 17 Jun 2026 19:33:23 +0200
Subject: [PATCH 6/8] Add WebSocket request protocol with shared
 live-connection channel (server session manager, ws driver, sidebar/editor
 UI, tests).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 CHANGELOG.md                                |   5 +
 client/src/App.tsx                          |  28 +-
 client/src/components/ConnectionEditor.tsx  | 305 ++++++++++++++++++++
 client/src/components/MessageLogPanel.tsx   | 132 +++++++++
 client/src/components/Sidebar.tsx           |  22 +-
 client/src/curl.ts                          |   4 +
 client/src/live.ts                          | 114 ++++++++
 client/src/styles.css                       |  74 +++++
 client/src/types.ts                         |  17 +-
 client/vite.config.ts                       |   2 +
 package-lock.json                           |  34 ++-
 server/package.json                         |   2 +
 server/src/index.ts                         |   9 +-
 server/src/live/driver.ts                   |  29 ++
 server/src/live/wsDriver.ts                 | 107 +++++++
 server/src/liveSessions.integration.test.ts | 128 ++++++++
 server/src/liveSessions.ts                  | 171 +++++++++++
 server/src/postmanImport.ts                 |   1 +
 server/src/router.ts                        |   3 +-
 server/src/types.ts                         |  17 +-
 server/src/workspaceFs.test.ts              |  18 ++
 server/src/workspaceFs.ts                   |   6 +-
 22 files changed, 1211 insertions(+), 17 deletions(-)
 create mode 100644 client/src/components/ConnectionEditor.tsx
 create mode 100644 client/src/components/MessageLogPanel.tsx
 create mode 100644 client/src/live.ts
 create mode 100644 server/src/live/driver.ts
 create mode 100644 server/src/live/wsDriver.ts
 create mode 100644 server/src/liveSessions.integration.test.ts
 create mode 100644 server/src/liveSessions.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d188e24..c8a5245 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,11 @@ See [RELEASING.md](RELEASING.md) for the release process.
 
 ### Added
 
+- **WebSocket requests**: a new request type that opens a live ws/wss connection
+  (routed through the server, so `{{variables}}`, headers, auth, and the cookie
+  jar apply), with a message log, a composer, and reusable saved messages.
+  Backed by a new multiplexed live channel (`/live`) shared by future streaming
+  protocols.
 - **Folders** inside collections, nestable to any depth (Postman-style).
   Folders carry their own description and pre-request/test scripts, which run in
   the execution chain (collection → folder(s) → request). Postman imports now
diff --git a/client/src/App.tsx b/client/src/App.tsx
index a985148..6ffd9e0 100644
--- a/client/src/App.tsx
+++ b/client/src/App.tsx
@@ -9,10 +9,12 @@ import { Sidebar } from './components/Sidebar';
 import { TopBar } from './components/TopBar';
 import { parseCurl } from './curl';
 import type { Selection } from './selection';
+import { ConnectionEditor } from './components/ConnectionEditor';
 import type {
   ApiRequest,
   Collection,
   Folder,
+  RequestType,
   WorkspaceMeta,
   WorkspaceTree,
 } from './types';
@@ -276,16 +278,21 @@ export default function App() {
           options: [
             { value: 'http', label: 'HTTP' },
             { value: 'graphql', label: 'GraphQL' },
+            { value: 'websocket', label: 'WebSocket' },
           ],
         },
       ],
       onSubmit: async (values) => {
+        const allowed: RequestType[] = ['http', 'graphql', 'websocket'];
+        const type = (allowed as string[]).includes(values.type)
+          ? (values.type as RequestType)
+          : 'http';
         const request = await api.createRequest(
           workspaceId,
           collectionId,
           folderPath,
           values.name,
-          values.type === 'graphql' ? 'graphql' : 'http'
+          type
         );
         await loadTree(workspaceId, true);
         if (!editorDirtyRef.current) {
@@ -664,9 +671,26 @@ export default function App() {
       const collection = findCollection(collectionId);
       const request = findRequest(collectionId, folderPath, requestId);
       if (collection && request) {
+        const key = `${collectionId}/${folderPath.join('/')}/${request.id}`;
+        if (request.type === 'websocket') {
+          return (
+            <ConnectionEditor
+              key={key}
+              workspaceId={tree.meta.id}
+              collectionId={collectionId}
+              folderPath={folderPath}
+              request={request}
+              onSaved={() => loadTree(tree.meta.id, true)}
+              onDelete={() =>
+                deleteRequestAction(collectionId, folderPath, request)
+              }
+              onDirtyChange={handleDirtyChange}
+            />
+          );
+        }
         return (
           <RequestEditor
-            key={`${collectionId}/${folderPath.join('/')}/${request.id}`}
+            key={key}
             workspaceId={tree.meta.id}
             collectionId={collectionId}
             folderPath={folderPath}
diff --git a/client/src/components/ConnectionEditor.tsx b/client/src/components/ConnectionEditor.tsx
new file mode 100644
index 0000000..6230e0f
--- /dev/null
+++ b/client/src/components/ConnectionEditor.tsx
@@ -0,0 +1,305 @@
+import { useEffect, useRef, useState } from 'react';
+import { api } from '../api';
+import { createLiveSession, type LiveSession } from '../live';
+import type { ApiRequest, SavedMessage } from '../types';
+import { AuthEditor } from './AuthEditor';
+import { DocsEditor } from './DocsEditor';
+import { KeyValueEditor } from './KeyValueEditor';
+import { MessageLogPanel, type LogEntry } from './MessageLogPanel';
+import { VarField } from './VarField';
+
+interface Props {
+  workspaceId: string;
+  collectionId: string;
+  folderPath: string[];
+  request: ApiRequest;
+  onSaved: (request: ApiRequest) => void;
+  onDelete: () => void;
+  onDirtyChange: (dirty: boolean) => void;
+}
+
+type Tab = 'connection' | 'headers' | 'auth' | 'messages' | 'docs';
+type Status = 'idle' | 'connecting' | 'open' | 'closed' | 'error';
+
+let logSeq = 0;
+const entry = (dir: LogEntry['dir'], text: string): LogEntry => ({
+  id: `${Date.now()}-${logSeq++}`,
+  dir,
+  text,
+  ts: Date.now(),
+});
+
+export function ConnectionEditor({
+  workspaceId,
+  collectionId,
+  folderPath,
+  request,
+  onSaved,
+  onDelete,
+  onDirtyChange,
+}: Props) {
+  const [saved, setSaved] = useState(request);
+  const [draft, setDraft] = useState(request);
+  const [tab, setTab] = useState<Tab>('connection');
+  const [status, setStatus] = useState<Status>('idle');
+  const [entries, setEntries] = useState<LogEntry[]>([]);
+  const [saveError, setSaveError] = useState<string | null>(null);
+  const sessionRef = useRef<LiveSession | null>(null);
+
+  const dirty = JSON.stringify(draft) !== JSON.stringify(saved);
+  const connected = status === 'open';
+
+  useEffect(() => {
+    onDirtyChange(dirty);
+  }, [dirty, onDirtyChange]);
+
+  // Close the live connection when navigating away / unmounting.
+  useEffect(
+    () => () => {
+      sessionRef.current?.close();
+      sessionRef.current = null;
+      onDirtyChange(false);
+    },
+    [onDirtyChange]
+  );
+
+  const patch = (changes: Partial<ApiRequest>) =>
+    setDraft((d) => ({ ...d, ...changes }));
+  const patchWs = (changes: Partial<ApiRequest['websocket']>) =>
+    setDraft((d) => ({ ...d, websocket: { ...d.websocket, ...changes } }));
+
+  const log = (e: LogEntry) => setEntries((prev) => [...prev, e]);
+
+  async function save() {
+    setSaveError(null);
+    try {
+      await api.updateRequest(workspaceId, collectionId, folderPath, draft);
+      setSaved(draft);
+      onSaved(draft);
+    } catch (err) {
+      setSaveError(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  function connect() {
+    if (sessionRef.current) return;
+    setStatus('connecting');
+    log(entry('system', `Connecting to ${draft.websocket.url}…`));
+    sessionRef.current = createLiveSession({
+      workspaceId,
+      collectionId,
+      folderPath,
+      request: draft,
+      onOpen: () => {
+        setStatus('open');
+        log(entry('system', 'Connected.'));
+      },
+      onMessage: (payload) => {
+        const p = payload as { data?: string; binary?: boolean };
+        log(entry('in', p?.binary ? `[binary ${p.data?.length ?? 0}b base64] ${p.data ?? ''}` : p?.data ?? ''));
+      },
+      onError: (message) => {
+        setStatus('error');
+        log(entry('system', `Error: ${message}`));
+      },
+      onClosed: (payload) => {
+        const p = payload as { code?: number; reason?: string } | undefined;
+        setStatus('closed');
+        log(entry('system', `Closed${p?.code ? ` (${p.code})` : ''}${p?.reason ? `: ${p.reason}` : ''}`));
+        sessionRef.current = null;
+      },
+    });
+  }
+
+  function disconnect() {
+    sessionRef.current?.close();
+    sessionRef.current = null;
+    setStatus('closed');
+    log(entry('system', 'Disconnected.'));
+  }
+
+  function sendMessage(text: string) {
+    sessionRef.current?.send({ data: text });
+    log(entry('out', text));
+  }
+
+  useEffect(() => {
+    function onKeyDown(e: KeyboardEvent) {
+      if ((e.metaKey || e.ctrlKey) && e.key === 's') {
+        e.preventDefault();
+        void save();
+      }
+    }
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+  });
+
+  return (
+    <div className="request-editor">
+      <div className="editor-title-row">
+        <span className="type-badge type-websocket">WS</span>
+        <input
+          className="name-input"
+          value={draft.name}
+          onChange={(e) => patch({ name: e.target.value })}
+        />
+        <button
+          className={dirty ? 'btn btn-primary' : 'btn'}
+          title={dirty ? 'You have unsaved changes' : 'No unsaved changes'}
+          onClick={save}
+        >
+          Save
+        </button>
+        <button className="btn btn-danger-ghost" onClick={onDelete}>
+          Delete
+        </button>
+      </div>
+      {saveError && <p className="error-text">{saveError}</p>}
+
+      <div className="url-row">
+        <span className={`conn-status conn-${status}`}>{status}</span>
+        <VarField
+          className="url-input"
+          wrapClassName="url-wrap"
+          value={draft.websocket.url}
+          placeholder="wss://echo.example.com/socket"
+          onChange={(url) => patchWs({ url })}
+        />
+        {connected || status === 'connecting' ? (
+          <button className="btn" onClick={disconnect}>
+            Disconnect
+          </button>
+        ) : (
+          <button
+            className="btn btn-primary"
+            onClick={connect}
+            disabled={!draft.websocket.url.trim()}
+          >
+            Connect
+          </button>
+        )}
+      </div>
+
+      <div className="tab-group editor-tabs">
+        {(
+          [
+            ['connection', 'Connection'],
+            ['headers', 'Headers'],
+            ['auth', 'Auth'],
+            ['messages', 'Saved Messages'],
+            ['docs', 'Docs'],
+          ] as [Tab, string][]
+        ).map(([value, label]) => (
+          <button
+            key={value}
+            className={tab === value ? 'tab active' : 'tab'}
+            onClick={() => setTab(value)}
+          >
+            {label}
+          </button>
+        ))}
+      </div>
+
+      <div className="tab-content">
+        {tab === 'connection' && (
+          <div className="kv-editor">
+            <label className="field-label">Subprotocols</label>
+            <VarField
+              className="kv-value"
+              wrapClassName="kv-value"
+              value={draft.websocket.subprotocols}
+              placeholder="comma- or space-separated (optional)"
+              onChange={(subprotocols) => patchWs({ subprotocols })}
+            />
+            <p className="muted">
+              Sent as <code>Sec-WebSocket-Protocol</code> during the handshake.
+            </p>
+          </div>
+        )}
+
+        {tab === 'headers' && (
+          <KeyValueEditor
+            items={draft.headers}
+            onChange={(headers) => patch({ headers })}
+            keyPlaceholder="Header"
+            addLabel="Header"
+          />
+        )}
+
+        {tab === 'auth' && (
+          <AuthEditor auth={draft.auth} onChange={(auth) => patch({ auth })} />
+        )}
+
+        {tab === 'messages' && (
+          <SavedMessagesEditor
+            messages={draft.websocket.messages}
+            onChange={(messages) => patchWs({ messages })}
+          />
+        )}
+
+        {tab === 'docs' && (
+          <DocsEditor
+            value={draft.docs}
+            onChange={(docs) => patch({ docs })}
+            placeholder="Document this connection in Markdown…"
+          />
+        )}
+      </div>
+
+      <MessageLogPanel
+        entries={entries}
+        connected={connected}
+        savedMessages={draft.websocket.messages}
+        onSend={sendMessage}
+        onClear={() => setEntries([])}
+        placeholder="Message to send…"
+      />
+    </div>
+  );
+}
+
+function SavedMessagesEditor({
+  messages,
+  onChange,
+}: {
+  messages: SavedMessage[];
+  onChange: (messages: SavedMessage[]) => void;
+}) {
+  const update = (i: number, changes: Partial<SavedMessage>) =>
+    onChange(messages.map((m, idx) => (idx === i ? { ...m, ...changes } : m)));
+  return (
+    <div className="saved-messages">
+      {messages.map((m, i) => (
+        <div key={i} className="saved-message">
+          <div className="saved-message-head">
+            <input
+              className="name-input"
+              value={m.name}
+              placeholder="Message name"
+              onChange={(e) => update(i, { name: e.target.value })}
+            />
+            <button
+              className="btn btn-ghost btn-sm"
+              onClick={() => onChange(messages.filter((_, idx) => idx !== i))}
+            >
+              Remove
+            </button>
+          </div>
+          <textarea
+            className="code-area"
+            value={m.content}
+            placeholder="Message content"
+            spellCheck={false}
+            onChange={(e) => update(i, { content: e.target.value })}
+          />
+        </div>
+      ))}
+      <button
+        className="btn btn-sm"
+        onClick={() => onChange([...messages, { name: `Message ${messages.length + 1}`, content: '' }])}
+      >
+        Add Saved Message
+      </button>
+    </div>
+  );
+}
diff --git a/client/src/components/MessageLogPanel.tsx b/client/src/components/MessageLogPanel.tsx
new file mode 100644
index 0000000..2f3a733
--- /dev/null
+++ b/client/src/components/MessageLogPanel.tsx
@@ -0,0 +1,132 @@
+import { useEffect, useRef, useState } from 'react';
+import type { SavedMessage } from '../types';
+
+export interface LogEntry {
+  id: string;
+  dir: 'in' | 'out' | 'system';
+  text: string;
+  ts: number;
+}
+
+interface Props {
+  entries: LogEntry[];
+  connected: boolean;
+  savedMessages: SavedMessage[];
+  onSend: (text: string) => void;
+  onClear: () => void;
+  /** Label for the send affordance (e.g. "Send" or "Emit"). */
+  sendLabel?: string;
+  /** Placeholder for the composer textarea. */
+  placeholder?: string;
+}
+
+function arrow(dir: LogEntry['dir']): string {
+  if (dir === 'in') return '↓';
+  if (dir === 'out') return '↑';
+  return '•';
+}
+
+export function MessageLogPanel({
+  entries,
+  connected,
+  savedMessages,
+  onSend,
+  onClear,
+  sendLabel = 'Send',
+  placeholder = 'Message to send…',
+}: Props) {
+  const [text, setText] = useState('');
+  const logRef = useRef<HTMLDivElement>(null);
+
+  // Auto-scroll to the newest entry.
+  useEffect(() => {
+    const el = logRef.current;
+    if (el) el.scrollTop = el.scrollHeight;
+  }, [entries.length]);
+
+  function send() {
+    if (!connected) return;
+    onSend(text);
+    setText('');
+  }
+
+  return (
+    <div className="message-log-panel">
+      <div className="response-header">
+        <span className="panel-title">Messages</span>
+        <div className="spacer" />
+        {entries.length > 0 && (
+          <button className="btn btn-ghost btn-sm" onClick={onClear}>
+            Clear
+          </button>
+        )}
+      </div>
+
+      <div className="message-log" ref={logRef}>
+        {entries.length === 0 ? (
+          <p className="muted response-placeholder">
+            {connected ? 'Connected. Send a message to begin.' : 'Not connected.'}
+          </p>
+        ) : (
+          entries.map((e) => (
+            <div key={e.id} className={`log-entry log-${e.dir}`}>
+              <span className="log-arrow">{arrow(e.dir)}</span>
+              <span className="log-time">
+                {new Date(e.ts).toLocaleTimeString([], {
+                  hour: '2-digit',
+                  minute: '2-digit',
+                  second: '2-digit',
+                })}
+              </span>
+              <pre className="log-text">{e.text}</pre>
+            </div>
+          ))
+        )}
+      </div>
+
+      <div className="message-composer">
+        <textarea
+          className="code-area"
+          value={text}
+          placeholder={placeholder}
+          spellCheck={false}
+          disabled={!connected}
+          onChange={(e) => setText(e.target.value)}
+          onKeyDown={(e) => {
+            if ((e.metaKey || e.ctrlKey) && e.key === 'Enter') {
+              e.preventDefault();
+              send();
+            }
+          }}
+        />
+        <div className="composer-actions">
+          {savedMessages.length > 0 && (
+            <select
+              className="method-select"
+              value=""
+              onChange={(e) => {
+                const m = savedMessages.find((s) => s.name === e.target.value);
+                if (m) setText(m.content);
+              }}
+            >
+              <option value="">Saved messages…</option>
+              {savedMessages.map((m) => (
+                <option key={m.name} value={m.name}>
+                  {m.name}
+                </option>
+              ))}
+            </select>
+          )}
+          <button
+            className="btn btn-primary"
+            onClick={send}
+            disabled={!connected}
+            title="Send (⌘/Ctrl+Enter)"
+          >
+            {sendLabel}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/client/src/components/Sidebar.tsx b/client/src/components/Sidebar.tsx
index 08a7041..c42bb0b 100644
--- a/client/src/components/Sidebar.tsx
+++ b/client/src/components/Sidebar.tsx
@@ -66,6 +66,18 @@ interface MenuItem {
 const pathKey = (collectionId: string, folderPath: string[]): string =>
   [collectionId, ...folderPath].join('/');
 
+function badgeLabel(request: ApiRequest): string {
+  if (request.type === 'graphql') return 'GQL';
+  if (request.type === 'websocket') return 'WS';
+  return request.method;
+}
+
+function badgeClass(request: ApiRequest): string {
+  if (request.type === 'graphql') return 'method-GQL';
+  if (request.type === 'websocket') return 'method-WS';
+  return `method-${request.method}`;
+}
+
 const INDENT = 16;
 
 export function Sidebar({
@@ -226,14 +238,8 @@ export function Sidebar({
         {...dragSource({ kind: 'request', collectionId, folderPath, requestId: request.id })}
       >
         <button className="row-label" onClick={() => onSelect(sel)}>
-          <span
-            className={
-              request.type === 'graphql'
-                ? 'method-tag method-GQL'
-                : `method-tag method-${request.method}`
-            }
-          >
-            {request.type === 'graphql' ? 'GQL' : request.method}
+          <span className={`method-tag ${badgeClass(request)}`}>
+            {badgeLabel(request)}
           </span>
           {request.name}
         </button>
diff --git a/client/src/curl.ts b/client/src/curl.ts
index 74ab3e3..ae019d4 100644
--- a/client/src/curl.ts
+++ b/client/src/curl.ts
@@ -20,6 +20,9 @@ export function requestToCurl(
   req: ApiRequest,
   vars: Record<string, string>
 ): string {
+  if (req.type !== 'http' && req.type !== 'graphql') {
+    return `# Cannot export a ${req.type} request as cURL`;
+  }
   const i = (t: string) => interpolate(t, vars);
   const method = req.type === 'graphql' ? 'POST' : req.method;
 
@@ -290,6 +293,7 @@ export function parseCurl(command: string): Omit<ApiRequest, 'id'> {
     auth: basic ? { type: 'basic', basic } : { type: 'none' },
     body: { mode, content, form, formData, binaryPath },
     graphql: { query: '', variables: '' },
+    websocket: { url: '', subprotocols: '', messages: [] },
     docs: '',
     scripts: { preRequest: '', postResponse: '' },
   };
diff --git a/client/src/live.ts b/client/src/live.ts
new file mode 100644
index 0000000..758c565
--- /dev/null
+++ b/client/src/live.ts
@@ -0,0 +1,114 @@
+import type { ApiRequest } from './types';
+
+/**
+ * Browser side of the live channel. A single WebSocket to our own server (/live)
+ * is shared by every live session; each session is keyed by a sessionId. The
+ * server owns the real outbound connection (WebSocket/Socket.IO/MCP).
+ */
+
+interface ServerFrame {
+  t: 'open' | 'message' | 'error' | 'closed';
+  sessionId: string;
+  payload?: unknown;
+  ts?: number;
+}
+
+export interface LiveSessionHandlers {
+  workspaceId: string;
+  collectionId: string;
+  folderPath: string[];
+  request: ApiRequest;
+  onOpen?: (info: unknown) => void;
+  onMessage?: (payload: unknown, ts: number) => void;
+  onError?: (message: string) => void;
+  onClosed?: (payload: unknown) => void;
+}
+
+export interface LiveSession {
+  send: (payload: unknown) => void;
+  close: () => void;
+}
+
+type Handlers = Map<string, LiveSessionHandlers>;
+
+let socket: WebSocket | null = null;
+let connecting: Promise<WebSocket> | null = null;
+const handlers: Handlers = new Map();
+const pending: string[] = [];
+
+function liveUrl(): string {
+  const { protocol, host } = window.location;
+  return `${protocol === 'https:' ? 'wss' : 'ws'}://${host}/live`;
+}
+
+function ensureSocket(): Promise<WebSocket> {
+  if (socket && socket.readyState === WebSocket.OPEN) return Promise.resolve(socket);
+  if (connecting) return connecting;
+  connecting = new Promise((resolve, reject) => {
+    const s = new WebSocket(liveUrl());
+    s.onopen = () => {
+      socket = s;
+      connecting = null;
+      while (pending.length) s.send(pending.shift()!);
+      resolve(s);
+    };
+    s.onerror = () => {
+      connecting = null;
+      reject(new Error('Live channel connection failed'));
+    };
+    s.onclose = () => {
+      socket = null;
+      // Notify every active session so editors can reflect the drop.
+      for (const [, h] of handlers) h.onClosed?.({ reason: 'channel closed' });
+      handlers.clear();
+    };
+    s.onmessage = (ev) => {
+      let frame: ServerFrame;
+      try {
+        frame = JSON.parse(ev.data as string) as ServerFrame;
+      } catch {
+        return;
+      }
+      const h = handlers.get(frame.sessionId);
+      if (!h) return;
+      if (frame.t === 'open') h.onOpen?.(frame.payload);
+      else if (frame.t === 'message') h.onMessage?.(frame.payload, frame.ts ?? Date.now());
+      else if (frame.t === 'error')
+        h.onError?.((frame.payload as { message?: string })?.message ?? 'Error');
+      else if (frame.t === 'closed') {
+        h.onClosed?.(frame.payload);
+        handlers.delete(frame.sessionId);
+      }
+    };
+  });
+  return connecting;
+}
+
+function rawSend(frame: Record<string, unknown>): void {
+  const text = JSON.stringify(frame);
+  if (socket && socket.readyState === WebSocket.OPEN) socket.send(text);
+  else pending.push(text);
+}
+
+export function createLiveSession(h: LiveSessionHandlers): LiveSession {
+  const sessionId = crypto.randomUUID();
+  handlers.set(sessionId, h);
+  void ensureSocket().catch((err) => {
+    h.onError?.(err instanceof Error ? err.message : String(err));
+  });
+  rawSend({
+    t: 'connect',
+    sessionId,
+    workspaceId: h.workspaceId,
+    collectionId: h.collectionId,
+    folderPath: h.folderPath.join('/'),
+    request: h.request,
+  });
+  return {
+    send: (payload: unknown) => rawSend({ t: 'send', sessionId, payload }),
+    close: () => {
+      rawSend({ t: 'close', sessionId });
+      handlers.delete(sessionId);
+    },
+  };
+}
diff --git a/client/src/styles.css b/client/src/styles.css
index 061d825..a3a50eb 100644
--- a/client/src/styles.css
+++ b/client/src/styles.css
@@ -215,6 +215,7 @@ pre,
 .method-HEAD,
 .method-OPTIONS { color: var(--text-muted); }
 .method-GQL { color: var(--pink); }
+.method-WS { color: var(--blue); }
 
 /* ---------- main pane ---------- */
 
@@ -294,6 +295,79 @@ pre,
 .type-env { background: #24303b; color: var(--blue); }
 .type-collection { background: #3b3324; color: var(--yellow); }
 .type-folder { background: #2a3340; color: var(--blue); }
+.type-websocket { background: #24323b; color: var(--blue); }
+
+/* ----- live connection (WebSocket/Socket.IO/MCP) ----- */
+.conn-status {
+  text-transform: uppercase;
+  font-size: 0.7rem;
+  font-weight: 700;
+  letter-spacing: 0.05em;
+  padding: 4px 8px;
+  border-radius: 6px;
+  background: rgba(255, 255, 255, 0.06);
+  color: var(--text-muted);
+  min-width: 78px;
+  text-align: center;
+}
+.conn-open { background: rgba(70, 180, 110, 0.18); color: var(--green); }
+.conn-connecting { background: rgba(220, 180, 70, 0.18); color: var(--yellow); }
+.conn-error { background: rgba(220, 90, 90, 0.18); color: var(--red); }
+.conn-closed { background: rgba(255, 255, 255, 0.06); color: var(--text-muted); }
+
+.message-log-panel {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
+  border-top: 1px solid var(--border);
+}
+.message-log {
+  flex: 1;
+  min-height: 120px;
+  overflow-y: auto;
+  padding: 8px 12px;
+  font-family: var(--mono, monospace);
+  font-size: 0.85rem;
+}
+.log-entry {
+  display: grid;
+  grid-template-columns: 14px 64px 1fr;
+  gap: 8px;
+  padding: 2px 0;
+  align-items: start;
+}
+.log-arrow { color: var(--text-muted); }
+.log-in .log-arrow { color: var(--green); }
+.log-out .log-arrow { color: var(--blue); }
+.log-time { color: var(--text-muted); font-size: 0.75rem; }
+.log-text { margin: 0; white-space: pre-wrap; word-break: break-word; }
+.log-system .log-text { color: var(--text-muted); font-style: italic; }
+
+.message-composer {
+  display: flex;
+  gap: 8px;
+  padding: 8px 12px;
+  border-top: 1px solid var(--border);
+}
+.message-composer .code-area { flex: 1; min-height: 56px; }
+.composer-actions {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  justify-content: flex-start;
+}
+
+.saved-messages { display: flex; flex-direction: column; gap: 12px; }
+.saved-message { display: flex; flex-direction: column; gap: 6px; }
+.saved-message-head { display: flex; gap: 8px; align-items: center; }
+.saved-message .code-area { min-height: 60px; }
+.field-label {
+  display: block;
+  font-size: 0.85rem;
+  color: var(--text-muted);
+  margin-bottom: 4px;
+}
 
 .ctx-backdrop {
   position: fixed;
diff --git a/client/src/types.ts b/client/src/types.ts
index 8db2a00..14c57cc 100644
--- a/client/src/types.ts
+++ b/client/src/types.ts
@@ -1,4 +1,4 @@
-export type RequestType = 'http' | 'graphql';
+export type RequestType = 'http' | 'graphql' | 'websocket';
 
 export type HttpMethod =
   | 'GET'
@@ -62,6 +62,20 @@ export interface GraphQLBody {
   variables: string;
 }
 
+/** A reusable message/payload template the user can send on a live connection. */
+export interface SavedMessage {
+  name: string;
+  content: string;
+}
+
+/** WebSocket connection config (handshake reuses the request's headers + auth). */
+export interface WebSocketConfig {
+  url: string;
+  /** Comma- or space-separated Sec-WebSocket-Protocol values. */
+  subprotocols: string;
+  messages: SavedMessage[];
+}
+
 /** Postman-style automation scripts (JavaScript using the `pm` API). */
 export interface Scripts {
   preRequest: string;
@@ -79,6 +93,7 @@ export interface ApiRequest {
   auth: AuthConfig;
   body: RequestBody;
   graphql: GraphQLBody;
+  websocket: WebSocketConfig;
   docs: string;
   scripts: Scripts;
 }
diff --git a/client/vite.config.ts b/client/vite.config.ts
index 91e3418..00f038e 100644
--- a/client/vite.config.ts
+++ b/client/vite.config.ts
@@ -7,6 +7,8 @@ export default defineConfig({
     port: 5173,
     proxy: {
       '/api': 'http://localhost:3001',
+      // The live channel (WebSocket/Socket.IO/MCP) needs the upgrade proxied.
+      '/live': { target: 'ws://localhost:3001', ws: true },
     },
   },
 });
diff --git a/package-lock.json b/package-lock.json
index e7f9fce..39257f7 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -2704,7 +2704,6 @@
       "version": "22.19.21",
       "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.21.tgz",
       "integrity": "sha512-VMeFBSCKQKmm2swI2kW51SFusDqekC6q9trBCvJ/JliDchFSuoYYKN7yVNjPthP1HKZcx3U1gI/wTcEBjEFKTA==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "undici-types": "~6.21.0"
@@ -2819,6 +2818,15 @@
       "integrity": "sha512-zFDAD+tlpf2r4asuHEj0XH6pY6i0g5NeAHPn+15wk3BV6JA69eERFXC1gyGThDkVa1zCyKr5jox1+2LbV/AMLg==",
       "license": "MIT"
     },
+    "node_modules/@types/ws": {
+      "version": "8.18.1",
+      "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.1.tgz",
+      "integrity": "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
     "node_modules/@ungap/structured-clone": {
       "version": "1.3.1",
       "resolved": "https://registry.npmjs.org/@ungap/structured-clone/-/structured-clone-1.3.1.tgz",
@@ -7135,7 +7143,6 @@
       "version": "6.21.0",
       "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
       "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/unified": {
@@ -8067,6 +8074,27 @@
       "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
       "license": "ISC"
     },
+    "node_modules/ws": {
+      "version": "8.21.0",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz",
+      "integrity": "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/y18n": {
       "version": "5.0.8",
       "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz",
@@ -8146,9 +8174,11 @@
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.29.0",
+        "@types/ws": "^8.18.1",
         "cors": "^2.8.5",
         "express": "^4.21.2",
         "tough-cookie": "^6.0.1",
+        "ws": "^8.21.0",
         "zod": "^4.4.3"
       },
       "devDependencies": {
diff --git a/server/package.json b/server/package.json
index 27c4050..d71a54d 100644
--- a/server/package.json
+++ b/server/package.json
@@ -13,9 +13,11 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@types/ws": "^8.18.1",
     "cors": "^2.8.5",
     "express": "^4.21.2",
     "tough-cookie": "^6.0.1",
+    "ws": "^8.21.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
diff --git a/server/src/index.ts b/server/src/index.ts
index a6f6164..6fa651b 100644
--- a/server/src/index.ts
+++ b/server/src/index.ts
@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import http from 'node:http';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import cors from 'cors';
@@ -7,6 +8,7 @@ import express, {
   type Request,
   type Response,
 } from 'express';
+import { attachLiveSessions } from './liveSessions.js';
 import { registerMcp } from './mcp.js';
 import { router } from './router.js';
 import { HttpError } from './workspaceFs.js';
@@ -45,6 +47,11 @@ app.use(
   }
 );
 
-app.listen(PORT, () => {
+// Explicit HTTP server so the live channel (WebSocket/Socket.IO/MCP) can attach
+// to the same port via the HTTP upgrade event at /live.
+const server = http.createServer(app);
+attachLiveSessions(server);
+
+server.listen(PORT, () => {
   console.log(`API Notebook server listening on http://localhost:${PORT}`);
 });
diff --git a/server/src/live/driver.ts b/server/src/live/driver.ts
new file mode 100644
index 0000000..c17dcea
--- /dev/null
+++ b/server/src/live/driver.ts
@@ -0,0 +1,29 @@
+import type { CookieJar } from 'tough-cookie';
+import type { ApiRequest } from '../types.js';
+
+/** Events a driver pushes back toward the browser for its session. */
+export type EmitKind = 'open' | 'message' | 'error' | 'closed';
+export type Emit = (kind: EmitKind, data?: unknown) => void;
+
+export interface DriverContext {
+  /** The request as sent by the client (drivers interpolate their own fields). */
+  request: ApiRequest;
+  /** Active-environment variables for {{var}} interpolation. */
+  vars: Record<string, string>;
+  /** Workspace cookie jar (for the handshake Cookie header). */
+  jar: CookieJar;
+  emit: Emit;
+}
+
+/**
+ * A driver owns one outbound connection (WebSocket, Socket.IO, MCP, …) for a
+ * single live session. The session manager calls open() once, forwards send()
+ * for each client message, and calls close() on teardown.
+ */
+export interface LiveDriver {
+  open(): Promise<void> | void;
+  send(payload: unknown): void | Promise<void>;
+  close(): void;
+}
+
+export type DriverFactory = (ctx: DriverContext) => LiveDriver;
diff --git a/server/src/live/wsDriver.ts b/server/src/live/wsDriver.ts
new file mode 100644
index 0000000..1fc4f0a
--- /dev/null
+++ b/server/src/live/wsDriver.ts
@@ -0,0 +1,107 @@
+import WebSocket from 'ws';
+import { interpolate } from '../execute.js';
+import type { AuthConfig } from '../types.js';
+import type { DriverContext, LiveDriver } from './driver.js';
+
+/** Builds the handshake headers (interpolated request headers + auth + cookies). */
+function buildHeaders(ctx: DriverContext, url: URL): Record<string, string> {
+  const { request, vars, jar } = ctx;
+  const headers: Record<string, string> = {};
+  for (const h of request.headers) {
+    if (h.enabled && h.key) headers[interpolate(h.key, vars)] = interpolate(h.value, vars);
+  }
+  applyAuth(headers, url, request.auth, vars);
+  // Reuse the workspace jar for the handshake (map ws→http for matching).
+  try {
+    const httpUrl = url.toString().replace(/^ws/, 'http');
+    const cookie = jar.getCookieStringSync(httpUrl);
+    if (cookie) headers['cookie'] = cookie;
+  } catch {
+    // No cookies for this URL.
+  }
+  return headers;
+}
+
+function applyAuth(
+  headers: Record<string, string>,
+  url: URL,
+  auth: AuthConfig,
+  vars: Record<string, string>
+): void {
+  switch (auth.type) {
+    case 'bearer':
+      headers['authorization'] = `Bearer ${interpolate(auth.bearer?.token ?? '', vars)}`;
+      break;
+    case 'basic': {
+      const user = interpolate(auth.basic?.username ?? '', vars);
+      const pass = interpolate(auth.basic?.password ?? '', vars);
+      headers['authorization'] = `Basic ${Buffer.from(`${user}:${pass}`).toString('base64')}`;
+      break;
+    }
+    case 'apiKey': {
+      const key = interpolate(auth.apiKey?.key ?? '', vars);
+      const value = interpolate(auth.apiKey?.value ?? '', vars);
+      if (key) {
+        if (auth.apiKey?.placement === 'query') url.searchParams.append(key, value);
+        else headers[key] = value;
+      }
+      break;
+    }
+  }
+}
+
+export function createWsDriver(ctx: DriverContext): LiveDriver {
+  let socket: WebSocket | null = null;
+
+  return {
+    open() {
+      const raw = interpolate(ctx.request.websocket.url, ctx.vars).trim();
+      let url: URL;
+      try {
+        url = new URL(raw);
+      } catch {
+        throw new Error(`Invalid WebSocket URL: "${raw}"`);
+      }
+      if (url.protocol !== 'ws:' && url.protocol !== 'wss:') {
+        throw new Error('WebSocket URL must start with ws:// or wss://');
+      }
+      const headers = buildHeaders(ctx, url);
+      const protocols = ctx.request.websocket.subprotocols
+        .split(/[\s,]+/)
+        .filter(Boolean);
+
+      socket = new WebSocket(url.toString(), protocols, { headers });
+      socket.on('open', () =>
+        ctx.emit('open', { protocol: socket?.protocol || undefined })
+      );
+      socket.on('message', (data: WebSocket.RawData, isBinary: boolean) => {
+        const buf = Array.isArray(data)
+          ? Buffer.concat(data)
+          : Buffer.from(data as ArrayBuffer);
+        if (isBinary) {
+          ctx.emit('message', { data: buf.toString('base64'), binary: true });
+        } else {
+          ctx.emit('message', { data: buf.toString('utf8') });
+        }
+      });
+      socket.on('error', (err: Error) => ctx.emit('error', err.message));
+      socket.on('close', (code: number, reason: Buffer) =>
+        ctx.emit('closed', { code, reason: reason.toString('utf8') })
+      );
+    },
+
+    send(payload: unknown) {
+      const data = (payload as { data?: string } | null)?.data ?? '';
+      if (socket && socket.readyState === WebSocket.OPEN) socket.send(data);
+    },
+
+    close() {
+      try {
+        socket?.close();
+      } catch {
+        socket?.terminate();
+      }
+      socket = null;
+    },
+  };
+}
diff --git a/server/src/liveSessions.integration.test.ts b/server/src/liveSessions.integration.test.ts
new file mode 100644
index 0000000..bf4f071
--- /dev/null
+++ b/server/src/liveSessions.integration.test.ts
@@ -0,0 +1,128 @@
+import http from 'node:http';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { WebSocket, WebSocketServer } from 'ws';
+import type { ApiRequest } from './types.js';
+
+// Redirect app-local state (~/.apinotebook) to a temp home before importing the
+// modules (appData/cookies compute their dirs at module load).
+let tmpHome: string;
+let wsDir: string;
+let appServer: http.Server;
+let liveUrl: string;
+let echo: WebSocketServer;
+let echoUrl: string;
+let wsId: string;
+let makeRequest: (over: Partial<ApiRequest>) => ApiRequest;
+
+function listening(server: http.Server): Promise<void> {
+  return new Promise((r) => server.listen(0, '127.0.0.1', () => r()));
+}
+function portOf(server: { address(): unknown }): number {
+  const addr = server.address();
+  return typeof addr === 'object' && addr ? (addr as { port: number }).port : 0;
+}
+
+beforeAll(async () => {
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'apinb-home-'));
+  wsDir = fs.mkdtempSync(path.join(os.tmpdir(), 'apinb-wsdir-'));
+  vi.spyOn(os, 'homedir').mockReturnValue(tmpHome);
+  vi.resetModules();
+
+  const wsfs = await import('./workspaceFs.js');
+  const appData = await import('./appData.js');
+  const { attachLiveSessions } = await import('./liveSessions.js');
+
+  const meta = wsfs.createWorkspace('Live WS', wsDir);
+  appData.addWorkspaceEntry({ id: meta.id, path: meta.path });
+  wsId = meta.id;
+  makeRequest = (over) => ({ ...wsfs.defaultRequest('r', 'r', 'websocket'), ...over });
+
+  // In-test WebSocket echo server (the "target").
+  echo = new WebSocketServer({ port: 0, host: '127.0.0.1' });
+  echo.on('connection', (s) => {
+    s.on('message', (m, isBinary) => s.send(m, { binary: isBinary }));
+  });
+  await new Promise<void>((r) => echo.once('listening', () => r()));
+  echoUrl = `ws://127.0.0.1:${portOf(echo)}`;
+
+  // Our server with the live channel attached.
+  appServer = http.createServer();
+  attachLiveSessions(appServer);
+  await listening(appServer);
+  liveUrl = `ws://127.0.0.1:${portOf(appServer)}/live`;
+});
+
+afterAll(async () => {
+  vi.restoreAllMocks();
+  echo.close();
+  await new Promise<void>((r) => appServer.close(() => r()));
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+  fs.rmSync(wsDir, { recursive: true, force: true });
+});
+
+interface Frame {
+  t: string;
+  sessionId: string;
+  payload?: { data?: string; message?: string; code?: number };
+}
+
+describe('live channel — WebSocket', () => {
+  it('connects, echoes a message, and closes', async () => {
+    const client = new WebSocket(liveUrl);
+    await new Promise<void>((r) => client.once('open', () => r()));
+
+    const nextFrame = (pred: (f: Frame) => boolean): Promise<Frame> =>
+      new Promise((resolve) => {
+        const onMsg = (d: WebSocket.RawData) => {
+          const f = JSON.parse(d.toString()) as Frame;
+          if (pred(f)) {
+            client.off('message', onMsg);
+            resolve(f);
+          }
+        };
+        client.on('message', onMsg);
+      });
+
+    const request = makeRequest({
+      websocket: { url: echoUrl, subprotocols: '', messages: [] },
+    });
+    client.send(
+      JSON.stringify({ t: 'connect', sessionId: 'S1', workspaceId: wsId, request })
+    );
+    const opened = await nextFrame((f) => f.t === 'open' && f.sessionId === 'S1');
+    expect(opened.t).toBe('open');
+
+    client.send(JSON.stringify({ t: 'send', sessionId: 'S1', payload: { data: 'hello' } }));
+    const msg = await nextFrame((f) => f.t === 'message' && f.sessionId === 'S1');
+    expect(msg.payload?.data).toBe('hello');
+
+    client.send(JSON.stringify({ t: 'close', sessionId: 'S1' }));
+    const closed = await nextFrame((f) => f.t === 'closed' && f.sessionId === 'S1');
+    expect(closed.t).toBe('closed');
+
+    client.close();
+  });
+
+  it('reports an error for an invalid target URL', async () => {
+    const client = new WebSocket(liveUrl);
+    await new Promise<void>((r) => client.once('open', () => r()));
+    const request = makeRequest({
+      websocket: { url: 'http://not-websocket/', subprotocols: '', messages: [] },
+    });
+    const errored = new Promise<Frame>((resolve) => {
+      client.on('message', (d) => {
+        const f = JSON.parse(d.toString()) as Frame;
+        if (f.t === 'error' && f.sessionId === 'S2') resolve(f);
+      });
+    });
+    client.send(
+      JSON.stringify({ t: 'connect', sessionId: 'S2', workspaceId: wsId, request })
+    );
+    const f = await errored;
+    expect(f.payload?.message).toMatch(/ws:\/\/|wss:\/\//);
+    client.close();
+  });
+});
diff --git a/server/src/liveSessions.ts b/server/src/liveSessions.ts
new file mode 100644
index 0000000..a3cda38
--- /dev/null
+++ b/server/src/liveSessions.ts
@@ -0,0 +1,171 @@
+import type { Server } from 'node:http';
+import { WebSocketServer, type WebSocket } from 'ws';
+import * as appData from './appData.js';
+import * as cookies from './cookies.js';
+import { envToVars } from './execute.js';
+import * as wsfs from './workspaceFs.js';
+import type { ApiRequest } from './types.js';
+import type { DriverContext, Emit, LiveDriver } from './live/driver.js';
+import { createWsDriver } from './live/wsDriver.js';
+
+/**
+ * The live channel: a single browser WebSocket (at /live) multiplexes many
+ * streaming sessions (WebSocket/Socket.IO/MCP), each keyed by a sessionId. The
+ * Node server owns every outbound connection so {{var}} interpolation, the
+ * cookie jar, and auth stay consistent with HTTP requests.
+ *
+ * Server→client frames all share the shape { t, sessionId, payload, ts }:
+ *   open    → payload: connection info (e.g. { protocol })
+ *   message → payload: protocol-specific message
+ *   error   → payload: { message }
+ *   closed  → payload: { code?, reason? }
+ */
+
+const MAX_SESSIONS_PER_SOCKET = 16;
+const MAX_SESSIONS_GLOBAL = 200;
+// Bound resource leaks: a session is force-closed after this long.
+const SESSION_MAX_MS = 60 * 60_000;
+
+interface ConnectFrame {
+  t: 'connect';
+  sessionId: string;
+  workspaceId: string;
+  request: ApiRequest;
+}
+interface SendFrame {
+  t: 'send';
+  sessionId: string;
+  payload: unknown;
+}
+interface CloseFrame {
+  t: 'close';
+  sessionId: string;
+}
+type ClientFrame = ConnectFrame | SendFrame | CloseFrame;
+
+interface Session {
+  driver: LiveDriver;
+  lifetime: NodeJS.Timeout;
+}
+
+let globalSessions = 0;
+
+function driverFor(type: ApiRequest['type'], ctx: DriverContext): LiveDriver {
+  switch (type) {
+    case 'websocket':
+      return createWsDriver(ctx);
+    default:
+      throw new Error(`Protocol "${type}" is not supported on the live channel`);
+  }
+}
+
+function errMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+export function attachLiveSessions(server: Server): WebSocketServer {
+  const wss = new WebSocketServer({ server, path: '/live', maxPayload: 1 << 20 });
+
+  wss.on('connection', (socket: WebSocket) => {
+    const sessions = new Map<string, Session>();
+
+    const send = (sessionId: string, t: string, payload?: unknown) => {
+      if (socket.readyState === socket.OPEN) {
+        socket.send(JSON.stringify({ t, sessionId, payload, ts: Date.now() }));
+      }
+    };
+    const fail = (sessionId: string, message: string) =>
+      send(sessionId, 'error', { message });
+
+    const cleanup = (sessionId: string) => {
+      const session = sessions.get(sessionId);
+      if (!session) return;
+      sessions.delete(sessionId);
+      globalSessions--;
+      clearTimeout(session.lifetime);
+      try {
+        session.driver.close();
+      } catch {
+        // best-effort teardown
+      }
+    };
+
+    const startSession = (frame: ConnectFrame) => {
+      const { sessionId, workspaceId, request } = frame;
+      if (sessions.has(sessionId)) return;
+      if (
+        sessions.size >= MAX_SESSIONS_PER_SOCKET ||
+        globalSessions >= MAX_SESSIONS_GLOBAL
+      ) {
+        fail(sessionId, 'Too many open connections');
+        return;
+      }
+
+      let driver: LiveDriver;
+      try {
+        const entry = appData.findWorkspaceEntry(workspaceId);
+        if (!entry) throw new Error(`Workspace "${workspaceId}" is not registered`);
+        const ws = wsfs.openWorkspace(entry.path);
+        const activeId = appData.getActiveEnvironmentId(ws.id);
+        const env = activeId ? wsfs.getEnvironment(ws, activeId) : undefined;
+        const emit: Emit = (kind, data) => {
+          send(sessionId, kind, kind === 'error' ? { message: errMessage(data) } : data);
+          if (kind === 'closed') cleanup(sessionId);
+        };
+        const ctx: DriverContext = {
+          request,
+          vars: envToVars(env),
+          jar: cookies.loadJar(ws.id),
+          emit,
+        };
+        driver = driverFor(request.type, ctx);
+      } catch (err) {
+        fail(sessionId, errMessage(err));
+        return;
+      }
+
+      const lifetime = setTimeout(() => {
+        fail(sessionId, 'Connection lifetime exceeded');
+        cleanup(sessionId);
+      }, SESSION_MAX_MS);
+      sessions.set(sessionId, { driver, lifetime });
+      globalSessions++;
+
+      Promise.resolve()
+        .then(() => driver.open())
+        .catch((err) => {
+          fail(sessionId, errMessage(err));
+          cleanup(sessionId);
+        });
+    };
+
+    socket.on('message', (raw) => {
+      let frame: ClientFrame;
+      try {
+        frame = JSON.parse(raw.toString()) as ClientFrame;
+      } catch {
+        return;
+      }
+      if (frame.t === 'connect') {
+        startSession(frame);
+      } else if (frame.t === 'send') {
+        const session = sessions.get(frame.sessionId);
+        if (!session) return;
+        Promise.resolve()
+          .then(() => session.driver.send(frame.payload))
+          .catch((err) => fail(frame.sessionId, errMessage(err)));
+      } else if (frame.t === 'close') {
+        cleanup(frame.sessionId);
+        send(frame.sessionId, 'closed', {});
+      }
+    });
+
+    const teardownAll = () => {
+      for (const id of [...sessions.keys()]) cleanup(id);
+    };
+    socket.on('close', teardownAll);
+    socket.on('error', teardownAll);
+  });
+
+  return wss;
+}
diff --git a/server/src/postmanImport.ts b/server/src/postmanImport.ts
index 661263e..0336c79 100644
--- a/server/src/postmanImport.ts
+++ b/server/src/postmanImport.ts
@@ -284,6 +284,7 @@ function convertRequest(item: PostmanItem): ConvertedRequest {
     auth: convertAuth(req.auth),
     body,
     graphql,
+    websocket: { url: '', subprotocols: '', messages: [] },
     docs: describe(req.description),
     scripts: eventsToScripts(item.event),
   };
diff --git a/server/src/router.ts b/server/src/router.ts
index 68846b3..202958f 100644
--- a/server/src/router.ts
+++ b/server/src/router.ts
@@ -190,7 +190,8 @@ router.post(
   wrap((req, res) => {
     const ws = getWorkspace(req.params.id);
     const name = requireString(req.body.name, 'name');
-    const type = req.body.type === 'graphql' ? 'graphql' : 'http';
+    const allowed = ['http', 'graphql', 'websocket'] as const;
+    const type = allowed.includes(req.body.type) ? req.body.type : 'http';
     const folderPath = parseFolderPath(req.body.folderPath);
     res
       .status(201)
diff --git a/server/src/types.ts b/server/src/types.ts
index 5c45ad7..689be87 100644
--- a/server/src/types.ts
+++ b/server/src/types.ts
@@ -1,4 +1,4 @@
-export type RequestType = 'http' | 'graphql';
+export type RequestType = 'http' | 'graphql' | 'websocket';
 
 export type HttpMethod =
   | 'GET'
@@ -52,6 +52,20 @@ export interface GraphQLBody {
   variables: string;
 }
 
+/** A reusable message/payload template the user can send on a live connection. */
+export interface SavedMessage {
+  name: string;
+  content: string;
+}
+
+/** WebSocket connection config (handshake reuses the request's headers + auth). */
+export interface WebSocketConfig {
+  url: string;
+  /** Comma- or space-separated Sec-WebSocket-Protocol values. */
+  subprotocols: string;
+  messages: SavedMessage[];
+}
+
 /** Postman-style automation scripts (JavaScript using the `pm` API). */
 export interface Scripts {
   preRequest: string;
@@ -69,6 +83,7 @@ export interface ApiRequest {
   auth: AuthConfig;
   body: RequestBody;
   graphql: GraphQLBody;
+  websocket: WebSocketConfig;
   docs: string;
   scripts: Scripts;
 }
diff --git a/server/src/workspaceFs.test.ts b/server/src/workspaceFs.test.ts
index bb47fe7..a8f8145 100644
--- a/server/src/workspaceFs.test.ts
+++ b/server/src/workspaceFs.test.ts
@@ -116,6 +116,24 @@ describe('collections & requests (round-trip)', () => {
     expect(collection.folders).toEqual([]);
   });
 
+  it('persists a websocket request with its config and saved messages', () => {
+    const col = wsfs.createCollection(ws, 'WS');
+    const created = wsfs.createRequest(ws, col.id, [], 'Socket', 'websocket');
+    expect(created.websocket).toEqual({ url: '', subprotocols: '', messages: [] });
+    wsfs.updateRequest(ws, col.id, [], created.id, {
+      ...created,
+      websocket: {
+        url: 'wss://x/socket',
+        subprotocols: 'json',
+        messages: [{ name: 'ping', content: '{"op":"ping"}' }],
+      },
+    });
+    const read = wsfs.getRequest(ws, col.id, [], created.id);
+    expect(read.type).toBe('websocket');
+    expect(read.websocket.url).toBe('wss://x/socket');
+    expect(read.websocket.messages).toEqual([{ name: 'ping', content: '{"op":"ping"}' }]);
+  });
+
   it('back-fills missing fields and reads a legacy requests/ subdir', () => {
     const col = wsfs.createCollection(ws, 'Old');
     // Pre-folders workspaces stored requests in a legacy requests/ subdir.
diff --git a/server/src/workspaceFs.ts b/server/src/workspaceFs.ts
index 3d40b3a..d05ed37 100644
--- a/server/src/workspaceFs.ts
+++ b/server/src/workspaceFs.ts
@@ -228,10 +228,12 @@ function readRequest(
   const docs = fs.existsSync(docsFile)
     ? fs.readFileSync(docsFile, 'utf8')
     : '';
-  // Files written by older versions may predate newer body/script/graphql fields.
+  // Files written by older versions may predate newer body/script/graphql/
+  // websocket fields, so back-fill each sub-object with its defaults.
   const storedBody: Partial<ApiRequest['body']> = stored.body ?? {};
   const storedScripts: Partial<ApiRequest['scripts']> = stored.scripts ?? {};
   const storedGraphql: Partial<ApiRequest['graphql']> = stored.graphql ?? {};
+  const storedWebsocket: Partial<ApiRequest['websocket']> = stored.websocket ?? {};
   return {
     ...stored,
     body: {
@@ -244,6 +246,7 @@ function readRequest(
     },
     scripts: { preRequest: '', postResponse: '', ...storedScripts },
     graphql: { query: '', variables: '', ...storedGraphql },
+    websocket: { url: '', subprotocols: '', messages: [], ...storedWebsocket },
     id,
     docs,
   };
@@ -502,6 +505,7 @@ export function defaultRequest(
     auth: { type: 'none' },
     body: { mode: 'none', content: '', form: [], formData: [], binaryPath: '' },
     graphql: { query: '', variables: '' },
+    websocket: { url: '', subprotocols: '', messages: [] },
     docs: '',
     scripts: { preRequest: '', postResponse: '' },
   };

From fa02002e015aa82ae8631d212c5f62cf7e1eb7b3 Mon Sep 17 00:00:00 2001
From: Tapiwa Muzira <tapsmuzira@gmail.com>
Date: Thu, 18 Jun 2026 00:16:06 +0200
Subject: [PATCH 7/8] Add Socket.IO request protocol over the live channel
 (driver, namespace-aware connect, editor UI, tests).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 CHANGELOG.md                               |   5 +
 client/src/App.tsx                         |   5 +-
 client/src/components/ConnectionEditor.tsx | 166 ++++++++++++++++-----
 client/src/components/MessageLogPanel.tsx  |  20 ++-
 client/src/components/Sidebar.tsx          |   2 +
 client/src/curl.ts                         |   1 +
 client/src/styles.css                      |  12 ++
 client/src/types.ts                        |  18 ++-
 package-lock.json                          | 128 ++++++++++++++++
 server/package.json                        |   2 +
 server/src/live/handshake.ts               |  61 ++++++++
 server/src/live/socketioDriver.ts          |  95 ++++++++++++
 server/src/live/wsDriver.ts                |  51 +------
 server/src/liveSessions.ts                 |   3 +
 server/src/postmanImport.ts                |   1 +
 server/src/router.ts                       |   2 +-
 server/src/socketio.integration.test.ts    | 137 +++++++++++++++++
 server/src/types.ts                        |  18 ++-
 server/src/workspaceFs.test.ts             |  29 ++++
 server/src/workspaceFs.ts                  |  11 ++
 20 files changed, 675 insertions(+), 92 deletions(-)
 create mode 100644 server/src/live/handshake.ts
 create mode 100644 server/src/live/socketioDriver.ts
 create mode 100644 server/src/socketio.integration.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c8a5245..d0ad521 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,11 @@ See [RELEASING.md](RELEASING.md) for the release process.
   jar apply), with a message log, a composer, and reusable saved messages.
   Backed by a new multiplexed live channel (`/live`) shared by future streaming
   protocols.
+- **Socket.IO requests**: connect to a Socket.IO server (routed through the
+  server like WebSocket, with a configurable handshake path, JSON `auth`
+  payload, query parameters, and an events filter), emit named events with JSON
+  arguments, and watch incoming events in the live log, with reusable saved
+  emits.
 - **Folders** inside collections, nestable to any depth (Postman-style).
   Folders carry their own description and pre-request/test scripts, which run in
   the execution chain (collection → folder(s) → request). Postman imports now
diff --git a/client/src/App.tsx b/client/src/App.tsx
index 6ffd9e0..72c195b 100644
--- a/client/src/App.tsx
+++ b/client/src/App.tsx
@@ -279,11 +279,12 @@ export default function App() {
             { value: 'http', label: 'HTTP' },
             { value: 'graphql', label: 'GraphQL' },
             { value: 'websocket', label: 'WebSocket' },
+            { value: 'socketio', label: 'Socket.IO' },
           ],
         },
       ],
       onSubmit: async (values) => {
-        const allowed: RequestType[] = ['http', 'graphql', 'websocket'];
+        const allowed: RequestType[] = ['http', 'graphql', 'websocket', 'socketio'];
         const type = (allowed as string[]).includes(values.type)
           ? (values.type as RequestType)
           : 'http';
@@ -672,7 +673,7 @@ export default function App() {
       const request = findRequest(collectionId, folderPath, requestId);
       if (collection && request) {
         const key = `${collectionId}/${folderPath.join('/')}/${request.id}`;
-        if (request.type === 'websocket') {
+        if (request.type === 'websocket' || request.type === 'socketio') {
           return (
             <ConnectionEditor
               key={key}
diff --git a/client/src/components/ConnectionEditor.tsx b/client/src/components/ConnectionEditor.tsx
index 6230e0f..5f55f86 100644
--- a/client/src/components/ConnectionEditor.tsx
+++ b/client/src/components/ConnectionEditor.tsx
@@ -44,10 +44,13 @@ export function ConnectionEditor({
   const [status, setStatus] = useState<Status>('idle');
   const [entries, setEntries] = useState<LogEntry[]>([]);
   const [saveError, setSaveError] = useState<string | null>(null);
+  const [eventName, setEventName] = useState('');
   const sessionRef = useRef<LiveSession | null>(null);
 
+  const isIo = draft.type === 'socketio';
   const dirty = JSON.stringify(draft) !== JSON.stringify(saved);
   const connected = status === 'open';
+  const url = isIo ? draft.socketio.url : draft.websocket.url;
 
   useEffect(() => {
     onDirtyChange(dirty);
@@ -67,6 +70,8 @@ export function ConnectionEditor({
     setDraft((d) => ({ ...d, ...changes }));
   const patchWs = (changes: Partial<ApiRequest['websocket']>) =>
     setDraft((d) => ({ ...d, websocket: { ...d.websocket, ...changes } }));
+  const patchIo = (changes: Partial<ApiRequest['socketio']>) =>
+    setDraft((d) => ({ ...d, socketio: { ...d.socketio, ...changes } }));
 
   const log = (e: LogEntry) => setEntries((prev) => [...prev, e]);
 
@@ -84,7 +89,7 @@ export function ConnectionEditor({
   function connect() {
     if (sessionRef.current) return;
     setStatus('connecting');
-    log(entry('system', `Connecting to ${draft.websocket.url}…`));
+    log(entry('system', `Connecting to ${url}…`));
     sessionRef.current = createLiveSession({
       workspaceId,
       collectionId,
@@ -95,8 +100,14 @@ export function ConnectionEditor({
         log(entry('system', 'Connected.'));
       },
       onMessage: (payload) => {
-        const p = payload as { data?: string; binary?: boolean };
-        log(entry('in', p?.binary ? `[binary ${p.data?.length ?? 0}b base64] ${p.data ?? ''}` : p?.data ?? ''));
+        if (isIo) {
+          const p = payload as { event?: string; args?: unknown[] };
+          const args = p?.args ?? [];
+          log(entry('in', `${p?.event ?? ''} ${args.map((a) => JSON.stringify(a)).join(', ')}`.trim()));
+        } else {
+          const p = payload as { data?: string; binary?: boolean };
+          log(entry('in', p?.binary ? `[binary ${p.data?.length ?? 0}b base64] ${p.data ?? ''}` : p?.data ?? ''));
+        }
       },
       onError: (message) => {
         setStatus('error');
@@ -119,8 +130,22 @@ export function ConnectionEditor({
   }
 
   function sendMessage(text: string) {
-    sessionRef.current?.send({ data: text });
-    log(entry('out', text));
+    if (isIo) {
+      const event = eventName.trim();
+      if (!event) return;
+      let args: unknown[];
+      try {
+        const parsed = text.trim() ? JSON.parse(text) : [];
+        args = Array.isArray(parsed) ? parsed : [parsed];
+      } catch {
+        args = [text];
+      }
+      sessionRef.current?.send({ event, args });
+      log(entry('out', `${event} ${text}`.trim()));
+    } else {
+      sessionRef.current?.send({ data: text });
+      log(entry('out', text));
+    }
   }
 
   useEffect(() => {
@@ -134,10 +159,12 @@ export function ConnectionEditor({
     return () => window.removeEventListener('keydown', onKeyDown);
   });
 
+  const savedMessages = isIo ? draft.socketio.emitEvents : draft.websocket.messages;
+
   return (
     <div className="request-editor">
       <div className="editor-title-row">
-        <span className="type-badge type-websocket">WS</span>
+        <span className={`type-badge type-${draft.type}`}>{isIo ? 'IO' : 'WS'}</span>
         <input
           className="name-input"
           value={draft.name}
@@ -161,20 +188,16 @@ export function ConnectionEditor({
         <VarField
           className="url-input"
           wrapClassName="url-wrap"
-          value={draft.websocket.url}
-          placeholder="wss://echo.example.com/socket"
-          onChange={(url) => patchWs({ url })}
+          value={url}
+          placeholder={isIo ? 'wss://socket.example.com/namespace' : 'wss://echo.example.com/socket'}
+          onChange={(value) => (isIo ? patchIo({ url: value }) : patchWs({ url: value }))}
         />
         {connected || status === 'connecting' ? (
           <button className="btn" onClick={disconnect}>
             Disconnect
           </button>
         ) : (
-          <button
-            className="btn btn-primary"
-            onClick={connect}
-            disabled={!draft.websocket.url.trim()}
-          >
+          <button className="btn btn-primary" onClick={connect} disabled={!url.trim()}>
             Connect
           </button>
         )}
@@ -186,7 +209,7 @@ export function ConnectionEditor({
             ['connection', 'Connection'],
             ['headers', 'Headers'],
             ['auth', 'Auth'],
-            ['messages', 'Saved Messages'],
+            ['messages', isIo ? 'Saved Emits' : 'Saved Messages'],
             ['docs', 'Docs'],
           ] as [Tab, string][]
         ).map(([value, label]) => (
@@ -201,21 +224,72 @@ export function ConnectionEditor({
       </div>
 
       <div className="tab-content">
-        {tab === 'connection' && (
-          <div className="kv-editor">
-            <label className="field-label">Subprotocols</label>
-            <VarField
-              className="kv-value"
-              wrapClassName="kv-value"
-              value={draft.websocket.subprotocols}
-              placeholder="comma- or space-separated (optional)"
-              onChange={(subprotocols) => patchWs({ subprotocols })}
-            />
-            <p className="muted">
-              Sent as <code>Sec-WebSocket-Protocol</code> during the handshake.
-            </p>
-          </div>
-        )}
+        {tab === 'connection' &&
+          (isIo ? (
+            <div className="kv-editor">
+              <p className="muted">
+                The path in the URL above is the Socket.IO{' '}
+                <strong>namespace</strong> — e.g.{' '}
+                <code>wss://ws.postman-echo.com/socketio</code> joins the{' '}
+                <code>/socketio</code> namespace.
+              </p>
+              <label className="field-label">Auth payload (JSON)</label>
+              <textarea
+                className="code-area"
+                value={draft.socketio.auth}
+                placeholder='{ "token": "{{token}}" }'
+                spellCheck={false}
+                onChange={(e) => patchIo({ auth: e.target.value })}
+              />
+              <label className="field-label">Query parameters</label>
+              <KeyValueEditor
+                items={draft.socketio.query}
+                onChange={(query) => patchIo({ query })}
+                keyPlaceholder="Param"
+                addLabel="Param"
+              />
+              <label className="field-label">Listen for events</label>
+              <input
+                className="kv-value"
+                value={draft.socketio.listenEvents.join(', ')}
+                placeholder="comma-separated (blank = all events)"
+                onChange={(e) =>
+                  patchIo({
+                    listenEvents: e.target.value.split(/[\s,]+/).filter(Boolean),
+                  })
+                }
+              />
+              <details className="advanced-field">
+                <summary>Advanced</summary>
+                <label className="field-label">Handshake path</label>
+                <VarField
+                  className="kv-value"
+                  wrapClassName="kv-value"
+                  value={draft.socketio.path}
+                  placeholder="/socket.io (default)"
+                  onChange={(path) => patchIo({ path })}
+                />
+                <p className="muted">
+                  The engine.io mount path, not the namespace. Leave blank unless
+                  a server documents a custom one.
+                </p>
+              </details>
+            </div>
+          ) : (
+            <div className="kv-editor">
+              <label className="field-label">Subprotocols</label>
+              <VarField
+                className="kv-value"
+                wrapClassName="kv-value"
+                value={draft.websocket.subprotocols}
+                placeholder="comma- or space-separated (optional)"
+                onChange={(subprotocols) => patchWs({ subprotocols })}
+              />
+              <p className="muted">
+                Sent as <code>Sec-WebSocket-Protocol</code> during the handshake.
+              </p>
+            </div>
+          ))}
 
         {tab === 'headers' && (
           <KeyValueEditor
@@ -232,8 +306,13 @@ export function ConnectionEditor({
 
         {tab === 'messages' && (
           <SavedMessagesEditor
-            messages={draft.websocket.messages}
-            onChange={(messages) => patchWs({ messages })}
+            messages={savedMessages}
+            onChange={(messages) =>
+              isIo ? patchIo({ emitEvents: messages }) : patchWs({ messages })
+            }
+            nameLabel={isIo ? 'Event name' : 'Message name'}
+            contentLabel={isIo ? 'JSON args' : 'Message content'}
+            addLabel={isIo ? 'Add Saved Emit' : 'Add Saved Message'}
           />
         )}
 
@@ -249,10 +328,17 @@ export function ConnectionEditor({
       <MessageLogPanel
         entries={entries}
         connected={connected}
-        savedMessages={draft.websocket.messages}
+        savedMessages={savedMessages}
         onSend={sendMessage}
         onClear={() => setEntries([])}
-        placeholder="Message to send…"
+        sendLabel={isIo ? 'Emit' : 'Send'}
+        placeholder={isIo ? 'JSON args (e.g. ["hello"])' : 'Message to send…'}
+        eventName={
+          isIo
+            ? { value: eventName, onChange: setEventName, placeholder: 'event name' }
+            : undefined
+        }
+        onPickSaved={isIo ? (m) => setEventName(m.name) : undefined}
       />
     </div>
   );
@@ -261,9 +347,15 @@ export function ConnectionEditor({
 function SavedMessagesEditor({
   messages,
   onChange,
+  nameLabel = 'Message name',
+  contentLabel = 'Message content',
+  addLabel = 'Add Saved Message',
 }: {
   messages: SavedMessage[];
   onChange: (messages: SavedMessage[]) => void;
+  nameLabel?: string;
+  contentLabel?: string;
+  addLabel?: string;
 }) {
   const update = (i: number, changes: Partial<SavedMessage>) =>
     onChange(messages.map((m, idx) => (idx === i ? { ...m, ...changes } : m)));
@@ -275,7 +367,7 @@ function SavedMessagesEditor({
             <input
               className="name-input"
               value={m.name}
-              placeholder="Message name"
+              placeholder={nameLabel}
               onChange={(e) => update(i, { name: e.target.value })}
             />
             <button
@@ -288,7 +380,7 @@ function SavedMessagesEditor({
           <textarea
             className="code-area"
             value={m.content}
-            placeholder="Message content"
+            placeholder={contentLabel}
             spellCheck={false}
             onChange={(e) => update(i, { content: e.target.value })}
           />
@@ -298,7 +390,7 @@ function SavedMessagesEditor({
         className="btn btn-sm"
         onClick={() => onChange([...messages, { name: `Message ${messages.length + 1}`, content: '' }])}
       >
-        Add Saved Message
+        {addLabel}
       </button>
     </div>
   );
diff --git a/client/src/components/MessageLogPanel.tsx b/client/src/components/MessageLogPanel.tsx
index 2f3a733..8036521 100644
--- a/client/src/components/MessageLogPanel.tsx
+++ b/client/src/components/MessageLogPanel.tsx
@@ -18,6 +18,10 @@ interface Props {
   sendLabel?: string;
   /** Placeholder for the composer textarea. */
   placeholder?: string;
+  /** Optional event-name field shown before the textarea (Socket.IO). */
+  eventName?: { value: string; onChange: (value: string) => void; placeholder?: string };
+  /** Called when a saved message is picked, in addition to filling the textarea. */
+  onPickSaved?: (message: SavedMessage) => void;
 }
 
 function arrow(dir: LogEntry['dir']): string {
@@ -34,6 +38,8 @@ export function MessageLogPanel({
   onClear,
   sendLabel = 'Send',
   placeholder = 'Message to send…',
+  eventName,
+  onPickSaved,
 }: Props) {
   const [text, setText] = useState('');
   const logRef = useRef<HTMLDivElement>(null);
@@ -85,6 +91,15 @@ export function MessageLogPanel({
       </div>
 
       <div className="message-composer">
+        {eventName && (
+          <input
+            className="event-name-input"
+            value={eventName.value}
+            placeholder={eventName.placeholder ?? 'event name'}
+            disabled={!connected}
+            onChange={(e) => eventName.onChange(e.target.value)}
+          />
+        )}
         <textarea
           className="code-area"
           value={text}
@@ -106,7 +121,10 @@ export function MessageLogPanel({
               value=""
               onChange={(e) => {
                 const m = savedMessages.find((s) => s.name === e.target.value);
-                if (m) setText(m.content);
+                if (m) {
+                  setText(m.content);
+                  onPickSaved?.(m);
+                }
               }}
             >
               <option value="">Saved messages…</option>
diff --git a/client/src/components/Sidebar.tsx b/client/src/components/Sidebar.tsx
index c42bb0b..e1e15e5 100644
--- a/client/src/components/Sidebar.tsx
+++ b/client/src/components/Sidebar.tsx
@@ -69,12 +69,14 @@ const pathKey = (collectionId: string, folderPath: string[]): string =>
 function badgeLabel(request: ApiRequest): string {
   if (request.type === 'graphql') return 'GQL';
   if (request.type === 'websocket') return 'WS';
+  if (request.type === 'socketio') return 'IO';
   return request.method;
 }
 
 function badgeClass(request: ApiRequest): string {
   if (request.type === 'graphql') return 'method-GQL';
   if (request.type === 'websocket') return 'method-WS';
+  if (request.type === 'socketio') return 'method-IO';
   return `method-${request.method}`;
 }
 
diff --git a/client/src/curl.ts b/client/src/curl.ts
index ae019d4..849eef7 100644
--- a/client/src/curl.ts
+++ b/client/src/curl.ts
@@ -294,6 +294,7 @@ export function parseCurl(command: string): Omit<ApiRequest, 'id'> {
     body: { mode, content, form, formData, binaryPath },
     graphql: { query: '', variables: '' },
     websocket: { url: '', subprotocols: '', messages: [] },
+    socketio: { url: '', path: '', auth: '', query: [], emitEvents: [], listenEvents: [] },
     docs: '',
     scripts: { preRequest: '', postResponse: '' },
   };
diff --git a/client/src/styles.css b/client/src/styles.css
index a3a50eb..287b2e2 100644
--- a/client/src/styles.css
+++ b/client/src/styles.css
@@ -216,6 +216,7 @@ pre,
 .method-OPTIONS { color: var(--text-muted); }
 .method-GQL { color: var(--pink); }
 .method-WS { color: var(--blue); }
+.method-IO { color: var(--green); }
 
 /* ---------- main pane ---------- */
 
@@ -296,6 +297,7 @@ pre,
 .type-collection { background: #3b3324; color: var(--yellow); }
 .type-folder { background: #2a3340; color: var(--blue); }
 .type-websocket { background: #24323b; color: var(--blue); }
+.type-socketio { background: #243b2c; color: var(--green); }
 
 /* ----- live connection (WebSocket/Socket.IO/MCP) ----- */
 .conn-status {
@@ -351,6 +353,16 @@ pre,
   border-top: 1px solid var(--border);
 }
 .message-composer .code-area { flex: 1; min-height: 56px; }
+.event-name-input { align-self: flex-start; width: 140px; }
+
+.advanced-field { margin-top: 4px; }
+.advanced-field > summary {
+  cursor: pointer;
+  color: var(--text-muted);
+  font-size: 0.85em;
+  user-select: none;
+  width: fit-content;
+}
 .composer-actions {
   display: flex;
   flex-direction: column;
diff --git a/client/src/types.ts b/client/src/types.ts
index 14c57cc..95bfdb4 100644
--- a/client/src/types.ts
+++ b/client/src/types.ts
@@ -1,4 +1,4 @@
-export type RequestType = 'http' | 'graphql' | 'websocket';
+export type RequestType = 'http' | 'graphql' | 'websocket' | 'socketio';
 
 export type HttpMethod =
   | 'GET'
@@ -76,6 +76,21 @@ export interface WebSocketConfig {
   messages: SavedMessage[];
 }
 
+/** Socket.IO connection config (handshake reuses the request's headers + auth). */
+export interface SocketIOConfig {
+  url: string;
+  /** Custom handshake path; blank uses the Socket.IO default (/socket.io). */
+  path: string;
+  /** JSON object sent as the connection `auth` payload (blank for none). */
+  auth: string;
+  /** Handshake query parameters. */
+  query: KeyValue[];
+  /** Reusable emit templates: `name` is the event, `content` is JSON args. */
+  emitEvents: SavedMessage[];
+  /** Event names to listen for; empty means listen to every event. */
+  listenEvents: string[];
+}
+
 /** Postman-style automation scripts (JavaScript using the `pm` API). */
 export interface Scripts {
   preRequest: string;
@@ -94,6 +109,7 @@ export interface ApiRequest {
   body: RequestBody;
   graphql: GraphQLBody;
   websocket: WebSocketConfig;
+  socketio: SocketIOConfig;
   docs: string;
   scripts: Scripts;
 }
diff --git a/package-lock.json b/package-lock.json
index 39257f7..c4f0bad 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1955,6 +1955,12 @@
         "win32"
       ]
     },
+    "node_modules/@socket.io/component-emitter": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/@socket.io/component-emitter/-/component-emitter-3.1.2.tgz",
+      "integrity": "sha512-9BCxFwvbGg/RsZK9tjXd8s4UcwR0MWeFQ1XEKIQVVvAGJyINdrqKMcTRyLoK8Rse1GjzLV9cwjWV1olXRWEXVA==",
+      "license": "MIT"
+    },
     "node_modules/@standard-schema/spec": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/@standard-schema/spec/-/spec-1.1.0.tgz",
@@ -3058,6 +3064,16 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/base64id": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/base64id/-/base64id-2.0.0.tgz",
+      "integrity": "sha512-lGe34o6EHj9y3Kts9R4ZYs/Gr+6N7MCaMlIFA3F1R2O5/m7K06AxfSeO5530PEERE6/WyEg3lsuyw4GHlPZHog==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^4.5.0 || >= 5.9"
+      }
+    },
     "node_modules/baseline-browser-mapping": {
       "version": "2.10.35",
       "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.35.tgz",
@@ -3628,6 +3644,50 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/engine.io": {
+      "version": "6.6.9",
+      "resolved": "https://registry.npmjs.org/engine.io/-/engine.io-6.6.9.tgz",
+      "integrity": "sha512-clKkw4C7nJ22mGgoVcCg6V/W/TxdNyIOTr89k2ONZu81qqkddPFDF0LXcbAwhzPD8DjkiRCjzuiO6Y+fkpD4vg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/cors": "^2.8.12",
+        "@types/node": ">=10.0.0",
+        "@types/ws": "^8.5.12",
+        "accepts": "~1.3.4",
+        "base64id": "2.0.0",
+        "cookie": "~0.7.2",
+        "cors": "~2.8.5",
+        "debug": "~4.4.1",
+        "engine.io-parser": "~5.2.1",
+        "ws": "~8.21.0"
+      },
+      "engines": {
+        "node": ">=10.2.0"
+      }
+    },
+    "node_modules/engine.io-client": {
+      "version": "6.6.6",
+      "resolved": "https://registry.npmjs.org/engine.io-client/-/engine.io-client-6.6.6.tgz",
+      "integrity": "sha512-iY6QdftLQ9pyiPoX082bpf/u1UewnOaJrtJIF9T0++QB34lZrj0uP+Q/bj8AlUsAxqhnkTV2BS8SBZSxOmoV5Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@socket.io/component-emitter": "~3.1.0",
+        "debug": "~4.4.1",
+        "engine.io-parser": "~5.2.1",
+        "ws": "~8.21.0",
+        "xmlhttprequest-ssl": "~2.1.1"
+      }
+    },
+    "node_modules/engine.io-parser": {
+      "version": "5.2.3",
+      "resolved": "https://registry.npmjs.org/engine.io-parser/-/engine.io-parser-5.2.3.tgz",
+      "integrity": "sha512-HqD3yTBfnBxIrbnM1DoD6Pcq8NECnh8d4As1Qgh0z5Gg3jRRIqijury0CL3ghu/edArpUYiYqQiDUQBIs4np3Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      }
+    },
     "node_modules/entities": {
       "version": "4.5.0",
       "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz",
@@ -6740,6 +6800,64 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/socket.io": {
+      "version": "4.8.3",
+      "resolved": "https://registry.npmjs.org/socket.io/-/socket.io-4.8.3.tgz",
+      "integrity": "sha512-2Dd78bqzzjE6KPkD5fHZmDAKRNe3J15q+YHDrIsy9WEkqttc7GY+kT9OBLSMaPbQaEd0x1BjcmtMtXkfpc+T5A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "accepts": "~1.3.4",
+        "base64id": "~2.0.0",
+        "cors": "~2.8.5",
+        "debug": "~4.4.1",
+        "engine.io": "~6.6.0",
+        "socket.io-adapter": "~2.5.2",
+        "socket.io-parser": "~4.2.4"
+      },
+      "engines": {
+        "node": ">=10.2.0"
+      }
+    },
+    "node_modules/socket.io-adapter": {
+      "version": "2.5.8",
+      "resolved": "https://registry.npmjs.org/socket.io-adapter/-/socket.io-adapter-2.5.8.tgz",
+      "integrity": "sha512-6Oy52pbg+kvdCVvjcN+FnY7BvxZ7cIHNScbvztT/It5d0vbwoJoVZmF2gjJmnV0/4WlXRfG15zc45ySk9Ah8bw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "debug": "~4.4.1",
+        "ws": "~8.21.0"
+      }
+    },
+    "node_modules/socket.io-client": {
+      "version": "4.8.3",
+      "resolved": "https://registry.npmjs.org/socket.io-client/-/socket.io-client-4.8.3.tgz",
+      "integrity": "sha512-uP0bpjWrjQmUt5DTHq9RuoCBdFJF10cdX9X+a368j/Ft0wmaVgxlrjvK3kjvgCODOMMOz9lcaRzxmso0bTWZ/g==",
+      "license": "MIT",
+      "dependencies": {
+        "@socket.io/component-emitter": "~3.1.0",
+        "debug": "~4.4.1",
+        "engine.io-client": "~6.6.1",
+        "socket.io-parser": "~4.2.4"
+      },
+      "engines": {
+        "node": ">=10.0.0"
+      }
+    },
+    "node_modules/socket.io-parser": {
+      "version": "4.2.6",
+      "resolved": "https://registry.npmjs.org/socket.io-parser/-/socket.io-parser-4.2.6.tgz",
+      "integrity": "sha512-asJqbVBDsBCJx0pTqw3WfesSY0iRX+2xzWEWzrpcH7L6fLzrhyF8WPI8UaeM4YCuDfpwA/cgsdugMsmtz8EJeg==",
+      "license": "MIT",
+      "dependencies": {
+        "@socket.io/component-emitter": "~3.1.0",
+        "debug": "~4.4.1"
+      },
+      "engines": {
+        "node": ">=10.0.0"
+      }
+    },
     "node_modules/source-map-js": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
@@ -8095,6 +8213,14 @@
         }
       }
     },
+    "node_modules/xmlhttprequest-ssl": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/xmlhttprequest-ssl/-/xmlhttprequest-ssl-2.1.2.tgz",
+      "integrity": "sha512-TEU+nJVUUnA4CYJFLvK5X9AOeH4KvDvhIfm0vV1GaQRtchnG0hgK5p8hw/xjv8cunWYCsiPCSDzObPyhEwq3KQ==",
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
     "node_modules/y18n": {
       "version": "5.0.8",
       "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz",
@@ -8177,6 +8303,7 @@
         "@types/ws": "^8.18.1",
         "cors": "^2.8.5",
         "express": "^4.21.2",
+        "socket.io-client": "^4.8.3",
         "tough-cookie": "^6.0.1",
         "ws": "^8.21.0",
         "zod": "^4.4.3"
@@ -8186,6 +8313,7 @@
         "@types/express": "^4.17.21",
         "@types/node": "^22.10.0",
         "@types/supertest": "^7.2.0",
+        "socket.io": "^4.8.3",
         "supertest": "^7.2.2",
         "tsx": "^4.19.2",
         "typescript": "^5.7.2",
diff --git a/server/package.json b/server/package.json
index d71a54d..98a936d 100644
--- a/server/package.json
+++ b/server/package.json
@@ -16,6 +16,7 @@
     "@types/ws": "^8.18.1",
     "cors": "^2.8.5",
     "express": "^4.21.2",
+    "socket.io-client": "^4.8.3",
     "tough-cookie": "^6.0.1",
     "ws": "^8.21.0",
     "zod": "^4.4.3"
@@ -25,6 +26,7 @@
     "@types/express": "^4.17.21",
     "@types/node": "^22.10.0",
     "@types/supertest": "^7.2.0",
+    "socket.io": "^4.8.3",
     "supertest": "^7.2.2",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
diff --git a/server/src/live/handshake.ts b/server/src/live/handshake.ts
new file mode 100644
index 0000000..909be47
--- /dev/null
+++ b/server/src/live/handshake.ts
@@ -0,0 +1,61 @@
+import type { CookieJar } from 'tough-cookie';
+import { interpolate } from '../execute.js';
+import type { AuthConfig } from '../types.js';
+import type { DriverContext } from './driver.js';
+
+/**
+ * Applies the request's auth to outbound handshake headers (and, for an
+ * apiKey placed in the query, to the URL). Shared by the live drivers so
+ * WebSocket and Socket.IO connections authenticate like HTTP requests.
+ */
+export function applyAuth(
+  headers: Record<string, string>,
+  url: URL,
+  auth: AuthConfig,
+  vars: Record<string, string>
+): void {
+  switch (auth.type) {
+    case 'bearer':
+      headers['authorization'] = `Bearer ${interpolate(auth.bearer?.token ?? '', vars)}`;
+      break;
+    case 'basic': {
+      const user = interpolate(auth.basic?.username ?? '', vars);
+      const pass = interpolate(auth.basic?.password ?? '', vars);
+      headers['authorization'] = `Basic ${Buffer.from(`${user}:${pass}`).toString('base64')}`;
+      break;
+    }
+    case 'apiKey': {
+      const key = interpolate(auth.apiKey?.key ?? '', vars);
+      const value = interpolate(auth.apiKey?.value ?? '', vars);
+      if (key) {
+        if (auth.apiKey?.placement === 'query') url.searchParams.append(key, value);
+        else headers[key] = value;
+      }
+      break;
+    }
+  }
+}
+
+/** Looks up the workspace jar's Cookie header for a (ws/http) URL. */
+export function cookieHeader(jar: CookieJar, url: URL): string {
+  try {
+    // Map ws→http so the jar matches; a no-op for http(s) URLs.
+    const httpUrl = url.toString().replace(/^ws/, 'http');
+    return jar.getCookieStringSync(httpUrl);
+  } catch {
+    return '';
+  }
+}
+
+/** Builds handshake headers: interpolated request headers + auth + cookies. */
+export function buildHandshakeHeaders(ctx: DriverContext, url: URL): Record<string, string> {
+  const { request, vars, jar } = ctx;
+  const headers: Record<string, string> = {};
+  for (const h of request.headers) {
+    if (h.enabled && h.key) headers[interpolate(h.key, vars)] = interpolate(h.value, vars);
+  }
+  applyAuth(headers, url, request.auth, vars);
+  const cookie = cookieHeader(jar, url);
+  if (cookie) headers['cookie'] = cookie;
+  return headers;
+}
diff --git a/server/src/live/socketioDriver.ts b/server/src/live/socketioDriver.ts
new file mode 100644
index 0000000..3133044
--- /dev/null
+++ b/server/src/live/socketioDriver.ts
@@ -0,0 +1,95 @@
+import { io, type Socket } from 'socket.io-client';
+import { interpolate } from '../execute.js';
+import { buildHandshakeHeaders } from './handshake.js';
+import type { DriverContext, LiveDriver } from './driver.js';
+
+/** Parses the optional JSON `auth` payload; throws with a clear message. */
+function parseAuth(raw: string): Record<string, unknown> | undefined {
+  const text = raw.trim();
+  if (!text) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error('Socket.IO auth must be a JSON object');
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('Socket.IO auth must be a JSON object');
+  }
+  return parsed as Record<string, unknown>;
+}
+
+export function createSocketioDriver(ctx: DriverContext): LiveDriver {
+  let socket: Socket | null = null;
+
+  return {
+    open() {
+      const cfg = ctx.request.socketio;
+      const raw = interpolate(cfg.url, ctx.vars).trim();
+      let url: URL;
+      try {
+        url = new URL(raw);
+      } catch {
+        throw new Error(`Invalid Socket.IO URL: "${raw}"`);
+      }
+      if (!/^https?:|^wss?:/.test(url.protocol)) {
+        throw new Error('Socket.IO URL must start with http(s):// or ws(s)://');
+      }
+
+      const query: Record<string, string> = {};
+      for (const q of cfg.query) {
+        if (q.enabled && q.key) {
+          query[interpolate(q.key, ctx.vars)] = interpolate(q.value, ctx.vars);
+        }
+      }
+      const path = interpolate(cfg.path, ctx.vars).trim();
+      const headers = buildHandshakeHeaders(ctx, url);
+      const auth = parseAuth(interpolate(cfg.auth, ctx.vars));
+
+      // Keep the URL pathname: Socket.IO reads it as the namespace (e.g.
+      // /socketio). The engine.io mount point is the separate `path` option.
+      const target = url.origin + url.pathname;
+      socket = io(target, {
+        path: path || undefined,
+        transports: ['websocket'],
+        reconnection: false,
+        forceNew: true,
+        auth,
+        query,
+        extraHeaders: headers,
+      });
+
+      socket.on('connect', () => ctx.emit('open', { id: socket?.id }));
+      socket.on('connect_error', (err: Error) => ctx.emit('error', err.message));
+      socket.on('disconnect', (reason: string) => ctx.emit('closed', { reason }));
+
+      const onEvent = (event: string, args: unknown[]) =>
+        ctx.emit('message', { event, args });
+      const listen = cfg.listenEvents.map((e) => e.trim()).filter(Boolean);
+      if (listen.length > 0) {
+        // Filtered mode: only the named events.
+        for (const name of listen) socket.on(name, (...args: unknown[]) => onEvent(name, args));
+      } else {
+        // Catch-all: every inbound event.
+        socket.onAny((event: string, ...args: unknown[]) => onEvent(event, args));
+      }
+    },
+
+    send(payload: unknown) {
+      const p = (payload as { event?: string; args?: unknown[] } | null) ?? {};
+      const event = p.event?.trim();
+      if (!socket || !event) return;
+      const args = Array.isArray(p.args) ? p.args : p.args === undefined ? [] : [p.args];
+      socket.emit(event, ...args);
+    },
+
+    close() {
+      try {
+        socket?.disconnect();
+      } catch {
+        // best-effort teardown
+      }
+      socket = null;
+    },
+  };
+}
diff --git a/server/src/live/wsDriver.ts b/server/src/live/wsDriver.ts
index 1fc4f0a..c807d2a 100644
--- a/server/src/live/wsDriver.ts
+++ b/server/src/live/wsDriver.ts
@@ -1,55 +1,8 @@
 import WebSocket from 'ws';
 import { interpolate } from '../execute.js';
-import type { AuthConfig } from '../types.js';
+import { buildHandshakeHeaders } from './handshake.js';
 import type { DriverContext, LiveDriver } from './driver.js';
 
-/** Builds the handshake headers (interpolated request headers + auth + cookies). */
-function buildHeaders(ctx: DriverContext, url: URL): Record<string, string> {
-  const { request, vars, jar } = ctx;
-  const headers: Record<string, string> = {};
-  for (const h of request.headers) {
-    if (h.enabled && h.key) headers[interpolate(h.key, vars)] = interpolate(h.value, vars);
-  }
-  applyAuth(headers, url, request.auth, vars);
-  // Reuse the workspace jar for the handshake (map ws→http for matching).
-  try {
-    const httpUrl = url.toString().replace(/^ws/, 'http');
-    const cookie = jar.getCookieStringSync(httpUrl);
-    if (cookie) headers['cookie'] = cookie;
-  } catch {
-    // No cookies for this URL.
-  }
-  return headers;
-}
-
-function applyAuth(
-  headers: Record<string, string>,
-  url: URL,
-  auth: AuthConfig,
-  vars: Record<string, string>
-): void {
-  switch (auth.type) {
-    case 'bearer':
-      headers['authorization'] = `Bearer ${interpolate(auth.bearer?.token ?? '', vars)}`;
-      break;
-    case 'basic': {
-      const user = interpolate(auth.basic?.username ?? '', vars);
-      const pass = interpolate(auth.basic?.password ?? '', vars);
-      headers['authorization'] = `Basic ${Buffer.from(`${user}:${pass}`).toString('base64')}`;
-      break;
-    }
-    case 'apiKey': {
-      const key = interpolate(auth.apiKey?.key ?? '', vars);
-      const value = interpolate(auth.apiKey?.value ?? '', vars);
-      if (key) {
-        if (auth.apiKey?.placement === 'query') url.searchParams.append(key, value);
-        else headers[key] = value;
-      }
-      break;
-    }
-  }
-}
-
 export function createWsDriver(ctx: DriverContext): LiveDriver {
   let socket: WebSocket | null = null;
 
@@ -65,7 +18,7 @@ export function createWsDriver(ctx: DriverContext): LiveDriver {
       if (url.protocol !== 'ws:' && url.protocol !== 'wss:') {
         throw new Error('WebSocket URL must start with ws:// or wss://');
       }
-      const headers = buildHeaders(ctx, url);
+      const headers = buildHandshakeHeaders(ctx, url);
       const protocols = ctx.request.websocket.subprotocols
         .split(/[\s,]+/)
         .filter(Boolean);
diff --git a/server/src/liveSessions.ts b/server/src/liveSessions.ts
index a3cda38..54d2795 100644
--- a/server/src/liveSessions.ts
+++ b/server/src/liveSessions.ts
@@ -7,6 +7,7 @@ import * as wsfs from './workspaceFs.js';
 import type { ApiRequest } from './types.js';
 import type { DriverContext, Emit, LiveDriver } from './live/driver.js';
 import { createWsDriver } from './live/wsDriver.js';
+import { createSocketioDriver } from './live/socketioDriver.js';
 
 /**
  * The live channel: a single browser WebSocket (at /live) multiplexes many
@@ -54,6 +55,8 @@ function driverFor(type: ApiRequest['type'], ctx: DriverContext): LiveDriver {
   switch (type) {
     case 'websocket':
       return createWsDriver(ctx);
+    case 'socketio':
+      return createSocketioDriver(ctx);
     default:
       throw new Error(`Protocol "${type}" is not supported on the live channel`);
   }
diff --git a/server/src/postmanImport.ts b/server/src/postmanImport.ts
index 0336c79..209deec 100644
--- a/server/src/postmanImport.ts
+++ b/server/src/postmanImport.ts
@@ -285,6 +285,7 @@ function convertRequest(item: PostmanItem): ConvertedRequest {
     body,
     graphql,
     websocket: { url: '', subprotocols: '', messages: [] },
+    socketio: { url: '', path: '', auth: '', query: [], emitEvents: [], listenEvents: [] },
     docs: describe(req.description),
     scripts: eventsToScripts(item.event),
   };
diff --git a/server/src/router.ts b/server/src/router.ts
index 202958f..50ed005 100644
--- a/server/src/router.ts
+++ b/server/src/router.ts
@@ -190,7 +190,7 @@ router.post(
   wrap((req, res) => {
     const ws = getWorkspace(req.params.id);
     const name = requireString(req.body.name, 'name');
-    const allowed = ['http', 'graphql', 'websocket'] as const;
+    const allowed = ['http', 'graphql', 'websocket', 'socketio'] as const;
     const type = allowed.includes(req.body.type) ? req.body.type : 'http';
     const folderPath = parseFolderPath(req.body.folderPath);
     res
diff --git a/server/src/socketio.integration.test.ts b/server/src/socketio.integration.test.ts
new file mode 100644
index 0000000..838536f
--- /dev/null
+++ b/server/src/socketio.integration.test.ts
@@ -0,0 +1,137 @@
+import http from 'node:http';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { WebSocket } from 'ws';
+import { Server as IOServer } from 'socket.io';
+import type { ApiRequest } from './types.js';
+
+// Redirect app-local state (~/.apinotebook) to a temp home before importing the
+// modules (appData/cookies compute their dirs at module load).
+let tmpHome: string;
+let wsDir: string;
+let appServer: http.Server;
+let liveUrl: string;
+let echoHttp: http.Server;
+let echo: IOServer;
+let echoUrl: string;
+let wsId: string;
+let makeRequest: (over: Partial<ApiRequest>) => ApiRequest;
+
+function listening(server: http.Server): Promise<void> {
+  return new Promise((r) => server.listen(0, '127.0.0.1', () => r()));
+}
+function portOf(server: { address(): unknown }): number {
+  const addr = server.address();
+  return typeof addr === 'object' && addr ? (addr as { port: number }).port : 0;
+}
+
+beforeAll(async () => {
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'apinb-home-'));
+  wsDir = fs.mkdtempSync(path.join(os.tmpdir(), 'apinb-wsdir-'));
+  vi.spyOn(os, 'homedir').mockReturnValue(tmpHome);
+  vi.resetModules();
+
+  const wsfs = await import('./workspaceFs.js');
+  const appData = await import('./appData.js');
+  const { attachLiveSessions } = await import('./liveSessions.js');
+
+  const meta = wsfs.createWorkspace('Live IO', wsDir);
+  appData.addWorkspaceEntry({ id: meta.id, path: meta.path });
+  wsId = meta.id;
+  makeRequest = (over) => ({ ...wsfs.defaultRequest('r', 'r', 'socketio'), ...over });
+
+  // In-test Socket.IO echo server (the "target"). Only the /chat namespace
+  // echoes — the default namespace stays silent — so the test fails unless the
+  // driver preserves the URL pathname as the namespace.
+  echoHttp = http.createServer();
+  echo = new IOServer(echoHttp);
+  echo.of('/chat').on('connection', (socket) => {
+    socket.onAny((event: string, ...args: unknown[]) => socket.emit(event, ...args));
+  });
+  await listening(echoHttp);
+  echoUrl = `http://127.0.0.1:${portOf(echoHttp)}/chat`;
+
+  // Our server with the live channel attached.
+  appServer = http.createServer();
+  attachLiveSessions(appServer);
+  await listening(appServer);
+  liveUrl = `ws://127.0.0.1:${portOf(appServer)}/live`;
+});
+
+afterAll(async () => {
+  vi.restoreAllMocks();
+  await echo.close();
+  await new Promise<void>((r) => echoHttp.close(() => r()));
+  await new Promise<void>((r) => appServer.close(() => r()));
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+  fs.rmSync(wsDir, { recursive: true, force: true });
+});
+
+interface Frame {
+  t: string;
+  sessionId: string;
+  payload?: { event?: string; args?: unknown[]; message?: string };
+}
+
+describe('live channel — Socket.IO', () => {
+  it('connects, emits an event, and echoes it back', async () => {
+    const client = new WebSocket(liveUrl);
+    await new Promise<void>((r) => client.once('open', () => r()));
+
+    const nextFrame = (pred: (f: Frame) => boolean): Promise<Frame> =>
+      new Promise((resolve) => {
+        const onMsg = (d: WebSocket.RawData) => {
+          const f = JSON.parse(d.toString()) as Frame;
+          if (pred(f)) {
+            client.off('message', onMsg);
+            resolve(f);
+          }
+        };
+        client.on('message', onMsg);
+      });
+
+    const request = makeRequest({
+      socketio: { url: echoUrl, path: '', auth: '', query: [], emitEvents: [], listenEvents: [] },
+    });
+    client.send(
+      JSON.stringify({ t: 'connect', sessionId: 'S1', workspaceId: wsId, request })
+    );
+    const opened = await nextFrame((f) => f.t === 'open' && f.sessionId === 'S1');
+    expect(opened.t).toBe('open');
+
+    client.send(
+      JSON.stringify({ t: 'send', sessionId: 'S1', payload: { event: 'chat', args: ['hello'] } })
+    );
+    const msg = await nextFrame((f) => f.t === 'message' && f.sessionId === 'S1');
+    expect(msg.payload?.event).toBe('chat');
+    expect(msg.payload?.args).toEqual(['hello']);
+
+    client.send(JSON.stringify({ t: 'close', sessionId: 'S1' }));
+    const closed = await nextFrame((f) => f.t === 'closed' && f.sessionId === 'S1');
+    expect(closed.t).toBe('closed');
+
+    client.close();
+  });
+
+  it('reports an error for an invalid target URL', async () => {
+    const client = new WebSocket(liveUrl);
+    await new Promise<void>((r) => client.once('open', () => r()));
+    const request = makeRequest({
+      socketio: { url: 'ftp://nope/', path: '', auth: '', query: [], emitEvents: [], listenEvents: [] },
+    });
+    const errored = new Promise<Frame>((resolve) => {
+      client.on('message', (d) => {
+        const f = JSON.parse(d.toString()) as Frame;
+        if (f.t === 'error' && f.sessionId === 'S2') resolve(f);
+      });
+    });
+    client.send(
+      JSON.stringify({ t: 'connect', sessionId: 'S2', workspaceId: wsId, request })
+    );
+    const f = await errored;
+    expect(f.payload?.message).toMatch(/Socket\.IO URL/);
+    client.close();
+  });
+});
diff --git a/server/src/types.ts b/server/src/types.ts
index 689be87..5901410 100644
--- a/server/src/types.ts
+++ b/server/src/types.ts
@@ -1,4 +1,4 @@
-export type RequestType = 'http' | 'graphql' | 'websocket';
+export type RequestType = 'http' | 'graphql' | 'websocket' | 'socketio';
 
 export type HttpMethod =
   | 'GET'
@@ -66,6 +66,21 @@ export interface WebSocketConfig {
   messages: SavedMessage[];
 }
 
+/** Socket.IO connection config (handshake reuses the request's headers + auth). */
+export interface SocketIOConfig {
+  url: string;
+  /** Custom handshake path; blank uses the Socket.IO default (/socket.io). */
+  path: string;
+  /** JSON object sent as the connection `auth` payload (blank for none). */
+  auth: string;
+  /** Handshake query parameters. */
+  query: KeyValue[];
+  /** Reusable emit templates: `name` is the event, `content` is JSON args. */
+  emitEvents: SavedMessage[];
+  /** Event names to listen for; empty means listen to every event. */
+  listenEvents: string[];
+}
+
 /** Postman-style automation scripts (JavaScript using the `pm` API). */
 export interface Scripts {
   preRequest: string;
@@ -84,6 +99,7 @@ export interface ApiRequest {
   body: RequestBody;
   graphql: GraphQLBody;
   websocket: WebSocketConfig;
+  socketio: SocketIOConfig;
   docs: string;
   scripts: Scripts;
 }
diff --git a/server/src/workspaceFs.test.ts b/server/src/workspaceFs.test.ts
index a8f8145..b12bd83 100644
--- a/server/src/workspaceFs.test.ts
+++ b/server/src/workspaceFs.test.ts
@@ -134,6 +134,35 @@ describe('collections & requests (round-trip)', () => {
     expect(read.websocket.messages).toEqual([{ name: 'ping', content: '{"op":"ping"}' }]);
   });
 
+  it('persists a socketio request with its config and saved emits', () => {
+    const col = wsfs.createCollection(ws, 'IO');
+    const created = wsfs.createRequest(ws, col.id, [], 'Live', 'socketio');
+    expect(created.socketio).toEqual({
+      url: '',
+      path: '',
+      auth: '',
+      query: [],
+      emitEvents: [],
+      listenEvents: [],
+    });
+    wsfs.updateRequest(ws, col.id, [], created.id, {
+      ...created,
+      socketio: {
+        url: 'https://x',
+        path: '/ws',
+        auth: '{"token":"t"}',
+        query: [{ key: 'room', value: 'lobby', enabled: true }],
+        emitEvents: [{ name: 'chat', content: '["hi"]' }],
+        listenEvents: ['chat', 'pong'],
+      },
+    });
+    const read = wsfs.getRequest(ws, col.id, [], created.id);
+    expect(read.type).toBe('socketio');
+    expect(read.socketio.url).toBe('https://x');
+    expect(read.socketio.emitEvents).toEqual([{ name: 'chat', content: '["hi"]' }]);
+    expect(read.socketio.listenEvents).toEqual(['chat', 'pong']);
+  });
+
   it('back-fills missing fields and reads a legacy requests/ subdir', () => {
     const col = wsfs.createCollection(ws, 'Old');
     // Pre-folders workspaces stored requests in a legacy requests/ subdir.
diff --git a/server/src/workspaceFs.ts b/server/src/workspaceFs.ts
index d05ed37..33c7867 100644
--- a/server/src/workspaceFs.ts
+++ b/server/src/workspaceFs.ts
@@ -234,6 +234,7 @@ function readRequest(
   const storedScripts: Partial<ApiRequest['scripts']> = stored.scripts ?? {};
   const storedGraphql: Partial<ApiRequest['graphql']> = stored.graphql ?? {};
   const storedWebsocket: Partial<ApiRequest['websocket']> = stored.websocket ?? {};
+  const storedSocketio: Partial<ApiRequest['socketio']> = stored.socketio ?? {};
   return {
     ...stored,
     body: {
@@ -247,6 +248,15 @@ function readRequest(
     scripts: { preRequest: '', postResponse: '', ...storedScripts },
     graphql: { query: '', variables: '', ...storedGraphql },
     websocket: { url: '', subprotocols: '', messages: [], ...storedWebsocket },
+    socketio: {
+      url: '',
+      path: '',
+      auth: '',
+      query: [],
+      emitEvents: [],
+      listenEvents: [],
+      ...storedSocketio,
+    },
     id,
     docs,
   };
@@ -506,6 +516,7 @@ export function defaultRequest(
     body: { mode: 'none', content: '', form: [], formData: [], binaryPath: '' },
     graphql: { query: '', variables: '' },
     websocket: { url: '', subprotocols: '', messages: [] },
+    socketio: { url: '', path: '', auth: '', query: [], emitEvents: [], listenEvents: [] },
     docs: '',
     scripts: { preRequest: '', postResponse: '' },
   };

From 9461faba0c4c6c410936ff8b38e6e027d366a5ec Mon Sep 17 00:00:00 2001
From: Tapiwa Muzira <tapsmuzira@gmail.com>
Date: Thu, 18 Jun 2026 00:22:55 +0200
Subject: [PATCH 8/8] Add MCP (HTTP) request protocol: client driver over the
 live channel, tool browser with JSON-Schema arg form, tests.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 CHANGELOG.md                              |   4 +
 client/src/App.tsx                        |  20 +-
 client/src/components/JsonSchemaForm.tsx  | 194 +++++++++++++
 client/src/components/McpEditor.tsx       | 328 ++++++++++++++++++++++
 client/src/components/Sidebar.tsx         |   2 +
 client/src/curl.ts                        |   1 +
 client/src/styles.css                     |  47 ++++
 client/src/types.ts                       |   8 +-
 server/src/live/mcpDriver.ts              |  86 ++++++
 server/src/liveSessions.ts                |   3 +
 server/src/mcp-client.integration.test.ts | 167 +++++++++++
 server/src/postmanImport.ts               |   1 +
 server/src/router.ts                      |   2 +-
 server/src/types.ts                       |   8 +-
 server/src/workspaceFs.test.ts            |  13 +
 server/src/workspaceFs.ts                 |   3 +
 16 files changed, 883 insertions(+), 4 deletions(-)
 create mode 100644 client/src/components/JsonSchemaForm.tsx
 create mode 100644 client/src/components/McpEditor.tsx
 create mode 100644 server/src/live/mcpDriver.ts
 create mode 100644 server/src/mcp-client.integration.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d0ad521..2a6284c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,10 @@ See [RELEASING.md](RELEASING.md) for the release process.
   payload, query parameters, and an events filter), emit named events with JSON
   arguments, and watch incoming events in the live log, with reusable saved
   emits.
+- **MCP requests**: connect to an external MCP server over Streamable HTTP
+  (routed through the server, reusing headers and auth), browse its tools, fill
+  in a tool's arguments via a form generated from its JSON Schema, call it, and
+  view the result. STDIO transport is not supported yet.
 - **Folders** inside collections, nestable to any depth (Postman-style).
   Folders carry their own description and pre-request/test scripts, which run in
   the execution chain (collection → folder(s) → request). Postman imports now
diff --git a/client/src/App.tsx b/client/src/App.tsx
index 72c195b..f7a04be 100644
--- a/client/src/App.tsx
+++ b/client/src/App.tsx
@@ -10,6 +10,7 @@ import { TopBar } from './components/TopBar';
 import { parseCurl } from './curl';
 import type { Selection } from './selection';
 import { ConnectionEditor } from './components/ConnectionEditor';
+import { McpEditor } from './components/McpEditor';
 import type {
   ApiRequest,
   Collection,
@@ -280,11 +281,12 @@ export default function App() {
             { value: 'graphql', label: 'GraphQL' },
             { value: 'websocket', label: 'WebSocket' },
             { value: 'socketio', label: 'Socket.IO' },
+            { value: 'mcp', label: 'MCP (HTTP)' },
           ],
         },
       ],
       onSubmit: async (values) => {
-        const allowed: RequestType[] = ['http', 'graphql', 'websocket', 'socketio'];
+        const allowed: RequestType[] = ['http', 'graphql', 'websocket', 'socketio', 'mcp'];
         const type = (allowed as string[]).includes(values.type)
           ? (values.type as RequestType)
           : 'http';
@@ -673,6 +675,22 @@ export default function App() {
       const request = findRequest(collectionId, folderPath, requestId);
       if (collection && request) {
         const key = `${collectionId}/${folderPath.join('/')}/${request.id}`;
+        if (request.type === 'mcp') {
+          return (
+            <McpEditor
+              key={key}
+              workspaceId={tree.meta.id}
+              collectionId={collectionId}
+              folderPath={folderPath}
+              request={request}
+              onSaved={() => loadTree(tree.meta.id, true)}
+              onDelete={() =>
+                deleteRequestAction(collectionId, folderPath, request)
+              }
+              onDirtyChange={handleDirtyChange}
+            />
+          );
+        }
         if (request.type === 'websocket' || request.type === 'socketio') {
           return (
             <ConnectionEditor
diff --git a/client/src/components/JsonSchemaForm.tsx b/client/src/components/JsonSchemaForm.tsx
new file mode 100644
index 0000000..22c11c1
--- /dev/null
+++ b/client/src/components/JsonSchemaForm.tsx
@@ -0,0 +1,194 @@
+import { useState } from 'react';
+
+/** The subset of JSON Schema the form understands; unknown shapes fall back to JSON. */
+export interface JsonSchema {
+  type?: string | string[];
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+  enum?: unknown[];
+  description?: string;
+  default?: unknown;
+  items?: JsonSchema;
+}
+
+interface Props {
+  schema: JsonSchema | undefined;
+  value: Record<string, unknown>;
+  onChange: (value: Record<string, unknown>) => void;
+}
+
+function typeOf(schema: JsonSchema): string {
+  const t = Array.isArray(schema.type) ? schema.type[0] : schema.type;
+  return t ?? (schema.enum ? 'enum' : 'json');
+}
+
+/** A minimal form generated from a tool's JSON Schema (object of scalars). */
+export function JsonSchemaForm({ schema, value, onChange }: Props) {
+  const properties = schema?.properties ?? {};
+  const required = new Set(schema?.required ?? []);
+  const names = Object.keys(properties);
+
+  if (names.length === 0) {
+    return <p className="muted">This tool takes no arguments.</p>;
+  }
+
+  const setField = (name: string, fieldValue: unknown) => {
+    const next = { ...value };
+    if (fieldValue === undefined) delete next[name];
+    else next[name] = fieldValue;
+    onChange(next);
+  };
+
+  return (
+    <div className="schema-form">
+      {names.map((name) => (
+        <SchemaField
+          key={name}
+          name={name}
+          schema={properties[name]}
+          required={required.has(name)}
+          value={value[name]}
+          onChange={(v) => setField(name, v)}
+        />
+      ))}
+    </div>
+  );
+}
+
+function SchemaField({
+  name,
+  schema,
+  required,
+  value,
+  onChange,
+}: {
+  name: string;
+  schema: JsonSchema;
+  required: boolean;
+  value: unknown;
+  onChange: (value: unknown) => void;
+}) {
+  const kind = schema.enum ? 'enum' : typeOf(schema);
+  const label = (
+    <label className="field-label">
+      {name}
+      {required && <span className="required-mark"> *</span>}
+      {schema.description && <span className="field-hint"> — {schema.description}</span>}
+    </label>
+  );
+
+  if (kind === 'boolean') {
+    return (
+      <div className="schema-field">
+        <label className="checkbox-label">
+          <input
+            type="checkbox"
+            checked={Boolean(value)}
+            onChange={(e) => onChange(e.target.checked)}
+          />
+          {name}
+          {required && <span className="required-mark"> *</span>}
+        </label>
+        {schema.description && <p className="muted">{schema.description}</p>}
+      </div>
+    );
+  }
+
+  if (kind === 'enum') {
+    const options = schema.enum ?? [];
+    return (
+      <div className="schema-field">
+        {label}
+        <select
+          className="method-select"
+          value={value === undefined ? '' : String(value)}
+          onChange={(e) => onChange(e.target.value === '' ? undefined : e.target.value)}
+        >
+          <option value="">(choose)</option>
+          {options.map((opt) => (
+            <option key={String(opt)} value={String(opt)}>
+              {String(opt)}
+            </option>
+          ))}
+        </select>
+      </div>
+    );
+  }
+
+  if (kind === 'number' || kind === 'integer') {
+    return (
+      <div className="schema-field">
+        {label}
+        <input
+          className="kv-value"
+          type="number"
+          value={value === undefined || value === null ? '' : String(value)}
+          onChange={(e) => {
+            const raw = e.target.value;
+            if (raw === '') return onChange(undefined);
+            const n = kind === 'integer' ? parseInt(raw, 10) : Number(raw);
+            onChange(Number.isNaN(n) ? raw : n);
+          }}
+        />
+      </div>
+    );
+  }
+
+  if (kind === 'string') {
+    return (
+      <div className="schema-field">
+        {label}
+        <input
+          className="kv-value"
+          value={value === undefined ? '' : String(value)}
+          onChange={(e) => onChange(e.target.value === '' ? undefined : e.target.value)}
+        />
+      </div>
+    );
+  }
+
+  // Fallback for arrays/objects/anyOf/etc: a validated JSON textarea.
+  return <JsonField label={label} value={value} onChange={onChange} />;
+}
+
+function JsonField({
+  label,
+  value,
+  onChange,
+}: {
+  label: React.ReactNode;
+  value: unknown;
+  onChange: (value: unknown) => void;
+}) {
+  const [text, setText] = useState(() =>
+    value === undefined ? '' : JSON.stringify(value, null, 2)
+  );
+  const [error, setError] = useState<string | null>(null);
+  return (
+    <div className="schema-field">
+      {label}
+      <textarea
+        className="code-area"
+        value={text}
+        spellCheck={false}
+        placeholder="JSON value"
+        onChange={(e) => {
+          const raw = e.target.value;
+          setText(raw);
+          if (raw.trim() === '') {
+            setError(null);
+            onChange(undefined);
+            return;
+          }
+          try {
+            onChange(JSON.parse(raw));
+            setError(null);
+          } catch {
+            setError('Invalid JSON');
+          }
+        }}
+      />
+      {error && <p className="error-text">{error}</p>}
+    </div>
+  );
+}
diff --git a/client/src/components/McpEditor.tsx b/client/src/components/McpEditor.tsx
new file mode 100644
index 0000000..1973765
--- /dev/null
+++ b/client/src/components/McpEditor.tsx
@@ -0,0 +1,328 @@
+import { useEffect, useRef, useState } from 'react';
+import { api } from '../api';
+import { createLiveSession, type LiveSession } from '../live';
+import type { ApiRequest } from '../types';
+import { AuthEditor } from './AuthEditor';
+import { DocsEditor } from './DocsEditor';
+import { JsonSchemaForm, type JsonSchema } from './JsonSchemaForm';
+import { KeyValueEditor } from './KeyValueEditor';
+import { VarField } from './VarField';
+
+interface Props {
+  workspaceId: string;
+  collectionId: string;
+  folderPath: string[];
+  request: ApiRequest;
+  onSaved: (request: ApiRequest) => void;
+  onDelete: () => void;
+  onDirtyChange: (dirty: boolean) => void;
+}
+
+type Tab = 'tools' | 'headers' | 'auth' | 'docs';
+type Status = 'idle' | 'connecting' | 'open' | 'closed' | 'error';
+
+/** A tool as returned by the MCP server (wire-only, not persisted). */
+interface McpTool {
+  name: string;
+  title?: string;
+  description?: string;
+  inputSchema?: JsonSchema;
+}
+
+interface ContentBlock {
+  type: string;
+  text?: string;
+  [key: string]: unknown;
+}
+interface ToolResult {
+  isError?: boolean;
+  content?: ContentBlock[];
+  structuredContent?: unknown;
+}
+
+export function McpEditor({
+  workspaceId,
+  collectionId,
+  folderPath,
+  request,
+  onSaved,
+  onDelete,
+  onDirtyChange,
+}: Props) {
+  const [saved, setSaved] = useState(request);
+  const [draft, setDraft] = useState(request);
+  const [tab, setTab] = useState<Tab>('tools');
+  const [status, setStatus] = useState<Status>('idle');
+  const [statusText, setStatusText] = useState<string | null>(null);
+  const [saveError, setSaveError] = useState<string | null>(null);
+  const [tools, setTools] = useState<McpTool[] | null>(null);
+  const [selected, setSelected] = useState<string | null>(null);
+  const [args, setArgs] = useState<Record<string, unknown>>({});
+  const [result, setResult] = useState<ToolResult | null>(null);
+  const [calling, setCalling] = useState(false);
+  const sessionRef = useRef<LiveSession | null>(null);
+
+  const dirty = JSON.stringify(draft) !== JSON.stringify(saved);
+  const connected = status === 'open';
+  const selectedTool = tools?.find((t) => t.name === selected) ?? null;
+
+  useEffect(() => {
+    onDirtyChange(dirty);
+  }, [dirty, onDirtyChange]);
+
+  useEffect(
+    () => () => {
+      sessionRef.current?.close();
+      sessionRef.current = null;
+      onDirtyChange(false);
+    },
+    [onDirtyChange]
+  );
+
+  const patch = (changes: Partial<ApiRequest>) => setDraft((d) => ({ ...d, ...changes }));
+  const patchMcp = (changes: Partial<ApiRequest['mcp']>) =>
+    setDraft((d) => ({ ...d, mcp: { ...d.mcp, ...changes } }));
+
+  async function save() {
+    setSaveError(null);
+    try {
+      await api.updateRequest(workspaceId, collectionId, folderPath, draft);
+      setSaved(draft);
+      onSaved(draft);
+    } catch (err) {
+      setSaveError(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  function connect() {
+    if (sessionRef.current) return;
+    setStatus('connecting');
+    setStatusText(`Connecting to ${draft.mcp.url}…`);
+    setTools(null);
+    setResult(null);
+    sessionRef.current = createLiveSession({
+      workspaceId,
+      collectionId,
+      folderPath,
+      request: draft,
+      onOpen: () => {
+        setStatus('open');
+        setStatusText('Connected. Loading tools…');
+        sessionRef.current?.send({ op: 'listTools' });
+      },
+      onMessage: (payload) => {
+        const p = payload as
+          | { kind: 'tools'; tools: McpTool[] }
+          | { kind: 'result'; callId: string; result: ToolResult };
+        if (p.kind === 'tools') {
+          setTools(p.tools);
+          setStatusText(`${p.tools.length} tool${p.tools.length === 1 ? '' : 's'} available.`);
+        } else if (p.kind === 'result') {
+          setResult(p.result);
+          setCalling(false);
+        }
+      },
+      onError: (message) => {
+        setStatus('error');
+        setStatusText(`Error: ${message}`);
+        setCalling(false);
+      },
+      onClosed: () => {
+        setStatus('closed');
+        setStatusText('Disconnected.');
+        sessionRef.current = null;
+      },
+    });
+  }
+
+  function disconnect() {
+    sessionRef.current?.close();
+    sessionRef.current = null;
+    setStatus('closed');
+    setStatusText('Disconnected.');
+  }
+
+  function selectTool(name: string) {
+    setSelected(name);
+    setArgs({});
+    setResult(null);
+  }
+
+  function callTool() {
+    if (!selected || !connected) return;
+    setResult(null);
+    setCalling(true);
+    sessionRef.current?.send({
+      op: 'callTool',
+      callId: crypto.randomUUID(),
+      name: selected,
+      args,
+    });
+  }
+
+  useEffect(() => {
+    function onKeyDown(e: KeyboardEvent) {
+      if ((e.metaKey || e.ctrlKey) && e.key === 's') {
+        e.preventDefault();
+        void save();
+      }
+    }
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+  });
+
+  return (
+    <div className="request-editor">
+      <div className="editor-title-row">
+        <span className="type-badge type-mcp">MCP</span>
+        <input
+          className="name-input"
+          value={draft.name}
+          onChange={(e) => patch({ name: e.target.value })}
+        />
+        <button
+          className={dirty ? 'btn btn-primary' : 'btn'}
+          title={dirty ? 'You have unsaved changes' : 'No unsaved changes'}
+          onClick={save}
+        >
+          Save
+        </button>
+        <button className="btn btn-danger-ghost" onClick={onDelete}>
+          Delete
+        </button>
+      </div>
+      {saveError && <p className="error-text">{saveError}</p>}
+
+      <div className="url-row">
+        <span className={`conn-status conn-${status}`}>{status}</span>
+        <VarField
+          className="url-input"
+          wrapClassName="url-wrap"
+          value={draft.mcp.url}
+          placeholder="https://mcp.example.com/mcp"
+          onChange={(url) => patchMcp({ url })}
+        />
+        {connected || status === 'connecting' ? (
+          <button className="btn" onClick={disconnect}>
+            Disconnect
+          </button>
+        ) : (
+          <button
+            className="btn btn-primary"
+            onClick={connect}
+            disabled={!draft.mcp.url.trim()}
+          >
+            Connect
+          </button>
+        )}
+      </div>
+
+      <div className="tab-group editor-tabs">
+        {(
+          [
+            ['tools', 'Tools'],
+            ['headers', 'Headers'],
+            ['auth', 'Auth'],
+            ['docs', 'Docs'],
+          ] as [Tab, string][]
+        ).map(([value, label]) => (
+          <button
+            key={value}
+            className={tab === value ? 'tab active' : 'tab'}
+            onClick={() => setTab(value)}
+          >
+            {label}
+          </button>
+        ))}
+      </div>
+
+      <div className="tab-content mcp-content">
+        {tab === 'tools' &&
+          (!connected ? (
+            <p className="muted">{statusText ?? 'Connect to list this server’s tools.'}</p>
+          ) : (
+            <div className="mcp-tools">
+              <div className="mcp-tool-list">
+                {statusText && <p className="muted">{statusText}</p>}
+                {(tools ?? []).map((t) => (
+                  <button
+                    key={t.name}
+                    className={selected === t.name ? 'mcp-tool selected' : 'mcp-tool'}
+                    onClick={() => selectTool(t.name)}
+                    title={t.description}
+                  >
+                    {t.title || t.name}
+                  </button>
+                ))}
+              </div>
+
+              <div className="mcp-tool-detail">
+                {selectedTool ? (
+                  <>
+                    <h3 className="mcp-tool-name">{selectedTool.name}</h3>
+                    {selectedTool.description && (
+                      <p className="muted">{selectedTool.description}</p>
+                    )}
+                    <JsonSchemaForm
+                      schema={selectedTool.inputSchema}
+                      value={args}
+                      onChange={setArgs}
+                    />
+                    <button
+                      className="btn btn-primary"
+                      onClick={callTool}
+                      disabled={calling}
+                    >
+                      {calling ? 'Calling…' : 'Call tool'}
+                    </button>
+                    {result && <ResultPanel result={result} />}
+                  </>
+                ) : (
+                  <p className="muted">Select a tool to call it.</p>
+                )}
+              </div>
+            </div>
+          ))}
+
+        {tab === 'headers' && (
+          <KeyValueEditor
+            items={draft.headers}
+            onChange={(headers) => patch({ headers })}
+            keyPlaceholder="Header"
+            addLabel="Header"
+          />
+        )}
+
+        {tab === 'auth' && (
+          <AuthEditor auth={draft.auth} onChange={(auth) => patch({ auth })} />
+        )}
+
+        {tab === 'docs' && (
+          <DocsEditor
+            value={draft.docs}
+            onChange={(docs) => patch({ docs })}
+            placeholder="Document this MCP connection in Markdown…"
+          />
+        )}
+      </div>
+    </div>
+  );
+}
+
+function ResultPanel({ result }: { result: ToolResult }) {
+  return (
+    <div className={`mcp-result ${result.isError ? 'mcp-result-error' : ''}`}>
+      <div className="mcp-result-head">{result.isError ? 'Error' : 'Result'}</div>
+      {(result.content ?? []).map((block, i) =>
+        block.type === 'text' ? (
+          <pre key={i} className="mcp-result-text">{block.text}</pre>
+        ) : (
+          <pre key={i} className="mcp-result-text">{JSON.stringify(block, null, 2)}</pre>
+        )
+      )}
+      {result.structuredContent !== undefined && (
+        <pre className="mcp-result-text">{JSON.stringify(result.structuredContent, null, 2)}</pre>
+      )}
+    </div>
+  );
+}
diff --git a/client/src/components/Sidebar.tsx b/client/src/components/Sidebar.tsx
index e1e15e5..8927987 100644
--- a/client/src/components/Sidebar.tsx
+++ b/client/src/components/Sidebar.tsx
@@ -70,6 +70,7 @@ function badgeLabel(request: ApiRequest): string {
   if (request.type === 'graphql') return 'GQL';
   if (request.type === 'websocket') return 'WS';
   if (request.type === 'socketio') return 'IO';
+  if (request.type === 'mcp') return 'MCP';
   return request.method;
 }
 
@@ -77,6 +78,7 @@ function badgeClass(request: ApiRequest): string {
   if (request.type === 'graphql') return 'method-GQL';
   if (request.type === 'websocket') return 'method-WS';
   if (request.type === 'socketio') return 'method-IO';
+  if (request.type === 'mcp') return 'method-MCP';
   return `method-${request.method}`;
 }
 
diff --git a/client/src/curl.ts b/client/src/curl.ts
index 849eef7..a0a18de 100644
--- a/client/src/curl.ts
+++ b/client/src/curl.ts
@@ -295,6 +295,7 @@ export function parseCurl(command: string): Omit<ApiRequest, 'id'> {
     graphql: { query: '', variables: '' },
     websocket: { url: '', subprotocols: '', messages: [] },
     socketio: { url: '', path: '', auth: '', query: [], emitEvents: [], listenEvents: [] },
+    mcp: { url: '' },
     docs: '',
     scripts: { preRequest: '', postResponse: '' },
   };
diff --git a/client/src/styles.css b/client/src/styles.css
index 287b2e2..b796bef 100644
--- a/client/src/styles.css
+++ b/client/src/styles.css
@@ -217,6 +217,7 @@ pre,
 .method-GQL { color: var(--pink); }
 .method-WS { color: var(--blue); }
 .method-IO { color: var(--green); }
+.method-MCP { color: var(--yellow); }
 
 /* ---------- main pane ---------- */
 
@@ -298,6 +299,7 @@ pre,
 .type-folder { background: #2a3340; color: var(--blue); }
 .type-websocket { background: #24323b; color: var(--blue); }
 .type-socketio { background: #243b2c; color: var(--green); }
+.type-mcp { background: #3b3324; color: var(--yellow); }
 
 /* ----- live connection (WebSocket/Socket.IO/MCP) ----- */
 .conn-status {
@@ -363,6 +365,51 @@ pre,
   user-select: none;
   width: fit-content;
 }
+
+/* ----- MCP editor ----- */
+.mcp-content { overflow: auto; }
+.mcp-tools { display: flex; gap: 16px; align-items: flex-start; }
+.mcp-tool-list {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  min-width: 160px;
+  max-width: 220px;
+}
+.mcp-tool {
+  text-align: left;
+  padding: 6px 8px;
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  background: var(--bg-elev);
+  color: var(--text);
+  cursor: pointer;
+}
+.mcp-tool.selected { border-color: var(--blue); color: var(--blue); }
+.mcp-tool-detail { flex: 1; min-width: 0; display: flex; flex-direction: column; gap: 10px; }
+.mcp-tool-name { margin: 0; font-size: 1em; }
+
+.schema-form { display: flex; flex-direction: column; gap: 12px; }
+.schema-field { display: flex; flex-direction: column; gap: 4px; }
+.required-mark { color: var(--red); }
+.field-hint { color: var(--text-muted); font-weight: normal; }
+.checkbox-label { display: flex; gap: 6px; align-items: center; cursor: pointer; }
+
+.mcp-result {
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  padding: 8px 10px;
+  background: var(--bg-elev);
+}
+.mcp-result-error { border-color: var(--red); }
+.mcp-result-head {
+  font-size: 0.8em;
+  text-transform: uppercase;
+  color: var(--text-muted);
+  margin-bottom: 4px;
+}
+.mcp-result-error .mcp-result-head { color: var(--red); }
+.mcp-result-text { margin: 0; white-space: pre-wrap; word-break: break-word; }
 .composer-actions {
   display: flex;
   flex-direction: column;
diff --git a/client/src/types.ts b/client/src/types.ts
index 95bfdb4..fb5a5d9 100644
--- a/client/src/types.ts
+++ b/client/src/types.ts
@@ -1,4 +1,4 @@
-export type RequestType = 'http' | 'graphql' | 'websocket' | 'socketio';
+export type RequestType = 'http' | 'graphql' | 'websocket' | 'socketio' | 'mcp';
 
 export type HttpMethod =
   | 'GET'
@@ -91,6 +91,11 @@ export interface SocketIOConfig {
   listenEvents: string[];
 }
 
+/** MCP client config (Streamable HTTP transport; reuses headers + auth). */
+export interface McpConfig {
+  url: string;
+}
+
 /** Postman-style automation scripts (JavaScript using the `pm` API). */
 export interface Scripts {
   preRequest: string;
@@ -110,6 +115,7 @@ export interface ApiRequest {
   graphql: GraphQLBody;
   websocket: WebSocketConfig;
   socketio: SocketIOConfig;
+  mcp: McpConfig;
   docs: string;
   scripts: Scripts;
 }
diff --git a/server/src/live/mcpDriver.ts b/server/src/live/mcpDriver.ts
new file mode 100644
index 0000000..be9340c
--- /dev/null
+++ b/server/src/live/mcpDriver.ts
@@ -0,0 +1,86 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { interpolate } from '../execute.js';
+import { buildHandshakeHeaders } from './handshake.js';
+import type { DriverContext, LiveDriver } from './driver.js';
+
+/**
+ * MCP client driver (Streamable HTTP transport only for now). Unlike the
+ * WebSocket/Socket.IO drivers this is request/response rather than a free
+ * stream: the browser sends control ops over `send` and gets correlated
+ * `message` frames back.
+ *   { op: 'listTools' }                     → { kind: 'tools', tools }
+ *   { op: 'callTool', callId, name, args }  → { kind: 'result', callId, result }
+ */
+
+interface ListToolsOp {
+  op: 'listTools';
+}
+interface CallToolOp {
+  op: 'callTool';
+  callId: string;
+  name: string;
+  args?: Record<string, unknown>;
+}
+type McpOp = ListToolsOp | CallToolOp;
+
+export function createMcpDriver(ctx: DriverContext): LiveDriver {
+  let client: Client | null = null;
+
+  return {
+    async open() {
+      const raw = interpolate(ctx.request.mcp.url, ctx.vars).trim();
+      let url: URL;
+      try {
+        url = new URL(raw);
+      } catch {
+        throw new Error(`Invalid MCP URL: "${raw}"`);
+      }
+      if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error('MCP URL must start with http:// or https://');
+      }
+      const headers = buildHandshakeHeaders(ctx, url);
+      const transport = new StreamableHTTPClientTransport(url, {
+        requestInit: { headers },
+      });
+      client = new Client({ name: 'api-notebook', version: '1.0.0' });
+      await client.connect(transport);
+      ctx.emit('open', { server: client.getServerVersion() ?? undefined });
+    },
+
+    async send(payload: unknown) {
+      if (!client) return;
+      const op = payload as McpOp;
+      if (op.op === 'listTools') {
+        const res = await client.listTools();
+        ctx.emit('message', { kind: 'tools', tools: res.tools });
+      } else if (op.op === 'callTool') {
+        try {
+          const result = await client.callTool({
+            name: op.name,
+            arguments: op.args ?? {},
+          });
+          ctx.emit('message', { kind: 'result', callId: op.callId, result });
+        } catch (err) {
+          // Surface the failure inline against its call rather than as a
+          // channel-level error, so the UI can show it next to the tool.
+          ctx.emit('message', {
+            kind: 'result',
+            callId: op.callId,
+            result: {
+              isError: true,
+              content: [
+                { type: 'text', text: err instanceof Error ? err.message : String(err) },
+              ],
+            },
+          });
+        }
+      }
+    },
+
+    close() {
+      void client?.close();
+      client = null;
+    },
+  };
+}
diff --git a/server/src/liveSessions.ts b/server/src/liveSessions.ts
index 54d2795..a33a32b 100644
--- a/server/src/liveSessions.ts
+++ b/server/src/liveSessions.ts
@@ -8,6 +8,7 @@ import type { ApiRequest } from './types.js';
 import type { DriverContext, Emit, LiveDriver } from './live/driver.js';
 import { createWsDriver } from './live/wsDriver.js';
 import { createSocketioDriver } from './live/socketioDriver.js';
+import { createMcpDriver } from './live/mcpDriver.js';
 
 /**
  * The live channel: a single browser WebSocket (at /live) multiplexes many
@@ -57,6 +58,8 @@ function driverFor(type: ApiRequest['type'], ctx: DriverContext): LiveDriver {
       return createWsDriver(ctx);
     case 'socketio':
       return createSocketioDriver(ctx);
+    case 'mcp':
+      return createMcpDriver(ctx);
     default:
       throw new Error(`Protocol "${type}" is not supported on the live channel`);
   }
diff --git a/server/src/mcp-client.integration.test.ts b/server/src/mcp-client.integration.test.ts
new file mode 100644
index 0000000..dd87086
--- /dev/null
+++ b/server/src/mcp-client.integration.test.ts
@@ -0,0 +1,167 @@
+import http from 'node:http';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import express from 'express';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { WebSocket } from 'ws';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { z } from 'zod';
+import type { ApiRequest } from './types.js';
+
+// Redirect app-local state (~/.apinotebook) to a temp home before importing the
+// modules (appData/cookies compute their dirs at module load).
+let tmpHome: string;
+let wsDir: string;
+let appServer: http.Server;
+let liveUrl: string;
+let mcpHttp: http.Server;
+let mcpUrl: string;
+let wsId: string;
+let makeRequest: (over: Partial<ApiRequest>) => ApiRequest;
+
+function listening(server: http.Server): Promise<void> {
+  return new Promise((r) => server.listen(0, '127.0.0.1', () => r()));
+}
+function portOf(server: { address(): unknown }): number {
+  const addr = server.address();
+  return typeof addr === 'object' && addr ? (addr as { port: number }).port : 0;
+}
+
+beforeAll(async () => {
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'apinb-home-'));
+  wsDir = fs.mkdtempSync(path.join(os.tmpdir(), 'apinb-wsdir-'));
+  vi.spyOn(os, 'homedir').mockReturnValue(tmpHome);
+  vi.resetModules();
+
+  const wsfs = await import('./workspaceFs.js');
+  const appData = await import('./appData.js');
+  const { attachLiveSessions } = await import('./liveSessions.js');
+
+  const meta = wsfs.createWorkspace('Live MCP', wsDir);
+  appData.addWorkspaceEntry({ id: meta.id, path: meta.path });
+  wsId = meta.id;
+  makeRequest = (over) => ({ ...wsfs.defaultRequest('r', 'r', 'mcp'), ...over });
+
+  // In-test MCP server (Streamable HTTP) exposing one echo tool.
+  const mcpApp = express();
+  mcpApp.use(express.json());
+  mcpApp.post('/mcp', async (req, res) => {
+    const server = new McpServer({ name: 'test-mcp', version: '0.0.1' });
+    server.registerTool(
+      'echo',
+      { description: 'Echoes the text back', inputSchema: { text: z.string() } },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (async (args: any) => ({ content: [{ type: 'text', text: args.text }] })) as never
+    );
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+      enableJsonResponse: true,
+    });
+    res.on('close', () => {
+      void transport.close();
+      void server.close();
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+  });
+  mcpHttp = http.createServer(mcpApp);
+  await listening(mcpHttp);
+  mcpUrl = `http://127.0.0.1:${portOf(mcpHttp)}/mcp`;
+
+  // Our server with the live channel attached.
+  appServer = http.createServer();
+  attachLiveSessions(appServer);
+  await listening(appServer);
+  liveUrl = `ws://127.0.0.1:${portOf(appServer)}/live`;
+});
+
+afterAll(async () => {
+  vi.restoreAllMocks();
+  await new Promise<void>((r) => mcpHttp.close(() => r()));
+  await new Promise<void>((r) => appServer.close(() => r()));
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+  fs.rmSync(wsDir, { recursive: true, force: true });
+});
+
+interface ToolInfo {
+  name: string;
+  description?: string;
+}
+interface Frame {
+  t: string;
+  sessionId: string;
+  payload?: {
+    kind?: string;
+    tools?: ToolInfo[];
+    callId?: string;
+    result?: { isError?: boolean; content?: { type: string; text?: string }[] };
+    message?: string;
+  };
+}
+
+describe('live channel — MCP (HTTP)', () => {
+  it('connects, lists tools, and calls a tool', async () => {
+    const client = new WebSocket(liveUrl);
+    await new Promise<void>((r) => client.once('open', () => r()));
+
+    const nextFrame = (pred: (f: Frame) => boolean): Promise<Frame> =>
+      new Promise((resolve) => {
+        const onMsg = (d: WebSocket.RawData) => {
+          const f = JSON.parse(d.toString()) as Frame;
+          if (pred(f)) {
+            client.off('message', onMsg);
+            resolve(f);
+          }
+        };
+        client.on('message', onMsg);
+      });
+
+    const request = makeRequest({ mcp: { url: mcpUrl } });
+    client.send(
+      JSON.stringify({ t: 'connect', sessionId: 'M1', workspaceId: wsId, request })
+    );
+    await nextFrame((f) => f.t === 'open' && f.sessionId === 'M1');
+
+    client.send(JSON.stringify({ t: 'send', sessionId: 'M1', payload: { op: 'listTools' } }));
+    const tools = await nextFrame(
+      (f) => f.t === 'message' && f.payload?.kind === 'tools'
+    );
+    expect(tools.payload?.tools?.map((t) => t.name)).toContain('echo');
+
+    client.send(
+      JSON.stringify({
+        t: 'send',
+        sessionId: 'M1',
+        payload: { op: 'callTool', callId: 'c1', name: 'echo', args: { text: 'hi there' } },
+      })
+    );
+    const result = await nextFrame(
+      (f) => f.t === 'message' && f.payload?.kind === 'result' && f.payload?.callId === 'c1'
+    );
+    expect(result.payload?.result?.isError).toBeFalsy();
+    expect(result.payload?.result?.content?.[0]?.text).toBe('hi there');
+
+    client.send(JSON.stringify({ t: 'close', sessionId: 'M1' }));
+    client.close();
+  });
+
+  it('reports an error for an invalid target URL', async () => {
+    const client = new WebSocket(liveUrl);
+    await new Promise<void>((r) => client.once('open', () => r()));
+    const request = makeRequest({ mcp: { url: 'ftp://nope/' } });
+    const errored = new Promise<Frame>((resolve) => {
+      client.on('message', (d) => {
+        const f = JSON.parse(d.toString()) as Frame;
+        if (f.t === 'error' && f.sessionId === 'M2') resolve(f);
+      });
+    });
+    client.send(
+      JSON.stringify({ t: 'connect', sessionId: 'M2', workspaceId: wsId, request })
+    );
+    const f = await errored;
+    expect(f.payload?.message).toMatch(/MCP URL/);
+    client.close();
+  });
+});
diff --git a/server/src/postmanImport.ts b/server/src/postmanImport.ts
index 209deec..41e03ab 100644
--- a/server/src/postmanImport.ts
+++ b/server/src/postmanImport.ts
@@ -286,6 +286,7 @@ function convertRequest(item: PostmanItem): ConvertedRequest {
     graphql,
     websocket: { url: '', subprotocols: '', messages: [] },
     socketio: { url: '', path: '', auth: '', query: [], emitEvents: [], listenEvents: [] },
+    mcp: { url: '' },
     docs: describe(req.description),
     scripts: eventsToScripts(item.event),
   };
diff --git a/server/src/router.ts b/server/src/router.ts
index 50ed005..bda318d 100644
--- a/server/src/router.ts
+++ b/server/src/router.ts
@@ -190,7 +190,7 @@ router.post(
   wrap((req, res) => {
     const ws = getWorkspace(req.params.id);
     const name = requireString(req.body.name, 'name');
-    const allowed = ['http', 'graphql', 'websocket', 'socketio'] as const;
+    const allowed = ['http', 'graphql', 'websocket', 'socketio', 'mcp'] as const;
     const type = allowed.includes(req.body.type) ? req.body.type : 'http';
     const folderPath = parseFolderPath(req.body.folderPath);
     res
diff --git a/server/src/types.ts b/server/src/types.ts
index 5901410..6193e27 100644
--- a/server/src/types.ts
+++ b/server/src/types.ts
@@ -1,4 +1,4 @@
-export type RequestType = 'http' | 'graphql' | 'websocket' | 'socketio';
+export type RequestType = 'http' | 'graphql' | 'websocket' | 'socketio' | 'mcp';
 
 export type HttpMethod =
   | 'GET'
@@ -81,6 +81,11 @@ export interface SocketIOConfig {
   listenEvents: string[];
 }
 
+/** MCP client config (Streamable HTTP transport; reuses headers + auth). */
+export interface McpConfig {
+  url: string;
+}
+
 /** Postman-style automation scripts (JavaScript using the `pm` API). */
 export interface Scripts {
   preRequest: string;
@@ -100,6 +105,7 @@ export interface ApiRequest {
   graphql: GraphQLBody;
   websocket: WebSocketConfig;
   socketio: SocketIOConfig;
+  mcp: McpConfig;
   docs: string;
   scripts: Scripts;
 }
diff --git a/server/src/workspaceFs.test.ts b/server/src/workspaceFs.test.ts
index b12bd83..96fd470 100644
--- a/server/src/workspaceFs.test.ts
+++ b/server/src/workspaceFs.test.ts
@@ -163,6 +163,19 @@ describe('collections & requests (round-trip)', () => {
     expect(read.socketio.listenEvents).toEqual(['chat', 'pong']);
   });
 
+  it('persists an mcp request with its url', () => {
+    const col = wsfs.createCollection(ws, 'MCP');
+    const created = wsfs.createRequest(ws, col.id, [], 'Agent', 'mcp');
+    expect(created.mcp).toEqual({ url: '' });
+    wsfs.updateRequest(ws, col.id, [], created.id, {
+      ...created,
+      mcp: { url: 'https://mcp.example.com/mcp' },
+    });
+    const read = wsfs.getRequest(ws, col.id, [], created.id);
+    expect(read.type).toBe('mcp');
+    expect(read.mcp.url).toBe('https://mcp.example.com/mcp');
+  });
+
   it('back-fills missing fields and reads a legacy requests/ subdir', () => {
     const col = wsfs.createCollection(ws, 'Old');
     // Pre-folders workspaces stored requests in a legacy requests/ subdir.
diff --git a/server/src/workspaceFs.ts b/server/src/workspaceFs.ts
index 33c7867..fe98fbb 100644
--- a/server/src/workspaceFs.ts
+++ b/server/src/workspaceFs.ts
@@ -235,6 +235,7 @@ function readRequest(
   const storedGraphql: Partial<ApiRequest['graphql']> = stored.graphql ?? {};
   const storedWebsocket: Partial<ApiRequest['websocket']> = stored.websocket ?? {};
   const storedSocketio: Partial<ApiRequest['socketio']> = stored.socketio ?? {};
+  const storedMcp: Partial<ApiRequest['mcp']> = stored.mcp ?? {};
   return {
     ...stored,
     body: {
@@ -257,6 +258,7 @@ function readRequest(
       listenEvents: [],
       ...storedSocketio,
     },
+    mcp: { url: '', ...storedMcp },
     id,
     docs,
   };
@@ -517,6 +519,7 @@ export function defaultRequest(
     graphql: { query: '', variables: '' },
     websocket: { url: '', subprotocols: '', messages: [] },
     socketio: { url: '', path: '', auth: '', query: [], emitEvents: [], listenEvents: [] },
+    mcp: { url: '' },
     docs: '',
     scripts: { preRequest: '', postResponse: '' },
   };