@agenticmail/mcp 0.7.1 → 0.7.3

package/README.md

@@ -10,7 +10,7 @@ When connected, your AI agent can send emails and texts, check inboxes, reply to
 npm install -g @agenticmail/mcp
 ```
 
-**Requirements:** Node.js 20+, AgenticMail API server running
+**Requirements:** Node.js 22+, AgenticMail API server running
 
 ---
 
@@ -35,7 +35,7 @@ Add to your MCP client configuration (e.g., `.mcp.json` or project settings):
       "command": "npx",
       "args": ["agenticmail-mcp"],
       "env": {
-        "AGENTICMAIL_API_URL": "http://127.0.0.1:3100",
+        "AGENTICMAIL_API_URL": "http://127.0.0.1:3829",
         "AGENTICMAIL_API_KEY": "ak_your_agent_key"
       }
     }
@@ -56,7 +56,7 @@ For desktop AI applications, add to your MCP configuration file. Example paths:
       "command": "npx",
       "args": ["agenticmail-mcp"],
       "env": {
-        "AGENTICMAIL_API_URL": "http://127.0.0.1:3100",
+        "AGENTICMAIL_API_URL": "http://127.0.0.1:3829",
         "AGENTICMAIL_API_KEY": "ak_your_agent_key"
       }
     }
@@ -68,9 +68,27 @@ For desktop AI applications, add to your MCP configuration file. Example paths:
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `AGENTICMAIL_API_URL` | Yes | AgenticMail API server URL (e.g., `http://127.0.0.1:3100`) |
-| `AGENTICMAIL_API_KEY` | Yes | Agent API key (`ak_...`). Determines which agent this MCP server acts as. |
-| `AGENTICMAIL_MASTER_KEY` | No | Master key (`mk_...`). Required for admin operations (create/delete agents, approve emails, gateway config). |
+| `AGENTICMAIL_API_URL` | Yes | AgenticMail API server URL. Default port is **`3829`** (changed from `3100` in `@agenticmail/mcp@0.7.x` to avoid common dev-tool conflicts). Example: `http://127.0.0.1:3829`. |
+| `AGENTICMAIL_API_KEY` | Yes¹ | Agent API key (`ak_...`). Determines the default identity this MCP server acts as when a tool call doesn't pass `_account`. |
+| `AGENTICMAIL_MASTER_KEY` | No | Master key (`mk_...`). Required for admin operations (create/delete agents, approve emails, gateway config). **Also enables on-demand `_account` resolution** — any tool call passing `_account: "<name>"` will lazily fetch that agent's API key via the master key the first time it sees the name, so freshly-`create_account`'d agents become addressable without restarting the MCP server. |
+| `AGENTICMAIL_ACCOUNT_KEYS_JSON` | No | JSON map of `{"<agentName>": "<apiKey>"}` for per-call identity switching. When the caller passes `_account: "Fola"` (etc.), the server authenticates AS that agent for the duration of the call. Populated automatically by `agenticmail claudecode install` for the Claude Code integration. |
+
+¹ Either `AGENTICMAIL_API_KEY` OR `AGENTICMAIL_MASTER_KEY` (or `AGENTICMAIL_ACCOUNT_KEYS_JSON`) must be set, but you don't strictly need all three.
+
+### Per-call identity switching (`_account`)
+
+Every tool's input schema accepts an optional `_account: "<name>"` parameter. When passed, the server resolves that name to an apiKey (from `AGENTICMAIL_ACCOUNT_KEYS_JSON`, then falling back to a live master-keyed lookup of `/accounts`) and runs the call as that agent. Without `_account`, the call uses `AGENTICMAIL_API_KEY` as the default identity.
+
+This is what powers the [`@agenticmail/claudecode`](https://www.npmjs.com/package/@agenticmail/claudecode) integration: one MCP server process, many AgenticMail identities. A Claude Code subagent that "is" Fola passes `_account: "Fola"` on every call and ends up reading Fola's real inbox, sending mail from `fola@localhost`, and so on.
+
+### Meta-tools for cheap discovery (`request_tools` + `invoke`)
+
+To keep host context windows small, only ~10 of the 62 tools are pre-declared in a typical subagent's `tools:` whitelist. The other ~50 stay reachable through two always-on meta-tools:
+
+- **`request_tools({ query?, sets? })`** — Returns a text catalogue of the unloaded tools, grouped by set (`mail_extras`, `mail_compose`, `sms`, `account_admin`, …). Optional substring filter or set-name filter.
+- **`invoke({ tool, args, _account? })`** — Dispatches to any of the 62 tools by name. The agent uses `request_tools` to discover, `invoke` to call.
+
+Token impact: a typical subagent spawn loads ~3K tokens of tool schemas instead of ~15K. The cost is one extra round trip for uncommon operations (discover → invoke), which is almost always a worthwhile trade.
 
 ---
 

package/dist/index.js

@@ -22383,11 +22383,18 @@ var TOOL_SETS = {
     "search_emails",
     "list_agents",
     "message_agent",
-    // call_agent is the headline coordination primitive: synchronous RPC
-    // to another AgenticMail agent that returns a structured result. It is
-    // the reason multi-agent setups exist on this platform and belongs in
-    // the pre-loaded toolset, not behind a request_tools indirection.
+    // call_agent is the one-shot RPC primitive — sync request, sync answer.
+    // Used when you need ONE structured result from ONE teammate; for
+    // multi-step coordination use the thread pattern (send_email with CC
+    // + reply_email with replyAll) instead.
     "call_agent",
+    // wait_for_email is the thread-coordination primitive: block until a
+    // specific reply lands in your inbox (filter by from / subject /
+    // inReplyTo / participants). The host uses it to wake on the next
+    // teammate reply; agents use it when they delegate and need an answer
+    // back. Essential enough that paying its tokens at every spawn beats
+    // making the agent discover it via request_tools.
+    "wait_for_email",
     "check_tasks"
   ],
   /** Less-common mail operations. */
@@ -22429,7 +22436,6 @@ var TOOL_SETS = {
   /** Agent coordination beyond the basics in `essential`. */
   agent_coord: [
     "check_messages",
-    "wait_for_email",
     "claim_task",
     "submit_result"
   ],
@@ -22603,15 +22609,15 @@ async function apiRequest(method, path, body, useMasterKey = false, timeoutMs =
 var toolDefinitions = [
   {
     name: "send_email",
-    description: "Send an email from the agent's mailbox. External emails are scanned for sensitive content. HIGH severity detections are BLOCKED and held for owner approval. Your owner will be notified and must approve blocked emails. You CANNOT bypass the outbound guard.",
+    description: "Send an email from the agent's mailbox. Supports multiple recipients on To and CC (comma-separated). This is the PRIMARY primitive for multi-agent coordination: kick off a thread with all participants on CC, and every local recipient is woken automatically. Each woken agent reads the thread, decides whose turn it is, and either reply-all's to contribute or stays silent. External emails are scanned for sensitive content; HIGH severity detections are BLOCKED for owner approval. You CANNOT bypass the outbound guard.",
     inputSchema: {
       type: "object",
       properties: {
-        to: { type: "string", description: "Recipient email address" },
+        to: { type: "string", description: "Recipient email address(es). For multi-agent threads, put the primary actor here and CC the rest. Comma-separated supported." },
         subject: { type: "string", description: "Email subject line" },
         text: { type: "string", description: "Plain text body" },
         html: { type: "string", description: "HTML body (optional)" },
-        cc: { type: "string", description: "CC recipients (optional)" },
+        cc: { type: "string", description: 'CC recipients \u2014 the team. Comma-separated, e.g. "vesper@localhost, orion@localhost". Every local @localhost recipient is auto-woken when this email lands.' },
         inReplyTo: { type: "string", description: "Message-ID to reply to (optional)" },
         references: {
           type: "array",
@@ -22699,7 +22705,7 @@ var toolDefinitions = [
   },
   {
     name: "reply_email",
-    description: "Reply to an email. Fetches the original message, auto-fills To, Subject (Re:), In-Reply-To, and References, then sends with quoted body. Outbound guard applies \u2014 HIGH severity content is held for review.",
+    description: "Reply to an email. Fetches the original message, auto-fills To, Subject (Re:), In-Reply-To, and References, then sends with quoted body. **For multi-agent thread coordination, pass `replyAll: true`** so every CC'd participant sees your contribution and stays in context \u2014 that is how the thread-as-workspace pattern works. Outbound guard applies \u2014 HIGH severity content is held for review.",
     inputSchema: {
       type: "object",
       properties: {
@@ -22878,7 +22884,7 @@ var toolDefinitions = [
   },
   {
     name: "create_account",
-    description: "Create a new agent email account (requires master API key)",
+    description: 'Create a new AgenticMail agent (email account + identity + API key + persona derived from role/metadata). Requires master API key. After creation: address them at `<name>@localhost`, delegate work via `call_agent({ target: "<name>", task: ... })`, or hand off via `send_email` / `message_agent`. The new agent acts as themselves \u2014 you never need to (and must not) roleplay them inside your host\'s native sub-agent tool.',
     inputSchema: {
       type: "object",
       properties: {
@@ -22999,7 +23005,7 @@ var toolDefinitions = [
   },
   {
     name: "list_agents",
-    description: "List all AI agents in the system with their email addresses and roles. Use this to discover which agents you can communicate with via message_agent.",
+    description: "List all AI agents in the system with their email addresses and roles. Use this to discover which agents you can call via call_agent (sync RPC) or email via send_email / message_agent (async). DO NOT spawn one of your host's native sub-agents and roleplay AS these agents \u2014 each one is a real identity with its own mailbox; just address them through AgenticMail and let them work as themselves.",
     inputSchema: {
       type: "object",
       properties: {}
@@ -23007,7 +23013,7 @@ var toolDefinitions = [
   },
   {
     name: "message_agent",
-    description: "Send a message to another AI agent by name. The message is delivered to their email inbox. Use list_agents first to see available agents. This is the primary way for agents to coordinate and share information with each other.",
+    description: "Async fire-and-forget: deliver a message to another AI agent's inbox. They will process it on their own schedule (immediately if a dispatcher is attached, later otherwise) and may reply by email. Use this for non-blocking handoffs. Prefer `call_agent` when you need a structured reply back. Both flows let the target agent do the work AS THEMSELVES \u2014 never roleplay them inside your own host.",
     inputSchema: {
       type: "object",
       properties: {
@@ -23133,11 +23139,20 @@ var toolDefinitions = [
   },
   {
     name: "wait_for_email",
-    description: "Wait for a new email or task notification using push notifications (SSE). Blocks until an email arrives, a task is assigned to you, or timeout is reached. Much more efficient than polling \u2014 use this when waiting for a reply or a task from another agent.",
+    description: 'Block until a matching email (or task) lands in your inbox. Push-based (SSE) \u2014 far more efficient than polling. Supports filtering by sender, subject substring, thread (In-Reply-To), or a participants list. The single-most-useful tool for thread-based coordination: send a kickoff email CC\'ing your team, then `wait_for_email({ subject: "<core thread subject>" })` to wake on the first reply. Non-matching events that arrive during the wait are ignored \u2014 you only resume when something you asked for shows up (or timeout).',
     inputSchema: {
       type: "object",
       properties: {
-        timeout: { type: "number", description: "Max seconds to wait (default: 120, max: 300)" }
+        timeout: { type: "number", description: "Max seconds to wait (default: 120, max: 300)" },
+        from: { type: "string", description: 'Only resume on an email FROM this address (case-insensitive substring match on the bare address \u2014 "orion" matches "orion@localhost").' },
+        subject: { type: "string", description: `Only resume on an email whose subject contains this string (case-insensitive). The thread's core subject works \u2014 "Build a small game" matches "Re: Build a small game".` },
+        inReplyTo: { type: "string", description: "Only resume on an email whose In-Reply-To header equals this Message-ID. Most precise thread filter \u2014 use when you have the exact Message-ID of the message you expect a reply to." },
+        participants: {
+          type: "array",
+          items: { type: "string" },
+          description: `Only resume on an email from ANY of these addresses (case-insensitive). Use this to wait for any teammate's reply, e.g. ["vesper@localhost", "orion@localhost"].`
+        },
+        includeTasks: { type: "boolean", description: "Include task-assignment events as matches (default: true). Set false if you only care about email." }
       }
     }
   },
@@ -23248,7 +23263,7 @@ var toolDefinitions = [
   },
   {
     name: "call_agent",
-    description: "Synchronous RPC: assign a task to another agent, notify them via email (wakes wait_for_email), and wait for the result. Times out after specified duration.",
+    description: `Synchronous RPC to delegate work to another AgenticMail agent. Pipeline: the task is queued in AgenticMail, the target agent processes it AS THEMSELVES (under their real identity, mailbox, persona, and audit trail), and the structured result returns into your call. THIS IS HOW MULTI-AGENT COORDINATION IS SUPPOSED TO WORK from any MCP host. Do not, instead, spawn one of your host's native sub-agents and tell it to "act as <target>" \u2014 that produces output under your identity, never touches the target's inbox, and skips their persona. Times out after the specified duration (default 180s, max 300s).`,
     inputSchema: {
       type: "object",
       properties: {
@@ -24237,6 +24252,32 @@ ${lines.join("\n")}`;
     }
     case "wait_for_email": {
       const timeoutSec = Math.min(Math.max(Number(args2.timeout) || 120, 5), 300);
+      const includeTasks = args2.includeTasks !== false;
+      const fromFilter = typeof args2.from === "string" ? args2.from.trim().toLowerCase() : "";
+      const subjectFilter = typeof args2.subject === "string" ? args2.subject.trim().toLowerCase() : "";
+      const inReplyToFilter = typeof args2.inReplyTo === "string" ? args2.inReplyTo.trim() : "";
+      const participantsRaw = Array.isArray(args2.participants) ? args2.participants : [];
+      const participantsFilter = participantsRaw.filter((p) => typeof p === "string" && p.trim().length > 0).map((p) => p.trim().toLowerCase());
+      const hasAnyFilter = !!(fromFilter || subjectFilter || inReplyToFilter || participantsFilter.length);
+      const bareAddr = (s) => {
+        if (!s) return "";
+        const m = s.match(/<([^>]+)>/);
+        return (m ? m[1] : s).trim().toLowerCase();
+      };
+      const emailMatches = (email2) => {
+        if (!hasAnyFilter) return true;
+        const fromAddr = bareAddr(email2?.from?.[0]?.address ?? "");
+        const subj = String(email2?.subject ?? "").toLowerCase();
+        const ire = String(email2?.inReplyTo ?? "").trim();
+        if (fromFilter && !fromAddr.includes(fromFilter)) return false;
+        if (subjectFilter && !subj.includes(subjectFilter)) return false;
+        if (inReplyToFilter && ire !== inReplyToFilter) return false;
+        if (participantsFilter.length > 0) {
+          const ok = participantsFilter.some((p) => fromAddr.includes(p));
+          if (!ok) return false;
+        }
+        return true;
+      };
       const controller = new AbortController();
       const timer = setTimeout(() => controller.abort(), timeoutSec * 1e3);
       try {
@@ -24246,24 +24287,38 @@ ${lines.join("\n")}`;
         });
         if (!res.ok) {
           clearTimeout(timer);
-          const search = await apiRequest("POST", "/mail/search", { seen: false });
+          const searchBody = { seen: false };
+          if (fromFilter) searchBody.from = fromFilter;
+          if (subjectFilter) searchBody.subject = subjectFilter;
+          const search = await apiRequest("POST", "/mail/search", searchBody);
           const uids = search?.uids ?? [];
-          if (uids.length > 0) {
-            const email2 = await apiRequest("GET", `/mail/messages/${uids[0]}`);
+          for (const uid of [...uids].reverse()) {
+            const email2 = await apiRequest("GET", `/mail/messages/${uid}`);
+            if (!email2 || !emailMatches(email2)) continue;
+            const fromAddr = bareAddr(email2.from?.[0]?.address);
             return JSON.stringify({
               arrived: true,
               mode: "poll-fallback",
-              email: email2 ? {
-                uid: uids[0],
-                from: email2.from?.[0]?.address ?? "",
+              eventType: "email",
+              email: {
+                uid,
+                from: fromAddr,
+                fromName: email2.from?.[0]?.name ?? fromAddr,
                 subject: email2.subject ?? "(no subject)",
                 date: email2.date,
-                preview: (email2.text ?? "").slice(0, 300)
-              } : null,
+                preview: (email2.text ?? "").slice(0, 300),
+                messageId: email2.messageId,
+                inReplyTo: email2.inReplyTo,
+                isInterAgent: fromAddr.endsWith("@localhost")
+              },
               totalUnread: uids.length
             });
           }
-          return JSON.stringify({ arrived: false, reason: "SSE unavailable and no unread emails", timedOut: true });
+          return JSON.stringify({
+            arrived: false,
+            reason: hasAnyFilter ? "SSE unavailable and no unread emails match the filters" : "SSE unavailable and no unread emails",
+            timedOut: true
+          });
         }
         if (!res.body) {
           clearTimeout(timer);
@@ -24272,6 +24327,7 @@ ${lines.join("\n")}`;
         const reader = res.body.getReader();
         const decoder = new TextDecoder();
         let buffer = "";
+        let skipped = 0;
         try {
           while (true) {
             const { done, value } = await reader.read();
@@ -24282,54 +24338,65 @@ ${lines.join("\n")}`;
               const frame = buffer.slice(0, boundary);
               buffer = buffer.slice(boundary + 2);
               for (const line of frame.split("\n")) {
-                if (line.startsWith("data: ")) {
+                if (!line.startsWith("data: ")) continue;
+                let event;
+                try {
+                  event = JSON.parse(line.slice(6));
+                } catch {
+                  continue;
+                }
+                if (event.type === "task" && event.taskId) {
+                  if (!includeTasks || hasAnyFilter) {
+                    skipped++;
+                    continue;
+                  }
+                  clearTimeout(timer);
                   try {
-                    const event = JSON.parse(line.slice(6));
-                    if (event.type === "task" && event.taskId) {
-                      clearTimeout(timer);
-                      try {
-                        reader.cancel();
-                      } catch {
-                      }
-                      return JSON.stringify({
-                        arrived: true,
-                        mode: "push",
-                        eventType: "task",
-                        task: {
-                          taskId: event.taskId,
-                          taskType: event.taskType,
-                          description: event.task,
-                          from: event.from
-                        },
-                        hint: 'You have a new task. Use check_tasks(action="pending") to see and claim it.'
-                      });
-                    }
-                    if (event.type === "new" && event.uid) {
-                      clearTimeout(timer);
-                      try {
-                        reader.cancel();
-                      } catch {
-                      }
-                      const email2 = await apiRequest("GET", `/mail/messages/${event.uid}`);
-                      const fromAddr = email2?.from?.[0]?.address ?? "";
-                      return JSON.stringify({
-                        arrived: true,
-                        mode: "push",
-                        eventType: "email",
-                        email: email2 ? {
-                          uid: event.uid,
-                          from: fromAddr,
-                          fromName: email2.from?.[0]?.name ?? fromAddr,
-                          subject: email2.subject ?? "(no subject)",
-                          date: email2.date,
-                          preview: (email2.text ?? "").slice(0, 300),
-                          messageId: email2.messageId,
-                          isInterAgent: fromAddr.endsWith("@localhost")
-                        } : null
-                      });
-                    }
+                    reader.cancel();
                   } catch {
                   }
+                  return JSON.stringify({
+                    arrived: true,
+                    mode: "push",
+                    eventType: "task",
+                    task: {
+                      taskId: event.taskId,
+                      taskType: event.taskType,
+                      description: event.task,
+                      from: event.from
+                    },
+                    hint: 'You have a new task. Use check_tasks(action="pending") to see and claim it.'
+                  });
+                }
+                if (event.type === "new" && event.uid) {
+                  const email2 = await apiRequest("GET", `/mail/messages/${event.uid}`);
+                  if (!email2 || !emailMatches(email2)) {
+                    skipped++;
+                    continue;
+                  }
+                  clearTimeout(timer);
+                  try {
+                    reader.cancel();
+                  } catch {
+                  }
+                  const fromAddr = bareAddr(email2.from?.[0]?.address);
+                  return JSON.stringify({
+                    arrived: true,
+                    mode: "push",
+                    eventType: "email",
+                    skippedEvents: skipped,
+                    email: {
+                      uid: event.uid,
+                      from: fromAddr,
+                      fromName: email2.from?.[0]?.name ?? fromAddr,
+                      subject: email2.subject ?? "(no subject)",
+                      date: email2.date,
+                      preview: (email2.text ?? "").slice(0, 300),
+                      messageId: email2.messageId,
+                      inReplyTo: email2.inReplyTo,
+                      isInterAgent: fromAddr.endsWith("@localhost")
+                    }
+                  });
                 }
               }
             }
@@ -24341,11 +24408,20 @@ ${lines.join("\n")}`;
           }
         }
         clearTimeout(timer);
-        return JSON.stringify({ arrived: false, reason: "SSE connection closed", timedOut: false });
+        return JSON.stringify({ arrived: false, reason: "SSE connection closed", timedOut: false, skippedEvents: skipped });
       } catch (err) {
         clearTimeout(timer);
         if (err.name === "AbortError") {
-          return JSON.stringify({ arrived: false, reason: `No email received within ${timeoutSec}s`, timedOut: true });
+          return JSON.stringify({
+            arrived: false,
+            reason: hasAnyFilter ? `Timed out after ${timeoutSec}s \u2014 no matching email arrived (filters: ${[
+              fromFilter && `from~="${fromFilter}"`,
+              subjectFilter && `subject~="${subjectFilter}"`,
+              inReplyToFilter && `inReplyTo="${inReplyToFilter}"`,
+              participantsFilter.length && `participants=${JSON.stringify(participantsFilter)}`
+            ].filter(Boolean).join(", ")})` : `No email received within ${timeoutSec}s`,
+            timedOut: true
+          });
         }
         return JSON.stringify({ arrived: false, reason: err.message });
       }
@@ -24902,12 +24978,124 @@ function jsonSchemaToZod(schema, topLevel = false) {
   }
   return schema.description ? result.describe(schema.description) : result;
 }
+var SERVER_INSTRUCTIONS = [
+  "\u{1F380} AgenticMail \u2014 multi-agent email + SMS infrastructure.",
+  "",
+  "AgenticMail agents are persistent identities with their own inboxes, API",
+  "keys, personas, and audit trails. They coordinate the way humans do: in",
+  "email threads, with every participant CC'd, taking turns implicitly from",
+  "context. Address other agents through AgenticMail's own primitives \u2014",
+  "never roleplay them inside your host's native sub-agent / sub-task tool.",
+  "",
+  "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550",
+  "PREFERRED PATTERN: Single thread, CC everyone, agents take turns",
+  "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550",
+  "",
+  "This is how a human boss coordinates a small team \u2014 and it is the right",
+  "pattern for multi-agent work. One email thread is the shared workspace.",
+  "",
+  "1. Decide who participates.",
+  "     \u2022 `list_agents()` \u2014 find existing identities",
+  "     \u2022 `create_account({ name, role, ... })` \u2014 spawn fresh ones",
+  "",
+  "2. Send ONE kickoff email with all participants on To / CC:",
+  "",
+  "       send_email({",
+  '         to: "vesper@localhost",                         // primary owner of step 1',
+  '         cc: "orion@localhost, claudecode@localhost",     // teammates + yourself',
+  '         subject: "Build a small terminal game",',
+  "         text: [",
+  '           "Team \u2014",',
+  '           "",',
+  '           "Vesper, please design a minimal terminal game (under ~80 LOC).",',
+  '           "Reply-all with the design doc when ready.",',
+  '           "",',
+  '           "Orion, once Vesper signs off, implement it and reply-all with the code.",',
+  '           "",',
+  '           "I (the host) will watch the thread and step in if needed.",',
+  '         ].join("\\n"),',
+  "       })",
+  "",
+  "   The mail server pushes a wake-up to every local recipient simultaneously.",
+  "   Each agent reads the thread, decides if it is THEIR turn, and either",
+  "   reply-all's to contribute or stays silent. Vesper goes first because she",
+  "   was named first; Orion stays silent until Vesper hands off; you (the",
+  "   host) see every reply land in your bridge inbox.",
+  "",
+  "3. Watch progress from the HOST session. The bridge inbox is yours to",
+  "   monitor \u2014 the dispatcher does NOT spawn an autonomous worker for the",
+  "   bridge (that would compete with you). Pick your monitoring style:",
+  "     \u2022 `wait_for_email({ timeout? })` \u2014 blocks the current turn (push-",
+  "         based, SSE-driven) until the next event lands in your inbox.",
+  '         Best when you want a single-shot "ping me when anything new',
+  '         arrives". Pair with `read_email` afterwards.',
+  "     \u2022 `list_inbox()` + `read_email({ uid })` \u2014 explicit poll. Best when",
+  "         the user is actively driving the conversation turn-by-turn.",
+  "     \u2022 `search_emails({ subject })` \u2014 load the full thread at any point.",
+  "   To unblock a stuck agent or change direction, just reply-all into the",
+  "   same thread.",
+  "",
+  '4. Done when the last hand-off (or an explicit "complete" message) lands',
+  "   in your inbox. Show the result to the user.",
+  "",
+  "Why this is right:",
+  "  \u2022 Every agent has FULL context every time they wake (they read the thread).",
+  "  \u2022 Turn-taking is implicit; no scheduler, no RPC ceremony.",
+  "  \u2022 The thread is searchable history. The host (you) sees everything.",
+  "  \u2022 Bringing in another teammate later is just adding them to CC.",
+  "",
+  "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550",
+  "When to use one-shot RPC instead",
+  "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550",
+  "",
+  "`call_agent({ target, task, timeout? })` is still the right tool when:",
+  "  \u2022 You need ONE structured answer from ONE agent and no multi-step work.",
+  "  \u2022 You need the result inline in your current call (not async).",
+  '  \u2022 The work is short and there is no useful "thread" to share.',
+  "",
+  "For multi-step / multi-agent coordination \u2014 use the thread pattern above.",
+  "For fire-and-forget handoffs to a single agent \u2014 `message_agent` is fine.",
+  "",
+  "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550",
+  "What NOT to do (regardless of host \u2014 Claude Code, ChatGPT, Cursor, Grok)",
+  "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550",
+  "",
+  "\u2717 Do NOT spawn a native sub-agent / sub-task tool of your host and tell",
+  '  it to "act as Vesper" / "write as Orion". That produces output under',
+  "  YOUR identity, never reaches the named agent's inbox, and bypasses",
+  "  their persona, signatures, outbound guard, and audit trail.",
+  "\u2717 Do NOT compose an agent's reply yourself in the host session and then",
+  "  `send_email` it on their behalf. Let the real agent reply from their",
+  "  own mailbox (via the thread pattern, or via call_agent for RPC).",
+  '\u2717 Do NOT pass `_account: "<other-agent>"` to act AS another agent. That',
+  "  falsifies the From: header.",
+  '\u2717 Do NOT serialise the work yourself ("first I call_agent Vesper, get her',
+  '  result, then I call_agent Orion with her result"). That works but it',
+  "  is fragile, slow, and burns one full Claude turn per hop. The thread",
+  "  pattern lets the agents drive their own handoffs.",
+  "",
+  "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550",
+  "Identity (`_account`) & tool surface",
+  "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550",
+  "",
+  'Every tool call accepts optional `_account: "<agent-name>"` to scope the',
+  "call to a specific identity. From the host, omit it to use the bridge",
+  "identity, or pass it to read/write a specific agent's mailbox directly.",
+  'From inside an agent\'s own context, ALWAYS pass `_account: "<self>"`.',
+  "",
+  "Tool surface: ~62 tools across email, SMS, contacts, drafts, templates,",
+  "rules, tags, search, scheduling, RPC. Only ~10 are pre-loaded; the rest",
+  "are reachable via `request_tools` (discover) + `invoke` (call)."
+].join("\n");
 function createMcpServer() {
-  const server = new McpServer({
-    name: "\u{1F380} AgenticMail",
-    version: "0.2.27",
-    description: "\u{1F380} AgenticMail \u2014 Email infrastructure for AI agents. By Ope Olatunji (https://github.com/agenticmail/agenticmail)"
-  });
+  const server = new McpServer(
+    {
+      name: "\u{1F380} AgenticMail",
+      version: "0.2.30",
+      description: "\u{1F380} AgenticMail \u2014 Email infrastructure for AI agents. By Ope Olatunji (https://github.com/agenticmail/agenticmail)"
+    },
+    { instructions: SERVER_INSTRUCTIONS }
+  );
   const ACCOUNT_PROP = {
     type: "string",
     description: 'Optional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/mcp",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "mcpName": "io.github.agenticmail/mcp",
   "description": "MCP server for AgenticMail — give any AI client real email and SMS capabilities",
   "type": "module",