@softeria/ms-365-mcp-server 0.150.3 → 0.151.0

package/README.md

@@ -598,6 +598,15 @@ When running as an MCP server, the following options can be used:
 --http [port]     Use Streamable HTTP transport instead of stdio (optionally specify port, default: 3000)
                   Starts Express.js server with MCP endpoint at /mcp
 --enable-auth-tools Enable login/logout tools when using HTTP mode (disabled by default in HTTP mode)
+--enable-attachment-urls Let get-download-url mint a server-served URL for byte resources Graph
+                  exposes no pre-authenticated URL for (see "Server-Minted Attachment URLs")
+--attachment-port <port> Serve /attachment on its own listener on this port instead of on the
+                  MCP app, so a fetcher that can read attachments cannot also reach /mcp
+                  (requires --enable-attachment-urls; see "Splitting the attachment listener")
+--attachment-host <host> Interface the --attachment-port listener binds. Defaults to whatever
+                  --http bound, which with a wildcard --http leaves BOTH ports on every
+                  interface and so isolates nothing — set this to make the split real
+                  (requires --attachment-port; see "Splitting the attachment listener")
 --no-dynamic-registration Disable OAuth Dynamic Client Registration (enabled by default in HTTP mode)
 --enabled-tools <pattern> Filter tools using regex pattern (e.g., "excel|contact" to enable Excel and Contact tools)
 --preset <names>  Use preset tool categories (comma-separated). See "Tool Presets" section above
@@ -623,6 +632,8 @@ Environment variables:
 - `MS365_MCP_MESSAGE_SIGNOFF_SUFFIX=<text>`: Signoff appended to outgoing messages. Default: none. CLI equivalent: `--message-signoff-suffix <text>`. `--no-message-signoff` disables both (see Message Signoff below)
 - `MS365_MCP_RATE_LIMIT_DISABLED=true|1`: Disable per-IP rate limiting in HTTP mode (default: enabled — 30 req/min on `/authorize`, `/token`, `/register`; 120 req/min on `/mcp`)
 - `MS365_MCP_TRUST_PROXY_HOPS=<n>`: Number of trusted reverse-proxy hops in HTTP mode (default `1`). Accurate per-IP rate limiting depends on this matching your deployment — set to the number of proxies in front of the server, `0` to use the raw socket peer IP, or a comma-separated subnet list
+- `MS365_MCP_ATTACHMENT_PORT=<port>`: Serve the attachment route on its own listener on this port (alternative to --attachment-port; requires `--enable-attachment-urls`)
+- `MS365_MCP_ATTACHMENT_HOST=<host>`: Interface the `MS365_MCP_ATTACHMENT_PORT` listener binds (alternative to --attachment-host; requires `--attachment-port`). Defaults to the host `--http` bound — which for a wildcard `--http` means both ports answer everywhere and the port split isolates nothing. See "Splitting the attachment listener"
 - `MS365_MCP_CLOUD_TYPE=global|china`: Microsoft cloud environment (alternative to --cloud flag)
 - `LOG_LEVEL`: Set logging level (default: 'info')
 - `SILENT=true|1`: Disable console output
@@ -638,6 +649,167 @@ Environment variables:
 - `MS365_MCP_EXPECTED_USERNAME`: Require local MSAL auth to use this Microsoft account username (case-insensitive; CLI flag takes precedence)
 - `MS365_MCP_EXPECTED_HOME_ACCOUNT_ID`: Require local MSAL auth to use this exact MSAL homeAccountId (CLI flag takes precedence)
 
+## Server-Minted Attachment URLs
+
+`get-download-url` returns Microsoft's own pre-authenticated `@microsoft.graph.downloadUrl`
+for OneDrive and SharePoint items. Graph publishes no such URL for **mail and calendar
+attachments, meeting recordings, or any other `/$value` byte endpoint** — for those, the
+only way to read the bytes has been `download-bytes`, which returns base64 into the
+agent's context. A 73 KB, 3-page PDF costs about 24,500 tokens that way, and the model
+cannot parse them anyway.
+
+`--enable-attachment-urls` (HTTP mode, off by default) closes that gap. When Graph has no
+URL of its own, `get-download-url` mints one this server serves:
+
+```
+GET /attachment?t=<ticket>&dgk=<key-id>&dgx=<expiry>&dgs=<signature>
+```
+
+The ticket is 32 bytes of CSPRNG output, **single-use**, memory-only, and expires after
+`MS365_MCP_ATTACHMENT_URL_TTL_S` seconds. Redeeming it streams the Graph bytes with this
+server's own token; the fetcher sends no Authorization header and holds no Microsoft
+credential.
+
+**This grants no authority the calling agent did not already have.** Every target that can
+be minted is one `download-bytes` would fetch for the same caller on the same account. The
+ticket only moves those bytes out of the context window and into a direct transfer.
+
+### Configuration
+
+```
+MS365_MCP_ATTACHMENT_URL_BASE=http://m365-mcp:3000   # required
+MS365_MCP_ATTACHMENT_URL_KEY=...                     # required (or _KEY_FILE=/path)
+MS365_MCP_ATTACHMENT_URL_KEY_ID=1                    # optional, default 1
+MS365_MCP_ATTACHMENT_URL_TTL_S=120                   # optional, default 120, max 300
+```
+
+`MS365_MCP_ATTACHMENT_URL_BASE` is deliberately **not** `MS365_MCP_PUBLIC_URL`: that one is
+browser-facing, for OAuth redirects, while this is fetched server-to-server and is
+commonly a container address. A missing or malformed setting fails at startup rather than
+per-request — a signing feature that comes up without a key would mint URLs nothing can
+verify, silently.
+
+### Splitting the attachment listener
+
+By default `/attachment` is served by the same Express app, on the same port, as `/mcp`.
+That is fine when callers are authenticated by a bearer token, and it is a problem when
+they are not. Under `--trust-proxy-auth` the MCP endpoint reads no `Authorization` header
+at all — **reachability is the authentication** — so one shared port means the sidecar you
+allowed through in order to fetch a PDF can also call every tool on the server.
+
+`--attachment-port <port>` (or `MS365_MCP_ATTACHMENT_PORT`) moves the route onto a listener
+of its own, and `--attachment-host <host>` (or `MS365_MCP_ATTACHMENT_HOST`) says which
+interface that listener binds:
+
+```
+ms-365-mcp-server --http 10.89.0.2:3000 --trust-proxy-auth \
+                  --enable-attachment-urls \
+                  --attachment-port 3001 --attachment-host 10.89.1.2
+MS365_MCP_ATTACHMENT_URL_BASE=http://m365-mcp:3001   # note: the attachment port
+```
+
+- `GET /attachment` on **3001** works; on 3000 it is **404** — the MCP app never mounts it.
+- `/mcp` on **3001** is **404**, as is everything else: the second app has the attachment
+  route and nothing more. No OAuth router, no body parsers, no CORS, no health check.
+- The 60 req/min limiter that guards the route follows it onto the new listener.
+- `trust proxy` is **off** on the attachment listener (and `MS365_MCP_TRUST_PROXY_HOPS` is
+  not read for it), unlike the MCP listener, which trusts one hop. This port is meant to be
+  dialled directly on a container network; honouring `X-Forwarded-For` on the server's one
+  uncredentialed surface would let a caller choose its own rate-limit bucket.
+
+The flag requires `--enable-attachment-urls` and refuses to start without it — on its own
+it would open a port with nothing on it while the operator believed the surfaces were
+separated. In stdio mode it warns and is ignored, like the flag it depends on.
+`--attachment-host` likewise requires `--attachment-port`: alone it would name an interface
+for a listener that does not exist.
+
+#### Two ports are not two surfaces unless they bind two interfaces
+
+**This is the part that decides whether any of the above is worth anything.** Read it
+before you deploy the split.
+
+`--attachment-port` on its own separates the two surfaces _inside the process_. It does not
+separate them _on the network_. Without `--attachment-host` the attachment listener inherits
+whatever host `--http` bound — and `--http 3000`, the common form, names no host at all, so
+Node binds the wildcard and **both** ports answer on **every** interface:
+
+```
+ms-365-mcp-server --http 3000 --trust-proxy-auth \
+                  --enable-attachment-urls --attachment-port 3001   # NOT isolated
+```
+
+Container networks grant a peer every port on a container, not one port. Put a
+document-conversion sidecar on a shared bridge so it can fetch `/attachment` on 3001, and
+that same sidecar can dial `:3000/mcp` — which under `--trust-proxy-auth` reads no
+`Authorization` header at all and hands back the full tool catalogue. Nothing fails, nothing
+is logged as an error, and the config looks exactly like the isolated one.
+
+To make it real, give the two listeners **different addresses**, and put only the attachment
+address on the network the fetcher is on:
+
+```yaml
+# docker compose — the MCP port on the agent's own bridge, the attachment port on the
+# bridge shared with the converter. The converter can reach 3001 and cannot route to 3000.
+services:
+  m365-mcp:
+    networks: { agent-net: { ipv4_address: 10.89.0.2 }, convert-net: { ipv4_address: 10.89.1.2 } }
+    command: >
+      --http 10.89.0.2:3000 --trust-proxy-auth
+      --enable-attachment-urls
+      --attachment-port 3001 --attachment-host 10.89.1.2
+  docglean:
+    networks: [convert-net]
+```
+
+The MCP port is then unreachable from `convert-net` **by binding** — there is no socket
+listening on that interface — rather than by a firewall rule that has to keep matching.
+
+The server warns at startup if you run `--trust-proxy-auth` with `--attachment-port` while
+both listeners still answer on a common interface (either sharing an address, or either one
+on the wildcard). Both bound addresses are logged, read back from the socket rather than
+from the flags, so `Server listening on …` and `Attachment listener on …` can be compared
+directly.
+
+`--attachment-host` takes a bare IPv4 address, IPv6 address (bracketed `[::1]` or bare
+`::1`) or hostname. It is refused rather than coerced — `--attachment-host 10.0.0.5:3001`
+is an error naming `--attachment-port`, not a bind to something else. Note that
+`MS365_MCP_ATTACHMENT_URL_BASE` still must not be an IPv6 literal (the URL signature covers
+the host and the two implementations normalise IPv6 differently); if you bind the listener
+to an IPv6 address, name it in the base by hostname.
+
+Point `MS365_MCP_ATTACHMENT_URL_BASE` at the attachment port. The server cannot check this
+for you: the base is usually a container name on a network this process cannot resolve, so
+a wrong port here shows up as a fetch failure in the sidecar, not an error here. Both the
+base and the bound port are logged at startup, one line apart, for exactly that comparison.
+
+### The signature, and who checks what
+
+`dgk`/`dgx`/`dgs` are **not** checked by this server on redemption, and that is deliberate.
+They exist for the fetcher: a document-conversion sidecar that refuses to dial a private
+address unless the URL carries a valid HMAC from an origin it has been configured to trust.
+What authorises redemption _here_ is the ticket. Verifying the signature on the way back in
+would prove only that we minted the URL — which the ticket already proves — while coupling
+redemption to the sidecar's clock and to the key surviving a restart.
+
+The wire format is [docglean-mcp](https://github.com/msoukhomlinov/docglean-mcp)'s
+`signing.py` (`canonical_string`), and `src/lib/url-signing.ts` is a port of it. The
+canonical string is `\n`-joined: `v1`, lowercased scheme, lowercased host, the port always
+explicit, the path, the remaining query with `dgk`/`dgx`/`dgs` removed and the rest sorted
+and re-encoded, and the expiry. The test vectors in
+`test/attachment-url-signing.test.ts` were verified against the Python implementation byte
+for byte — three places where the obvious JavaScript disagrees with Python (`!*'()`
+escaping, `+` decoding as a space, and code-point vs UTF-16 sort order) are why that check
+exists rather than being assumed.
+
+The ticket travels in the **query, not the path**, because the verifying sidecar keeps a
+fetched URL's path in its error messages and strips the query.
+
+### Not available in OAuth/OBO mode
+
+Identity there arrives per request on the caller's `Authorization` header, and a ticket is
+redeemed later by a fetcher that sends none. Minting refuses with an explanation rather
+than producing a URL that always fails.
+
 ## Token Storage
 
 Authentication tokens are stored in an encrypted file (AES-256-GCM). Only the 32-byte encryption key goes to the OS credential store via keytar.

package/dist/attachment-route.js

@@ -0,0 +1,112 @@
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import logger from "./logger.js";
+import {
+  isPlainGraphPath,
+  TICKET_PARAM
+} from "./lib/attachment-tickets.js";
+const NOT_FOUND_BODY = "Not found";
+function forceAttachment(header) {
+  if (!header) return "attachment";
+  const params = [];
+  let current = "";
+  let quoted = false;
+  for (let i = 0; i < header.length; i += 1) {
+    const char = header[i];
+    if (quoted && char === "\\" && i + 1 < header.length) {
+      current += char + header[i + 1];
+      i += 1;
+      continue;
+    }
+    if (char === '"') quoted = !quoted;
+    else if (char === ";" && !quoted) {
+      params.push(current);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  params.push(current);
+  let filename;
+  let extended;
+  for (const param of params.slice(1)) {
+    const eq = param.indexOf("=");
+    if (eq === -1) continue;
+    const name = param.slice(0, eq).trim().toLowerCase();
+    const value = Array.from(param.slice(eq + 1).trim()).filter((char) => {
+      const code = char.charCodeAt(0);
+      return code > 31 && code !== 127;
+    }).join("");
+    if (!value) continue;
+    if (name === "filename*") extended = value;
+    else if (name === "filename") filename = value;
+  }
+  if (extended) return `attachment; filename*=${extended}`;
+  if (filename) return `attachment; filename=${filename}`;
+  return "attachment";
+}
+function refuse(res) {
+  res.status(404).type("text/plain").send(NOT_FOUND_BODY);
+}
+function createAttachmentHandler(deps) {
+  return async (req, res) => {
+    if (req.method !== "GET") {
+      res.setHeader("allow", "GET");
+      res.status(405).type("text/plain").send("Method not allowed");
+      return;
+    }
+    const raw = req.query[TICKET_PARAM];
+    if (typeof raw !== "string" || raw.length === 0) {
+      refuse(res);
+      return;
+    }
+    const ticket = deps.store.redeem(raw);
+    if (!ticket) {
+      refuse(res);
+      return;
+    }
+    if (!isPlainGraphPath(ticket.target)) {
+      logger.error("Attachment redemption refused: ticket target is not a plain Graph path");
+      refuse(res);
+      return;
+    }
+    const graphClient = deps.getGraphClient();
+    if (!graphClient) {
+      logger.error("Attachment redemption failed: Graph client is not initialised");
+      res.status(503).type("text/plain").send("Service unavailable");
+      return;
+    }
+    let stream;
+    try {
+      let accessToken;
+      if (!deps.authManager.isOAuthModeEnabled()) {
+        accessToken = await deps.authManager.getTokenForAccount(ticket.accountName);
+      }
+      stream = await graphClient.downloadStream(ticket.target, { accessToken });
+    } catch (error) {
+      logger.error(
+        `Attachment redemption failed for ${ticket.target}: ${error.message}`
+      );
+      res.status(502).type("text/plain").send("Upstream fetch failed");
+      return;
+    }
+    res.status(200);
+    res.setHeader("content-type", stream.contentType);
+    if (stream.contentLength !== null) {
+      res.setHeader("content-length", String(stream.contentLength));
+    }
+    res.setHeader("content-disposition", forceAttachment(stream.contentDisposition));
+    res.setHeader("cache-control", "no-store");
+    res.setHeader("x-content-type-options", "nosniff");
+    try {
+      await pipeline(Readable.fromWeb(stream.body), res);
+    } catch (error) {
+      logger.error(`Attachment stream aborted for ${ticket.target}: ${error.message}`);
+      res.destroy();
+    }
+  };
+}
+export {
+  createAttachmentHandler,
+  forceAttachment
+};

package/dist/cli.js

@@ -27,6 +27,15 @@ program.name("ms-365-mcp-server").description("Microsoft 365 MCP Server").versio
 ).option(
   "--enable-auth-tools",
   "Enable login/logout tools when using HTTP mode (disabled by default in HTTP mode)"
+).option(
+  "--enable-attachment-urls",
+  "HTTP mode only. Let get-download-url mint a short-TTL, single-use URL served by this server for Graph byte resources that expose no pre-authenticated URL of their own (mail and event attachments, meeting recordings, other $value endpoints). Requires MS365_MCP_ATTACHMENT_URL_BASE and MS365_MCP_ATTACHMENT_URL_KEY (or _KEY_FILE)"
+).option(
+  "--attachment-port <port>",
+  "HTTP mode only. Serve the attachment download route on its own listener on this port instead of on the MCP app, so a caller that can fetch attachments cannot also reach /mcp. Requires --enable-attachment-urls, and MS365_MCP_ATTACHMENT_URL_BASE must name this port. A separate port only isolates the two surfaces if they also bind separate interfaces \u2014 see --attachment-host. Equivalent env var: MS365_MCP_ATTACHMENT_PORT."
+).option(
+  "--attachment-host <host>",
+  "Interface the --attachment-port listener binds (IPv4, IPv6 or hostname). Defaults to whatever --http bound, which with a wildcard --http means both ports answer on every interface \u2014 so a peer allowed onto the network to fetch attachments can also reach /mcp. Bind this to the address the fetcher uses and --http to a different one to make that unreachable rather than merely un-advertised. Requires --attachment-port. Equivalent env var: MS365_MCP_ATTACHMENT_HOST."
 ).option(
   "--enabled-tools <pattern>",
   'Filter tools using regex pattern (e.g., "excel|contact" to enable Excel and Contact tools)'
@@ -127,6 +136,12 @@ function parseArgs() {
     );
     process.exit(1);
   }
+  if (options.attachmentPort === void 0 && process.env.MS365_MCP_ATTACHMENT_PORT !== void 0) {
+    options.attachmentPort = process.env.MS365_MCP_ATTACHMENT_PORT;
+  }
+  if (options.attachmentHost === void 0 && process.env.MS365_MCP_ATTACHMENT_HOST !== void 0) {
+    options.attachmentHost = process.env.MS365_MCP_ATTACHMENT_HOST;
+  }
   if (options.expectedUsername === void 0 && process.env.MS365_MCP_EXPECTED_USERNAME !== void 0) {
     options.expectedUsername = process.env.MS365_MCP_EXPECTED_USERNAME;
   }

package/dist/graph-client.js

@@ -167,6 +167,55 @@ class GraphClient {
    * memory or hit V8's max string length. Creates the file with wx + 0o600 (never
    * overwrites) and removes a partial file if the transfer fails.
    */
+  /**
+   * Fetch Graph binary content and hand back the undrained response stream.
+   *
+   * Same auth, same resilience and the same error mapping as `downloadToFile`,
+   * which is the reason this exists rather than the attachment route calling
+   * `fetch` for itself: token acquisition, the OBO/bearer context tokens, retry
+   * and the 403-scope special case are all in `performRequest`, which is
+   * private. Splitting them would give the route a second, quietly divergent
+   * copy of the auth path.
+   *
+   * The caller owns the body from here and MUST consume or cancel it -- an
+   * abandoned stream holds a socket open until the agent times out.
+   */
+  async downloadStream(endpoint, options = {}) {
+    const contextTokens = getRequestTokens();
+    const accessToken = options.accessToken ?? contextTokens?.accessToken ?? await this.authManager.getToken();
+    if (!accessToken) {
+      throw new Error("No access token available");
+    }
+    const response = await this.performRequest(endpoint, accessToken, options);
+    if (response.status === 403) {
+      const errorText = await response.text();
+      if (errorText.includes("scope") || errorText.includes("permission")) {
+        throw new Error(
+          `Microsoft Graph API scope error: ${response.status} ${response.statusText} - ${errorText}. This tool requires organization mode. Please restart with --org-mode flag.`
+        );
+      }
+      throw new Error(
+        `Microsoft Graph API error: ${response.status} ${response.statusText} - ${errorText}`
+      );
+    }
+    if (!response.ok) {
+      throw new Error(
+        `Microsoft Graph API error: ${response.status} ${response.statusText} - ${await response.text()}`
+      );
+    }
+    if (!response.body) {
+      throw new Error("Microsoft Graph returned an empty response body");
+    }
+    const rawLength = response.headers.get("content-length");
+    const decoded = response.headers.get("content-encoding") !== null;
+    const declaredLength = !decoded && rawLength !== null && /^\d+$/.test(rawLength.trim());
+    return {
+      body: response.body,
+      contentType: response.headers.get("content-type") || "application/octet-stream",
+      contentLength: declaredLength ? Number(rawLength) : null,
+      contentDisposition: response.headers.get("content-disposition")
+    };
+  }
   async downloadToFile(endpoint, destinationPath, options = {}) {
     const fileHandle = await open(destinationPath, "wx", 384);
     let completed = false;

package/dist/graph-tools.js

@@ -4,6 +4,12 @@ import logger from "./logger.js";
 import { auditLog, getUserIdentityForAudit } from "./audit-log.js";
 import { isDestructiveOperation } from "./lib/destructive-ops.js";
 import { describePathParam } from "./lib/path-params.js";
+import { getAttachmentMinting } from "./lib/attachment-minting.js";
+import {
+  buildAttachmentUrl,
+  isPlainGraphPath,
+  TicketStoreFullError
+} from "./lib/attachment-tickets.js";
 import {
   anyFieldPresent,
   isTransportEnvelope,
@@ -475,6 +481,68 @@ async function checkAccountParamInBearerMode(accountParam, authManager) {
   if (bearerIdentity && bearerIdentity.toLowerCase() === accountParam.toLowerCase()) return null;
   return `The 'account' parameter is not supported in HTTP/OAuth mode: every request uses the identity of the connecting client's bearer token` + (bearerIdentity ? ` ('${bearerIdentity}')` : "") + `, so account switching is not possible. To act as '${accountParam}', reconnect the MCP client authenticated as that account, or run the server in stdio mode (or HTTP with --trust-proxy-auth) where cached accounts are available.`;
 }
+async function mintDownloadUrl(target, accountParam, authManager) {
+  const minting = getAttachmentMinting();
+  if (!minting) return null;
+  if (authManager?.isOAuthModeEnabled() || getRequestTokens()) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: "Server-minted download URLs are unavailable when Graph identity comes from the request (OAuth, OBO, or bearer mode): the URL is redeemed later without an Authorization header, so the bytes would be fetched as a different identity than the one that asked for them. Use download-bytes."
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+  const accountModeError = await checkAccountParamInBearerMode(accountParam, authManager);
+  if (accountModeError) {
+    return {
+      content: [{ type: "text", text: JSON.stringify({ error: accountModeError }) }],
+      isError: true
+    };
+  }
+  if (!isPlainGraphPath(target)) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: 'target must be a plain relative Graph path: no fragment, no query, no "." or ".." segments, and no percent-encoded separators.'
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+  let ticket;
+  try {
+    ticket = minting.store.mint(target, accountParam);
+  } catch (error) {
+    if (error instanceof TicketStoreFullError) {
+      return {
+        content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+        isError: true
+      };
+    }
+    throw error;
+  }
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({
+          downloadUrl: buildAttachmentUrl(minting.config, ticket.id),
+          expiresAt: new Date(ticket.expiresAtMs).toISOString(),
+          singleUse: true,
+          note: "Served by this server, not by Microsoft Graph. Valid for one fetch until it expires."
+        })
+      }
+    ]
+  };
+}
 const UTILITY_TOOLS = [
   {
     name: "parse-teams-url",
@@ -719,7 +787,7 @@ const UTILITY_TOOLS = [
     method: "GET",
     path: "tool:get-download-url",
     searchKeywords: "download file download drive file download onedrive file sharepoint file download large drive file large sharepoint file large file out-of-band download pre-authenticated url",
-    description: "Resolve a short-lived, pre-authenticated download URL for Microsoft Graph binary content that exposes one (drive/SharePoint file content). The returned URL streams the bytes with NO Authorization header, so the client can fetch it straight to disk (e.g. curl) without round-tripping base64 through the agent context. Prefer this over download-bytes for any file above a few KB or any bulk download. Returns { downloadUrl, name?, size?, contentType? }. NOTE: mail file attachments (/messages/{id}/attachments/{id}/$value) and meeting recordings do NOT expose a pre-authenticated URL \u2014 Graph offers no such link for them; use download-bytes for small ones.",
+    description: "Resolve a short-lived, pre-authenticated download URL for Microsoft Graph binary content that exposes one (drive/SharePoint file content). The returned URL streams the bytes with NO Authorization header, so the client can fetch it straight to disk (e.g. curl) without round-tripping base64 through the agent context. Prefer this over download-bytes for any file above a few KB or any bulk download. Returns { downloadUrl, name?, size?, contentType? }. Mail file attachments (/messages/{id}/attachments/{id}/$value), meeting recordings and other $value byte endpoints have no pre-authenticated URL from Graph itself, but call this tool for them anyway: a server running with --enable-attachment-urls mints its own single-use URL for them, and one without it answers with the reason and points at download-bytes.",
     readOnlyHint: true,
     openWorldHint: true,
     buildSchema: (ctx) => {
@@ -778,6 +846,8 @@ const UTILITY_TOOLS = [
       }
       const pathPart = target.replace(/\/+$/, "");
       if (/^(\/me|\/users\/[^/]+)\/messages\/[^/]+\/attachments\//.test(pathPart) || /^(\/me|\/users\/[^/]+)\/events\/[^/]+\/attachments\//.test(pathPart) || /^\/groups\/[^/]+\/messages\/[^/]+\/attachments\//.test(pathPart) || /^\/groups\/[^/]+\/events\/[^/]+\/attachments\//.test(pathPart)) {
+        const minted = await mintDownloadUrl(pathPart, accountParam, authManager);
+        if (minted) return minted;
         return {
           content: [
             {
@@ -793,6 +863,8 @@ const UTILITY_TOOLS = [
       if (/^(\/me|\/users\/[^/]+)\/onlineMeetings\/[^/]+\/recordings\/[^/]+(?:\/content)?$/.test(
         pathPart
       ) || /^\/communications\/calls\/[^/]+\/recordings\/[^/]+(?:\/content)?$/.test(pathPart)) {
+        const minted = await mintDownloadUrl(pathPart, accountParam, authManager);
+        if (minted) return minted;
         return {
           content: [
             {
@@ -806,6 +878,8 @@ const UTILITY_TOOLS = [
         };
       }
       if (pathPart.endsWith("/$value")) {
+        const minted = await mintDownloadUrl(pathPart, accountParam, authManager);
+        if (minted) return minted;
         return {
           content: [
             {
@@ -875,6 +949,8 @@ const UTILITY_TOOLS = [
         }
         const downloadUrl = item?.["@microsoft.graph.downloadUrl"];
         if (!downloadUrl) {
+          const minted = await mintDownloadUrl(`${itemPath}/content`, accountParam, authManager);
+          if (minted) return minted;
           return {
             content: [
               {

package/dist/lib/attachment-minting.js

@@ -0,0 +1,15 @@
+let current = null;
+function configureAttachmentMinting(minting) {
+  current = minting;
+}
+function getAttachmentMinting() {
+  return current;
+}
+function resetAttachmentMinting() {
+  current = null;
+}
+export {
+  configureAttachmentMinting,
+  getAttachmentMinting,
+  resetAttachmentMinting
+};

package/dist/lib/attachment-tickets.js

@@ -0,0 +1,89 @@
+import { randomBytes } from "node:crypto";
+import { ATTACHMENT_ROUTE } from "./attachment-url-config.js";
+import { signUrl } from "./url-signing.js";
+const TICKET_PARAM = "t";
+function buildAttachmentUrl(config, ticketId, nowMs = Date.now()) {
+  const url = new URL(ATTACHMENT_ROUTE, config.base);
+  url.searchParams.set(TICKET_PARAM, ticketId);
+  return signUrl(
+    url.toString(),
+    { key: config.key, keyId: config.keyId, ttlSeconds: config.ttlSeconds },
+    nowMs
+  );
+}
+const PROBE_ORIGIN = "https://graph.invalid";
+const PROBE_PREFIX = "/v1.0";
+function isPlainGraphPath(target) {
+  if (!target.startsWith("/")) return false;
+  if (target.includes("//")) return false;
+  let resolved;
+  try {
+    resolved = new URL(PROBE_ORIGIN + PROBE_PREFIX + target);
+  } catch {
+    return false;
+  }
+  return resolved.origin === PROBE_ORIGIN && resolved.search === "" && resolved.hash === "" && resolved.pathname === PROBE_PREFIX + target;
+}
+const MAX_LIVE_TICKETS = 256;
+const TICKET_BYTES = 32;
+class TicketStoreFullError extends Error {
+  constructor(limit) {
+    super(`No ticket slots available (limit ${limit}); retry once outstanding tickets expire.`);
+    this.limit = limit;
+    this.name = "TicketStoreFullError";
+  }
+}
+class AttachmentTicketStore {
+  constructor(ttlSeconds) {
+    this.ttlSeconds = ttlSeconds;
+    this.tickets = /* @__PURE__ */ new Map();
+  }
+  /** Drop every expired ticket. Called before each mint and each redemption. */
+  sweep(nowMs) {
+    for (const [id, ticket] of this.tickets) {
+      if (ticket.expiresAtMs <= nowMs) this.tickets.delete(id);
+    }
+  }
+  mint(target, accountName, nowMs = Date.now()) {
+    this.sweep(nowMs);
+    if (this.tickets.size >= MAX_LIVE_TICKETS) {
+      throw new TicketStoreFullError(MAX_LIVE_TICKETS);
+    }
+    const id = randomBytes(TICKET_BYTES).toString("base64url");
+    const expiresAtMs = nowMs + this.ttlSeconds * 1e3;
+    this.tickets.set(id, { target, accountName, expiresAtMs });
+    return { id, expiresAtMs };
+  }
+  /**
+   * Return the ticket and burn it, or undefined.
+   *
+   * One `undefined` for every failure -- unknown id, already redeemed, expired.
+   * The caller answers 404 to all three, so a probe cannot use the response to
+   * tell "never existed" from "already used", which would confirm a guessed id.
+   *
+   * The delete happens before the value is returned rather than in the caller,
+   * so an exception on the streaming path cannot leave a redeemed ticket live.
+   */
+  redeem(id, nowMs = Date.now()) {
+    this.sweep(nowMs);
+    const ticket = this.tickets.get(id);
+    if (!ticket) return void 0;
+    this.tickets.delete(id);
+    return ticket;
+  }
+  /** Live ticket count, for tests and diagnostics. Never logged with ids. */
+  size(nowMs = Date.now()) {
+    this.sweep(nowMs);
+    return this.tickets.size;
+  }
+  clear() {
+    this.tickets.clear();
+  }
+}
+export {
+  AttachmentTicketStore,
+  TICKET_PARAM,
+  TicketStoreFullError,
+  buildAttachmentUrl,
+  isPlainGraphPath
+};

package/dist/lib/attachment-url-config.js

@@ -0,0 +1,104 @@
+import { readFileSync } from "node:fs";
+const ATTACHMENT_ROUTE = "/attachment";
+const DEFAULT_TTL_SECONDS = 120;
+const MAX_TTL_SECONDS = 300;
+class AttachmentUrlConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AttachmentUrlConfigError";
+  }
+}
+const PYTHON_WHITESPACE = "	\n\v\f\r \x85\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200A\u2028\u2029\u202F\u205F\u3000";
+function pythonStrip(value) {
+  let start = 0;
+  let end = value.length;
+  while (start < end && PYTHON_WHITESPACE.includes(value[start])) start += 1;
+  while (end > start && PYTHON_WHITESPACE.includes(value[end - 1])) end -= 1;
+  return value.slice(start, end);
+}
+function readKey(env) {
+  const keyFile = env.MS365_MCP_ATTACHMENT_URL_KEY_FILE;
+  if (keyFile) {
+    try {
+      return pythonStrip(readFileSync(keyFile, "utf8"));
+    } catch {
+      throw new AttachmentUrlConfigError(
+        `MS365_MCP_ATTACHMENT_URL_KEY_FILE could not be read: ${keyFile}`
+      );
+    }
+  }
+  return env.MS365_MCP_ATTACHMENT_URL_KEY ?? "";
+}
+function loadAttachmentUrlConfig(enabled, env = process.env) {
+  if (!enabled) return null;
+  const base = env.MS365_MCP_ATTACHMENT_URL_BASE ?? "";
+  if (!base) {
+    throw new AttachmentUrlConfigError(
+      "--enable-attachment-urls requires MS365_MCP_ATTACHMENT_URL_BASE (the origin a document-conversion sidecar will fetch, e.g. http://m365-mcp:3000). This is deliberately not MS365_MCP_PUBLIC_URL: that one is browser-facing for OAuth, while this is reached server-to-server and is commonly a container address. With --attachment-port, name that port here, not the --http one: the route is not served on the MCP port at all in that mode."
+    );
+  }
+  let parsedBase;
+  try {
+    parsedBase = new URL(base);
+  } catch {
+    throw new AttachmentUrlConfigError(
+      `MS365_MCP_ATTACHMENT_URL_BASE is not a valid absolute URL: ${base}`
+    );
+  }
+  if (parsedBase.protocol !== "http:" && parsedBase.protocol !== "https:") {
+    throw new AttachmentUrlConfigError(
+      `MS365_MCP_ATTACHMENT_URL_BASE must be http or https, got ${parsedBase.protocol}`
+    );
+  }
+  if (parsedBase.hostname.startsWith("[")) {
+    throw new AttachmentUrlConfigError(
+      `MS365_MCP_ATTACHMENT_URL_BASE must not be an IPv6 literal: the URL signature covers the host, and this runtime and the verifying sidecar normalise IPv6 spellings differently, so every minted URL would be refused. Use a hostname (a container or service name) instead of ${parsedBase.hostname}.`
+    );
+  }
+  if (parsedBase.search || parsedBase.hash) {
+    throw new AttachmentUrlConfigError(
+      "MS365_MCP_ATTACHMENT_URL_BASE must not carry a query string or fragment."
+    );
+  }
+  const key = readKey(env);
+  if (!key) {
+    throw new AttachmentUrlConfigError(
+      "--enable-attachment-urls requires MS365_MCP_ATTACHMENT_URL_KEY or MS365_MCP_ATTACHMENT_URL_KEY_FILE -- the HMAC key shared with the sidecar that will verify the minted URL."
+    );
+  }
+  for (let index = 0; index < key.length; index += 1) {
+    const code = key.charCodeAt(index);
+    if (code < 32 || code === 127) {
+      throw new AttachmentUrlConfigError(
+        `The attachment URL signing key contains a control character at offset ${index} (value not shown).`
+      );
+    }
+  }
+  const keyId = env.MS365_MCP_ATTACHMENT_URL_KEY_ID || "1";
+  const ttlRaw = env.MS365_MCP_ATTACHMENT_URL_TTL_S;
+  let ttlSeconds = DEFAULT_TTL_SECONDS;
+  if (ttlRaw !== void 0 && ttlRaw !== "") {
+    if (!/^\d+$/.test(ttlRaw)) {
+      throw new AttachmentUrlConfigError(
+        `MS365_MCP_ATTACHMENT_URL_TTL_S must be a positive integer, got ${JSON.stringify(ttlRaw)}`
+      );
+    }
+    ttlSeconds = Number(ttlRaw);
+    if (ttlSeconds <= 0 || ttlSeconds > MAX_TTL_SECONDS) {
+      throw new AttachmentUrlConfigError(
+        `MS365_MCP_ATTACHMENT_URL_TTL_S must be between 1 and ${MAX_TTL_SECONDS}, got ${ttlSeconds}`
+      );
+    }
+  }
+  return {
+    base: parsedBase.origin,
+    key,
+    keyId,
+    ttlSeconds
+  };
+}
+export {
+  ATTACHMENT_ROUTE,
+  AttachmentUrlConfigError,
+  loadAttachmentUrlConfig
+};

package/dist/lib/url-signing.js

@@ -0,0 +1,81 @@
+import { createHmac } from "node:crypto";
+function quoteAll(value) {
+  return Array.from(new TextEncoder().encode(value)).map((byte) => {
+    const char = String.fromCharCode(byte);
+    if (/[A-Za-z0-9_.\-~]/.test(char)) return char;
+    return "%" + byte.toString(16).toUpperCase().padStart(2, "0");
+  }).join("");
+}
+function unquotePlus(value) {
+  const withSpaces = value.replace(/\+/g, " ");
+  const bytes = [];
+  for (let i = 0; i < withSpaces.length; i += 1) {
+    const char = withSpaces[i];
+    if (char === "%" && /^[0-9A-Fa-f]{2}$/.test(withSpaces.slice(i + 1, i + 3))) {
+      bytes.push(parseInt(withSpaces.slice(i + 1, i + 3), 16));
+      i += 2;
+      continue;
+    }
+    for (const byte of new TextEncoder().encode(char)) bytes.push(byte);
+  }
+  return new TextDecoder("utf-8", { fatal: false }).decode(new Uint8Array(bytes));
+}
+function compareByCodePoint(a, b) {
+  const left = Array.from(a);
+  const right = Array.from(b);
+  const shared = Math.min(left.length, right.length);
+  for (let i = 0; i < shared; i += 1) {
+    const diff = left[i].codePointAt(0) - right[i].codePointAt(0);
+    if (diff !== 0) return diff;
+  }
+  return left.length - right.length;
+}
+const RESERVED_PARAMS = /* @__PURE__ */ new Set(["dgk", "dgx", "dgs"]);
+function parseQsl(query) {
+  const pairs = [];
+  for (const field of query.split("&")) {
+    if (!field) continue;
+    const eq = field.indexOf("=");
+    const rawName = eq === -1 ? field : field.slice(0, eq);
+    const rawValue = eq === -1 ? "" : field.slice(eq + 1);
+    pairs.push([unquotePlus(rawName), unquotePlus(rawValue)]);
+  }
+  return pairs;
+}
+function canonicalQuery(query) {
+  const pairs = parseQsl(query).filter(([name]) => !RESERVED_PARAMS.has(name));
+  pairs.sort((a, b) => compareByCodePoint(a[0], b[0]) || compareByCodePoint(a[1], b[1]));
+  return pairs.map(([name, value]) => `${quoteAll(name)}=${quoteAll(value)}`).join("&");
+}
+function canonicalString(url, expiry) {
+  const parsed = new URL(url);
+  const scheme = parsed.protocol.replace(/:$/, "").toLowerCase();
+  const host = parsed.hostname.toLowerCase().replace(/^\[(.+)\]$/, "$1");
+  const port = parsed.port === "" ? scheme === "https" ? 443 : 80 : Number(parsed.port);
+  const path = parsed.pathname === "" ? "/" : parsed.pathname;
+  const query = canonicalQuery(parsed.search.replace(/^\?/, ""));
+  return ["v1", scheme, host, String(port), path, query, expiry].join("\n");
+}
+function digest(key, message) {
+  return createHmac("sha256", Buffer.from(key, "utf8")).update(Buffer.from(message, "utf8")).digest("base64url");
+}
+function signUrl(url, config, nowMs = Date.now()) {
+  const expiry = String(Math.floor(nowMs / 1e3) + config.ttlSeconds);
+  const signature = digest(config.key, canonicalString(url, expiry));
+  const parsed = new URL(url);
+  const kept = parseQsl(parsed.search.replace(/^\?/, "")).filter(
+    ([name]) => !RESERVED_PARAMS.has(name)
+  );
+  kept.push(["dgk", config.keyId], ["dgx", expiry], ["dgs", signature]);
+  parsed.search = kept.map(([name, value]) => `${quoteAll(name)}=${quoteAll(value)}`).join("&");
+  return parsed.toString();
+}
+export {
+  canonicalString,
+  compareByCodePoint,
+  digest,
+  parseQsl,
+  quoteAll,
+  signUrl,
+  unquotePlus
+};

package/dist/server.js

@@ -25,11 +25,16 @@ import {
   toOAuthErrorResponse
 } from "./lib/microsoft-auth.js";
 import { isAllowedRedirectUri, parseAllowlist } from "./lib/redirect-uri-validation.js";
+import { loadAttachmentUrlConfig, ATTACHMENT_ROUTE } from "./lib/attachment-url-config.js";
+import { AttachmentTicketStore } from "./lib/attachment-tickets.js";
+import { configureAttachmentMinting } from "./lib/attachment-minting.js";
+import { createAttachmentHandler } from "./attachment-route.js";
 import { getSecrets } from "./secrets.js";
 import { getCloudEndpoints } from "./cloud-config.js";
 import { requestContext } from "./request-context.js";
 import { dumpError } from "./crash-logging.js";
 import crypto from "node:crypto";
+import { isIP, isIPv6 } from "node:net";
 import OboClient from "./obo-client.js";
 function parseHttpOption(httpOption) {
   if (typeof httpOption === "boolean") {
@@ -45,12 +50,78 @@ function parseHttpOption(httpOption) {
   const port = parseInt(httpString) || 3e3;
   return { host: void 0, port };
 }
+function parseAttachmentPortOption(value) {
+  if (value === void 0 || value === null || value === "") return null;
+  const raw = String(value).trim();
+  if (!/^\d+$/.test(raw)) {
+    throw new Error(
+      `--attachment-port / MS365_MCP_ATTACHMENT_PORT must be a port number between 1 and 65535, got ${JSON.stringify(String(value))}`
+    );
+  }
+  const port = Number(raw);
+  if (port < 1 || port > 65535) {
+    throw new Error(
+      `--attachment-port / MS365_MCP_ATTACHMENT_PORT must be a port number between 1 and 65535, got ${port}`
+    );
+  }
+  return port;
+}
+const HOSTNAME_LABEL = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/;
+function isHostname(value) {
+  const name = value.endsWith(".") ? value.slice(0, -1) : value;
+  if (name.length === 0 || name.length > 253) return false;
+  return name.split(".").every((label) => label.length > 0 && label.length <= 63 && HOSTNAME_LABEL.test(label));
+}
+function parseAttachmentHostOption(value) {
+  if (value === void 0 || value === null || value === "") return null;
+  const raw = String(value).trim();
+  const reject = (reason) => {
+    throw new Error(
+      `--attachment-host / MS365_MCP_ATTACHMENT_HOST must be a bare IPv4 address, IPv6 address or hostname (${reason}), got ${JSON.stringify(String(value))}`
+    );
+  };
+  if (raw === "") reject("it is empty");
+  if (raw.startsWith("[") || raw.endsWith("]")) {
+    if (!raw.startsWith("[") || !raw.endsWith("]")) reject("unbalanced brackets");
+    const inner = raw.slice(1, -1);
+    if (!isIPv6(inner)) reject("the brackets do not contain an IPv6 address");
+    return inner;
+  }
+  if (isIP(raw) !== 0) return raw;
+  if (isHostname(raw)) return raw;
+  if (raw.includes(":")) {
+    reject("this takes a host only -- the port goes on --attachment-port");
+  }
+  return reject("not a valid address or hostname");
+}
+function isWildcardAddress(address) {
+  return address === "0.0.0.0" || address === "::" || address === "";
+}
+function formatAuthority(address, port) {
+  return isIPv6(address) ? `[${address}]:${port}` : `${address}:${port}`;
+}
+function describeBoundAddress(bound) {
+  const authority = formatAuthority(bound.address, bound.port);
+  if (isWildcardAddress(bound.address)) {
+    return { label: `all interfaces (${authority})`, authority: `localhost:${bound.port}` };
+  }
+  return { label: authority, authority };
+}
 const PKCE_MAX_AGE_MS = 60 * 60 * 1e3;
 class MicrosoftGraphServer {
   constructor(authManager, options = {}) {
     this.version = "0.0.0";
     this.multiAccount = false;
     this.accountNames = [];
+    /**
+     * Every HTTP listener `start()` opened, so `stop()` can close every one.
+     *
+     * A list rather than a field because `--attachment-port` makes it two, and an
+     * untracked listener cannot be closed at all: it holds the event loop open
+     * for the life of the process. One that is only *usually* two is worse than
+     * either, so nothing here special-cases the count.
+     */
+    this.httpServers = [];
     // Two-leg PKCE: stores client's code_challenge and server's code_verifier, keyed by OAuth state
     this.pkceStore = /* @__PURE__ */ new Map();
     this.authManager = authManager;
@@ -171,6 +242,28 @@ class MicrosoftGraphServer {
     if (this.options.readOnly) {
       logger.info("Server running in READ-ONLY mode. Write operations are disabled.");
     }
+    if (this.options.enableAttachmentUrls && !this.options.http) {
+      logger.warn(
+        "--enable-attachment-urls has no effect in stdio mode and is being ignored: the minted URL has to be reachable over HTTP. Start with --http to use it."
+      );
+    }
+    const attachmentPort = parseAttachmentPortOption(this.options.attachmentPort);
+    if (attachmentPort !== null && !this.options.enableAttachmentUrls) {
+      throw new Error(
+        "--attachment-port requires --enable-attachment-urls: on its own there is no attachment route to put on the second listener. Pass both, or neither."
+      );
+    }
+    const attachmentHost = parseAttachmentHostOption(this.options.attachmentHost);
+    if (attachmentHost !== null && attachmentPort === null) {
+      throw new Error(
+        "--attachment-host requires --attachment-port: without a second listener there is no separate interface to bind, and the attachment route stays on the MCP app."
+      );
+    }
+    if (attachmentPort !== null && !this.options.http) {
+      logger.warn(
+        "--attachment-port has no effect in stdio mode and is being ignored: there is no HTTP listener to split. Start with --http to use it."
+      );
+    }
     if (this.options.http) {
       const { host, port } = parseHttpOption(this.options.http);
       const app = express();
@@ -538,27 +631,88 @@ class MicrosoftGraphServer {
           }
         }
       );
+      const attachmentConfig = loadAttachmentUrlConfig(Boolean(this.options.enableAttachmentUrls));
+      const mintingAlwaysRefused = this.authManager?.isOAuthModeEnabled() === true || !this.options.trustProxyAuth;
+      if (attachmentConfig && mintingAlwaysRefused) {
+        logger.warn(
+          "--enable-attachment-urls is on, but this server takes its Graph identity from the request in plain --http mode, and minting is refused whenever it does (the URL is redeemed later with no Authorization header, so the bytes would be fetched as a different identity). get-download-url will keep answering with download-bytes. Server-minted URLs need --trust-proxy-auth, where the server uses its own token."
+        );
+      }
+      let attachmentApp = null;
+      if (attachmentConfig) {
+        const ticketStore = new AttachmentTicketStore(attachmentConfig.ttlSeconds);
+        configureAttachmentMinting({ store: ticketStore, config: attachmentConfig });
+        const dedicated = attachmentPort !== null;
+        attachmentApp = dedicated ? express() : app;
+        if (dedicated) {
+          attachmentApp.use(
+            helmet({
+              contentSecurityPolicy: false,
+              crossOriginEmbedderPolicy: false,
+              hsts: { maxAge: 31536e3, includeSubDomains: true, preload: true }
+            })
+          );
+        }
+        if (!rateLimitDisabled) {
+          attachmentApp.use(
+            ATTACHMENT_ROUTE,
+            rateLimit({
+              windowMs: 6e4,
+              max: 60,
+              standardHeaders: "draft-7",
+              legacyHeaders: false
+            })
+          );
+        }
+        attachmentApp.get(
+          ATTACHMENT_ROUTE,
+          createAttachmentHandler({
+            store: ticketStore,
+            getGraphClient: () => this.graphClient,
+            authManager: this.authManager
+          })
+        );
+        logger.info(
+          `  - Attachment URLs: ${attachmentConfig.base}${ATTACHMENT_ROUTE} (ttl ${attachmentConfig.ttlSeconds}s, key id ${attachmentConfig.keyId})`
+        );
+        if (dedicated) {
+          logger.info(
+            `  - Attachment listener: separate, port ${attachmentPort} (${ATTACHMENT_ROUTE} is NOT served on the MCP port; MS365_MCP_ATTACHMENT_URL_BASE must name this port)`
+          );
+        }
+      } else {
+        configureAttachmentMinting(null);
+      }
       app.get("/", (req, res) => {
         res.send("Microsoft 365 MCP Server is running");
       });
-      if (host) {
-        app.listen(port, host, () => {
-          logger.info(`Server listening on ${host}:${port}`);
-          logger.info(`  - MCP endpoint: http://${host}:${port}/mcp`);
-          logger.info(`  - OAuth endpoints: http://${host}:${port}/auth/*`);
-          logger.info(
-            `  - OAuth discovery: http://${host}:${port}/.well-known/oauth-authorization-server`
+      const mcpBound = await this.listen(app, port, host);
+      const mcp = describeBoundAddress(mcpBound);
+      logger.info(`Server listening on ${mcp.label}`);
+      logger.info(`  - MCP endpoint: http://${mcp.authority}/mcp`);
+      logger.info(`  - OAuth endpoints: http://${mcp.authority}/auth/*`);
+      logger.info(
+        `  - OAuth discovery: http://${mcp.authority}/.well-known/oauth-authorization-server`
+      );
+      if (attachmentApp && attachmentPort !== null) {
+        let attachmentBound;
+        try {
+          attachmentBound = await this.listen(
+            attachmentApp,
+            attachmentPort,
+            attachmentHost ?? host
           );
-        });
-      } else {
-        app.listen(port, () => {
-          logger.info(`Server listening on all interfaces (0.0.0.0:${port})`);
-          logger.info(`  - MCP endpoint: http://localhost:${port}/mcp`);
-          logger.info(`  - OAuth endpoints: http://localhost:${port}/auth/*`);
-          logger.info(
-            `  - OAuth discovery: http://localhost:${port}/.well-known/oauth-authorization-server`
+        } catch (error) {
+          await this.stop();
+          throw error;
+        }
+        const attachment = describeBoundAddress(attachmentBound);
+        logger.info(`Attachment listener on ${attachment.label} \u2014 serves ${ATTACHMENT_ROUTE} only`);
+        if (this.options.trustProxyAuth && this.listenersShareAnInterface(mcpBound, attachmentBound)) {
+          logger.warn(
+            `--attachment-port split ${ATTACHMENT_ROUTE} onto port ${attachmentBound.port}, but both listeners answer on the same interface (MCP ${mcp.label}, attachment ${attachment.label}), so the ports are not isolated from each other. With --trust-proxy-auth, /mcp requires no credential, so anything permitted to reach the attachment port can also call every tool. Bind them to different --http and --attachment-host addresses, or keep the MCP port off the network the attachment fetcher is on.`
           );
-        });
+        }
       }
     } else {
       const transport = new StdioServerTransport();
@@ -569,8 +723,86 @@ class MicrosoftGraphServer {
       logger.info("Server connected to stdio transport");
     }
   }
+  /**
+   * Bind one Express app and record the listener.
+   *
+   * Awaited rather than fire-and-forget, which is what `app.listen(...)` on its
+   * own was. Two consequences, both wanted. A bind failure (EADDRINUSE is the
+   * live one now that there is a second port to collide) rejects `start()`, so
+   * `index.ts` reports it and exits 1 instead of the `error` event reaching the
+   * process-wide `uncaughtException` handler as an unattributed dump. And the
+   * caller knows the port is actually accepting connections when this resolves,
+   * so the second bind cannot race the first.
+   *
+   * **The callback's argument is read, and that is not a formality.** Express 5
+   * wraps the callback passed to `app.listen` in `once()` and registers that
+   * same wrapper as the server's `error` handler (`application.js`), so a bind
+   * that fails does not skip the callback -- it calls it with an Error. The
+   * zero-argument `() => logger.info('Server listening on ...')` this replaces
+   * is the shape every example uses, and it announced a port the process had
+   * not got: on EADDRINUSE the server logged that it was listening and stayed
+   * up serving nothing.
+   */
+  async listen(app, port, host) {
+    let server;
+    await new Promise((resolve, reject) => {
+      const done = (error) => error ? reject(error) : resolve();
+      server = host ? app.listen(port, host, done) : app.listen(port, done);
+      server.once("error", reject);
+      this.httpServers.push(server);
+    });
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+      throw new Error(`Listener on port ${port} reported no TCP address`);
+    }
+    return address;
+  }
+  /**
+   * Whether the two listeners can be reached from a common interface.
+   *
+   * A wildcard on either side answers everywhere, so it overlaps whatever the
+   * other one bound -- and on Linux a dual-stack `::` accepts IPv4 too, so the
+   * families are not a distinction worth drawing here. Otherwise they overlap
+   * only if they bound the same address. Deliberately coarse in the direction of
+   * warning: `127.0.0.1` and `127.0.0.2` are two addresses on one interface,
+   * separate to `bind()` and to a container network, and a check that tried to
+   * reason about routes instead of addresses would be wrong more often than this.
+   */
+  listenersShareAnInterface(a, b) {
+    if (isWildcardAddress(a.address) || isWildcardAddress(b.address)) return true;
+    return a.address === b.address;
+  }
+  /**
+   * Close every listener this server opened.
+   *
+   * `close()` alone is not enough and the difference is not theoretical: it
+   * stops accepting but waits on established sockets, and a keep-alive client
+   * (Node's own `fetch` is one) holds one open by default, so the process hangs
+   * instead of exiting. `closeIdleConnections()` drops exactly those, while a
+   * transfer still in flight -- an attachment being streamed -- is allowed to
+   * finish.
+   *
+   * Minting is switched off at the same time. The tickets live in a store this
+   * server owns, and after this returns there is no listener left to redeem
+   * them on; continuing to hand out URLs for a dead route would be a lie the
+   * agent only discovers at fetch time.
+   */
+  async stop() {
+    const servers = this.httpServers.splice(0);
+    configureAttachmentMinting(null);
+    await Promise.all(
+      servers.map(
+        (server) => new Promise((resolve) => {
+          server.close(() => resolve());
+          server.closeIdleConnections();
+        })
+      )
+    );
+  }
 }
 var server_default = MicrosoftGraphServer;
 export {
-  server_default as default
+  server_default as default,
+  parseAttachmentHostOption,
+  parseAttachmentPortOption
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@softeria/ms-365-mcp-server",
   "mcpName": "io.github.Softeria/ms-365-mcp-server",
-  "version": "0.150.3",
+  "version": "0.151.0",
   "description": " A Model Context Protocol (MCP) server for interacting with Microsoft 365 and Office services through the Graph API",
   "type": "module",
   "main": "dist/index.js",