@markmnl/fmsg-mcp 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## Unreleased
+
+- Add HTTP-only `get_attachment_download_url` and authenticated binary attachment GETs. Links
+  contain no credentials; downloads reuse caller authentication and OAuth read scope, stream the
+  original bytes, and keep Web API access checks authoritative. API-key deployments configure
+  `FMSG_MCP_PUBLIC_URL`; OAuth reuses its resource URL. Inline downloads and stdio saves remain available.
+- Abort failed response streams so a truncated download cannot appear successful.
+- Close unused replacement connections on HTTP shutdown after cancelled downloads.
+
 ## 0.2.0 (unreleased)
 
 This is the next planned release; publication still happens through a `v0.2.0` GitHub release.

package/README.md

@@ -10,23 +10,45 @@ attachments and wait for replies, through a deployed
 [fmsg Web API](https://github.com/markmnl/fmsg-webapi). Connect through stdio in hosts such as
 Claude Code, Claude Desktop, Cursor and VS Code, or through HTTP using API-key headers or configured OAuth.
 
+Use your choice of fmsg hosting provider, or self-host. No hosting provider or identity provider
+is built in.
+
 - **stdio** for local hosts: one address per server process, configured by two environment variables.
 - **Streamable HTTP** for shared or remote deployments: one endpoint serving many users, each
   authenticated by their own fmsg API key or OAuth connection.
 - The fmsg Web API client is exported for reuse: `import { FmsgClient } from "@markmnl/fmsg-mcp/client"`.
 
-## 1. Get an fmsg address and API key
+## 1. Choose a connection
+
+### OAuth: connect and sign in
 
-Connecting to an existing OAuth-enabled endpoint? Add its MCP URL to your host and sign in;
-you can skip the API-key setup below. Operators can enable this with [HTTP OAuth](docs/oauth.md).
+Get an OAuth-enabled MCP URL from your fmsg hosting provider, add it to your AI host, and sign in.
+You do not need an API key or a local installation for this connection. Your AI host must support
+the authorization server's client registration method; see [OAuth onboarding](docs/oauth.md#discovery-and-client-onboarding).
+Operators can enable this with [HTTP OAuth](docs/oauth.md).
+
+### API key: use locally or over HTTP
 
 You send as an fmsg address, authenticated by an API key (`fmsgk_…`) issued by your fmsg host:
 
-- **No host yet?** Create an account at a public fmsg host such as [fmsg.io](https://fmsg.io) and
-  add an agent (sub-account) to get an API URL and key.
+- **Using a hosting provider?** Create an account with an fmsg hosting provider and obtain an
+  API URL and API key for the address your agent will use.
 - **Self-hosting?** Run the stack with [fmsg-docker](https://github.com/markmnl/fmsg-docker) and issue
   a key with `fmsg-webapi api-key create`.
 
+Use the API URL and key for local installation below, or use your provider's API-key MCP endpoint
+with an `Authorization: Bearer fmsgk_...` header. The endpoint must use the fmsg Web API that accepts
+your key.
+
+### MCP Registry
+
+Find `io.github.markmnl/fmsg-mcp` in the [official MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.markmnl%2Ffmsg-mcp).
+The listing offers local npm installation and configurable remote connections for OAuth or API keys.
+For a remote connection, supply the MCP endpoint from your fmsg hosting provider or your own deployment;
+the registry input takes its hostname and path without the `https://` prefix, such as `mcp.example.com/mcp`.
+OAuth sign-in is discovered from that endpoint; the API-key option additionally asks for your key.
+If your AI host cannot configure registry URL templates, add the full MCP URL directly instead.
+
 ## 2. Install
 
 Requires Node.js 22 or later.
@@ -115,6 +137,7 @@ See the [TLS reverse-proxy example](docs/http-deployment.md) for a loopback depl
 | `react` | Set or clear your emoji reaction |
 | `mark_read` | Mark received messages read |
 | `download_attachment` | Fetch a small attachment inline: text as text, images as image blocks, other files as base64 resources |
+| `get_attachment_download_url` | Get a credential-free URL and resource link for an authenticated binary download; HTTP only, requires a public MCP URL |
 | `save_attachment` | Stream an attachment to the configured local folder; stdio only, enabled by `FMSG_MCP_DOWNLOAD_DIR` |
 | `delivery_status` | Per-recipient delivery times and host response codes |
 | `wait_for_message` | Block until the next inbound message (WebSocket push), batched per thread, with thread context |
@@ -132,6 +155,7 @@ attach resources; prompts `chat` and `reply` script the wait → reply loop and
 | `FMSG_API_URL` | — | Base URL of the fmsg Web API (required) |
 | `FMSG_API_KEY` | — | `fmsgk_…` key; stdio mode only |
 | `FMSG_MCP_AUTH_MODE` | `api-key` | HTTP authentication: `api-key` or `oauth`; see [OAuth settings](docs/oauth.md#operator-configuration) |
+| `FMSG_MCP_PUBLIC_URL` | OAuth resource URL, otherwise unset | Public MCP endpoint, including `/mcp`; enables the HTTP download-link tool. HTTPS required except loopback; in OAuth mode must equal `FMSG_MCP_OAUTH_RESOURCE_URL` |
 | `FMSG_ALLOW_INSECURE_HTTP` | disabled | Set to `1` only to permit cleartext API access on a trusted development/private network; loopback HTTP is allowed by default |
 | `FMSG_DEFAULT_DOMAIN` | — | Lets short names resolve: `bob` → `@bob@<domain>` |
 | `FMSG_DIRECTORY` | — | JSON file mapping short names to full addresses |
@@ -156,7 +180,22 @@ while making progress; a 60-second idle timeout detects stalled transfers.
 
 Inline downloads default to 256 KiB to keep file content manageable for the model. Use
 `save_attachment` for larger local files, or raise `max_inline_bytes` explicitly when your AI host
-can handle more inline content. HTTP clients use inline downloads or their host's file capabilities.
+can handle more inline content.
+
+For remote file downloads, call `get_attachment_download_url` with the message ID and filename.
+It returns metadata and an HTTPS `resource_link`; your AI host downloads the original bytes using
+the existing MCP connection's Authorization header. API-key operators enable the tool with
+`FMSG_MCP_PUBLIC_URL=https://mcp.example.com/mcp`; OAuth deployments reuse their configured resource
+URL automatically. The [reverse proxy must forward the attachment route](docs/http-deployment.md#binary-attachment-downloads).
+Links contain no credentials and grant no access by themselves. The host must support authenticated
+HTTP downloads; an ordinary browser click without the header returns 401. Use inline downloads when
+that host capability is unavailable. Downloads stream without the inline size budget, using the
+original Content-Type and download filename. No files are stored on the MCP server.
+
+The Web API already transfers attachments as raw bytes. Base64 is used only when embedding binary
+content in MCP's JSON results, as required by [MCP binary resources](https://modelcontextprotocol.io/specification/2026-07-28/server/resources#binary-content).
+`save_attachment` and authenticated HTTP downloads avoid that encoding and keep file bytes out of
+model context. See [issue #6](https://github.com/markmnl/fmsg-mcp/issues/6).
 
 Over stdio, missing or invalid configuration still allows hosts to discover the tools. Tool calls
 explain the configuration error and how to fix it; restart the MCP server after correcting settings.
@@ -213,4 +252,11 @@ bash .github/scripts/run-fmsg-docker-e2e.sh                     # end to end on
 See [AGENTS.md](./AGENTS.md) for layout and conventions, [ROADMAP.md](./ROADMAP.md) for remaining
 integration work, and [CHANGELOG.md](./CHANGELOG.md) for release notes.
 
+### Releasing
+
+Publish a stable GitHub release tagged `vX.Y.Z` to run the checks, publish the npm package, and
+then update the MCP Registry with the same version. Both use OIDC authentication; no dedicated
+registry secret is needed. Drafts and prereleases do not publish. Registry publishing runs as a
+separate job, so if it fails after npm succeeds, use **Re-run failed jobs** on the release workflow.
+
 [MIT licensed](./LICENSE)

package/SECURITY.md

@@ -37,6 +37,12 @@ rather than a public issue.
 - Attachment transfers retain caller cancellation and client shutdown signals. They use a response
   header deadline followed by a per-read idle timeout (60 seconds each by default), so a progressing
   large download is not subject to a 60-second total duration limit.
+- HTTP attachment links contain no credentials and do not confer access. Every GET authenticates
+  the caller and uses its upstream client; OAuth also requires `fmsg:read`. The Web API decides
+  attachment visibility. Public URLs come from operator configuration, never forwarded headers.
+  Downloads stream with backpressure and force attachment disposition, no-store caching and nosniff.
+  Failed streams terminate the connection so partial files cannot appear successfully completed.
+  Query parameters are refused. Authenticated download links require support in the AI host.
 - Error previews are limited to 2 KiB while reading, except canonical JSON HTTP 400/413 responses:
   those retain the host's acceptance/size-policy explanation. Selected credentials are still redacted;
   oversized previews are explicitly marked as truncated.

package/dist/config.d.ts

@@ -3,6 +3,8 @@ export type Transport = "stdio" | "http";
 export type HttpConfig = {
     host: string;
     port: number;
+    /** Canonical public MCP endpoint for credential-free attachment links. */
+    publicUrl?: string;
     /** Hostnames accepted in the Host header. Empty means: derive from the bind address (loopback only). */
     allowedHosts: string[];
     /** Exact browser origins. Empty permits same-origin and, on loopback binds, loopback origins on any port. */

package/dist/config.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { normalizeFmsgAddress } from "./address.js";
 import { normalizeApiUrl, normalizeOrigin } from "./client/url.js";
-import { loadOAuthConfig } from "./oauth/config.js";
+import { loadOAuthConfig, oauthUrl } from "./oauth/config.js";
 export const DEFAULT_HTTP_PORT = 8765;
 export const DEFAULT_WAIT_MAX_SECONDS = 230;
 function intEnv(env, name, fallback, min = 1) {
@@ -63,6 +63,11 @@ export function loadConfig(env, transport, overrides = {}, options = {}) {
     if (!Number.isInteger(port) || port < 0 || port > 65535)
         throw new Error("FMSG_MCP_PORT must be between 0 and 65535");
     const host = overrides.host ?? env.FMSG_MCP_HOST?.trim() ?? "127.0.0.1";
+    const publicUrl = transport === "http" ? env.FMSG_MCP_PUBLIC_URL?.trim() || oauth?.resourceUrl : undefined;
+    if (publicUrl)
+        oauthUrl(publicUrl, "FMSG_MCP_PUBLIC_URL");
+    if (oauth && publicUrl !== oauth.resourceUrl)
+        throw new Error("FMSG_MCP_PUBLIC_URL must match FMSG_MCP_OAUTH_RESOURCE_URL in OAuth mode");
     return {
         transport,
         apiUrl: normalizedApiUrl,
@@ -76,6 +81,7 @@ export function loadConfig(env, transport, overrides = {}, options = {}) {
         http: {
             host,
             port,
+            ...(publicUrl ? { publicUrl } : {}),
             allowedHosts: listEnv(env, "FMSG_MCP_ALLOWED_HOSTS"),
             allowedOrigins: listEnv(env, "FMSG_MCP_ALLOWED_ORIGINS").map(normalizeOrigin),
             keyCacheMax: intEnv(env, "FMSG_MCP_KEY_CACHE_MAX", 500),

package/dist/download.d.ts

@@ -0,0 +1,11 @@
+import type { Config } from "./config.js";
+export declare const DOWNLOAD_PATH = "/mcp/attachments";
+export declare function downloadBaseUrl(config: Config): string | undefined;
+export declare function attachmentFilename(filename: string): string;
+export declare function attachmentDownloadUrl(baseUrl: string, id: string, filename: string): string;
+export declare function parseDownloadPath(pathname: string): {
+    id: string;
+    filename: string;
+};
+/** Always download untrusted files; preserve Unicode filenames without raw header characters. */
+export declare function downloadHeaders(filename: string, contentType?: string): Headers;

package/dist/download.js

@@ -0,0 +1,34 @@
+import { normalizeMessageId } from "./client/message-id.js";
+export const DOWNLOAD_PATH = "/mcp/attachments";
+export function downloadBaseUrl(config) {
+    return config.transport === "http" ? config.http.publicUrl ?? config.oauth?.resourceUrl : undefined;
+}
+export function attachmentFilename(filename) {
+    if (!filename || filename === "." || filename === ".." || /[/\\\x00-\x1f\x7f]/u.test(filename)) {
+        throw new Error("use an attachment filename without directory components or control characters");
+    }
+    // Also reject unpaired UTF-16 surrogates before building a URL/header.
+    encodeURIComponent(filename);
+    return filename;
+}
+export function attachmentDownloadUrl(baseUrl, id, filename) {
+    return `${baseUrl.replace(/\/$/u, "")}/attachments/${normalizeMessageId(id)}/${encodeURIComponent(attachmentFilename(filename))}`;
+}
+export function parseDownloadPath(pathname) {
+    const parts = pathname.slice(DOWNLOAD_PATH.length + 1).split("/");
+    if (parts.length !== 2)
+        throw new Error("invalid attachment download path");
+    return { id: normalizeMessageId(parts[0]), filename: attachmentFilename(decodeURIComponent(parts[1])) };
+}
+/** Always download untrusted files; preserve Unicode filenames without raw header characters. */
+export function downloadHeaders(filename, contentType) {
+    const fallback = filename.replace(/[^A-Za-z0-9._-]/gu, "_");
+    const encoded = encodeURIComponent(filename).replace(/[!'()*]/gu, c => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+    return new Headers({
+        "content-type": contentType ?? "application/octet-stream",
+        "content-disposition": `attachment; filename="${fallback}"; filename*=UTF-8''${encoded}`,
+        "cache-control": "no-store",
+        "x-content-type-options": "nosniff",
+        "content-security-policy": "sandbox",
+    });
+}

package/dist/http.js

@@ -5,7 +5,10 @@ import { ApiKeyCallerProvider, FMSG_SCOPE } from "./auth.js";
 import { createFmsgMcpServer } from "./server.js";
 import { OAuthCallerProvider } from "./oauth/provider.js";
 import { invalidToken, insufficientScope, OAuthRequestError, oauthErrorResponse, oauthRequestState } from "./oauth/errors.js";
-import { MESSAGING_SCOPES, requestScopes } from "./oauth/scopes.js";
+import { MESSAGING_SCOPES, READ_SCOPE, requestScopes } from "./oauth/scopes.js";
+import { DOWNLOAD_PATH, downloadBaseUrl, downloadHeaders, parseDownloadPath } from "./download.js";
+import { FmsgHttpError } from "./client/errors.js";
+import { describeError } from "./errors.js";
 import { VERSION } from "./version.js";
 import { safeErrorMessage } from "./client/redact.js";
 import { isLoopbackHost, normalizeOrigin } from "./client/url.js";
@@ -76,10 +79,18 @@ export async function sendWebResponse(res, response, failure) {
                 });
         }
     }
+    catch (error) {
+        // Once bytes have been sent, terminate the transfer so a truncated file is
+        // not reported as a successful download. Before headers, let the caller map the error.
+        if (res.headersSent)
+            res.destroy();
+        throw error;
+    }
     finally {
         res.off("close", abort);
         await reader.cancel().catch(() => undefined);
-        res.end();
+        if (res.headersSent && !res.destroyed)
+            res.end();
     }
 }
 export function createHttpServer(config, log = (l) => console.error(l)) {
@@ -96,6 +107,7 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
     const safeLog = (line) => log(safeErrorMessage(line));
     const provider = config.oauth ? new OAuthCallerProvider(config, safeLog) : new ApiKeyCallerProvider(config, safeLog);
     const resource = config.oauth ? new URL(config.oauth.resourceUrl) : undefined;
+    const publicOrigin = downloadBaseUrl(config) ? new URL(downloadBaseUrl(config)).origin : undefined;
     const metadataPath = resource ? `/.well-known/oauth-protected-resource${resource.pathname === "/" ? "" : resource.pathname}` : undefined;
     const metadataUrl = resource ? `${resource.origin}${metadataPath}` : "";
     const handler = createMcpHandler(({ authInfo }) => createFmsgMcpServer(provider, config, authInfo ? {
@@ -111,6 +123,7 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
         res.once("close", abort);
         void (async () => {
             const url = new URL(req.url ?? "/", "http://localhost");
+            const isDownload = url.pathname.startsWith(`${DOWNLOAD_PATH}/`);
             if (url.pathname === "/healthz") {
                 res.writeHead(200, { "content-type": "application/json" });
                 res.end(JSON.stringify({ ok: true, name: "fmsg-mcp", version: VERSION }));
@@ -129,7 +142,7 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
                     authorization_servers: [config.oauth.issuerUrl], scopes_supported: MESSAGING_SCOPES,
                     bearer_methods_supported: ["header"], resource_name: "fmsg messaging", }, { headers }));
             }
-            if (url.pathname !== MCP_PATH) {
+            if (url.pathname !== MCP_PATH && !isDownload) {
                 res.writeHead(404, { "content-type": "text/plain" });
                 res.end("not found; the MCP endpoint is /mcp");
                 return;
@@ -148,26 +161,82 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
                     const localDevelopment = isLoopbackHost(config.http.host) && !allowedOrigins.length &&
                         /^https?:$/u.test(parsed.protocol) && isLoopbackHost(parsed.hostname);
                     valid = parsed.origin === origin &&
-                        (localDevelopment || allowedOrigins.includes(origin) || origin === (resource?.origin ?? new URL(request.url).origin));
+                        (localDevelopment || allowedOrigins.includes(origin) || origin === (publicOrigin ?? resource?.origin ?? new URL(request.url).origin));
                 }
                 catch { /* malformed origins are rejected */ }
                 if (!valid)
                     return sendWebResponse(res, new Response("origin not allowed", { status: 403 }));
                 res.setHeader("access-control-allow-origin", origin);
-                res.setHeader("access-control-expose-headers", "WWW-Authenticate, MCP-Session-Id, MCP-Protocol-Version, Retry-After");
+                res.setHeader("access-control-expose-headers", "WWW-Authenticate, MCP-Session-Id, MCP-Protocol-Version, Retry-After, Content-Disposition");
             }
             res.setHeader("vary", "Origin");
             res.setHeader("cache-control", "no-store");
             if (req.method === "OPTIONS") {
                 const method = request.headers.get("access-control-request-method") ?? "";
                 const headers = (request.headers.get("access-control-request-headers") ?? "").split(",").map((v) => v.trim().toLowerCase()).filter(Boolean);
-                if (!origin || !CORS_METHODS.includes(method) || headers.some((h) => !CORS_HEADERS.includes(h))) {
+                const methods = isDownload ? ["GET"] : CORS_METHODS;
+                if (!origin || !methods.includes(method) || headers.some((h) => !CORS_HEADERS.includes(h))) {
                     return sendWebResponse(res, new Response("preflight not allowed", { status: 403 }));
                 }
-                res.setHeader("access-control-allow-methods", CORS_METHODS.join(", "));
+                res.setHeader("access-control-allow-methods", methods.join(", "));
                 res.setHeader("access-control-allow-headers", CORS_HEADERS.join(", "));
                 return sendWebResponse(res, new Response(null, { status: 204 }));
             }
+            let download;
+            if (isDownload) {
+                if (req.method !== "GET")
+                    return sendWebResponse(res, new Response("use GET to download attachments", { status: 405, headers: { allow: "GET, OPTIONS" } }));
+                // Authentication belongs only in the Authorization header, never the URL.
+                if (url.search)
+                    return sendWebResponse(res, new Response("attachment URLs must not contain query parameters", { status: 400 }));
+                try {
+                    download = parseDownloadPath(url.pathname);
+                }
+                catch {
+                    return sendWebResponse(res, new Response("invalid attachment download path", { status: 400 }));
+                }
+            }
+            const serveDownload = async (auth) => {
+                let caller;
+                try {
+                    caller = await provider.forRequest(auth);
+                    const { stream, contentType } = await caller.client.streamAttachment(download.id, download.filename, controller.signal);
+                    let response;
+                    try {
+                        response = new Response(stream, { headers: downloadHeaders(download.filename, contentType) });
+                    }
+                    catch (error) {
+                        await stream.cancel().catch(() => undefined);
+                        throw error;
+                    }
+                    return await sendWebResponse(res, response);
+                }
+                catch (error) {
+                    const rejectedAuth = (error instanceof OAuthRequestError && error.status === 401) ||
+                        (error instanceof FmsgHttpError && (error.status === 401 || (error.path === "/fmsg/token" && [400, 403].includes(error.status))));
+                    if (caller && rejectedAuth)
+                        provider.invalidate(caller);
+                    if (res.destroyed || controller.signal.aborted)
+                        return;
+                    if (res.headersSent) {
+                        res.destroy();
+                        return;
+                    }
+                    if (provider instanceof OAuthCallerProvider) {
+                        if (error instanceof OAuthRequestError)
+                            return sendWebResponse(res, oauthErrorResponse(error, metadataUrl));
+                        if (rejectedAuth)
+                            return sendWebResponse(res, oauthErrorResponse(invalidToken(), metadataUrl));
+                        if (error instanceof FmsgHttpError && error.insufficientScope) {
+                            return sendWebResponse(res, oauthErrorResponse(new OAuthRequestError(403, "insufficient_scope", error.message, [READ_SCOPE]), metadataUrl));
+                        }
+                    }
+                    const status = rejectedAuth ? 401 : error instanceof FmsgHttpError && error.status >= 400 && error.status <= 599 ? error.status : 502;
+                    return sendWebResponse(res, Response.json({ error: describeError(error) }, {
+                        status, headers: status === 401 ? { "www-authenticate": 'Bearer error="invalid_token"' } : {},
+                    }));
+                }
+            };
             if (provider instanceof OAuthCallerProvider) {
                 try {
                     const bearer = /^Bearer ([A-Za-z0-9._~+\/-]+=*)$/iu.exec(request.headers.get("authorization") ?? "");
@@ -185,9 +254,11 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
                         if (Array.isArray(parsedBody))
                             return sendWebResponse(res, new Response("MCP batch requests are not supported", { status: 400 }));
                     }
-                    const scopes = requestScopes(parsedBody);
+                    const scopes = download ? [READ_SCOPE] : requestScopes(parsedBody);
                     if (scopes.some(scope => !authenticated.scopes.includes(scope)))
                         throw insufficientScope(scopes);
+                    if (download)
+                        return await serveDownload(authenticated);
                     // Discover/list operations only need the incoming JWT. Resolve an
                     // exchanged credential before starting any protected tool response.
                     if (scopes.length) {
@@ -218,11 +289,18 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
             const auth = await gate(request);
             if (auth instanceof Response)
                 return sendWebResponse(res, auth);
+            if (download)
+                return serveDownload(auth);
             return sendWebResponse(res, await handler.fetch(request, { authInfo: auth }));
         })().catch((error) => {
             safeLog(`request failed: ${error instanceof Error ? error.message : String(error)}`);
-            if (!res.headersSent)
-                res.writeHead(500, { "content-type": "text/plain" });
+            if (res.destroyed)
+                return;
+            if (res.headersSent) {
+                res.destroy();
+                return;
+            }
+            res.writeHead(500, { "content-type": "text/plain" });
             res.end("internal error");
         }).finally(() => {
             if (authenticated)
@@ -241,7 +319,12 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
             controller.abort();
         provider.close();
         await handler.close();
-        await new Promise((resolve) => server.close(() => resolve()));
+        await new Promise((resolve) => {
+            server.close(() => resolve());
+            // Aborted fetches may open replacement sockets without a request, so
+            // they are absent from `active` and must also be closed on shutdown.
+            server.closeAllConnections();
+        });
     };
     return { server, close, provider };
 }

package/dist/instructions.js

@@ -10,7 +10,9 @@ export function buildInstructions(ctx = {}) {
             "Use its tools for everything fmsg: inbox, threads, attachments, sending, replying, reactions, " +
             "delivery status and waiting for new messages. Do not use an fmsg command-line tool, local config " +
             "files or cached credentials instead; they may belong to a different address or host. If a tool " +
-            "reports the server is not configured, explain the reported configuration fix and restart requirement.",
+            "reports the server is not configured, explain the reported configuration fix and restart requirement. " +
+            "For URLs returned by get_attachment_download_url, use your host's authenticated download facility " +
+            "with this MCP connection; never search for credentials or put them in prompts or URLs.",
         "Carry out the user's requested messaging task or authorized automation without repeatedly asking for " +
             "confirmation. Sending is immediate and sent messages cannot be edited or recalled. Ask the user only " +
             "when a decision is needed to resolve unclear intent, recipients or content. The AI host controls tool " +

package/dist/oauth/scopes.js

@@ -7,7 +7,7 @@ export const TOOL_SCOPES = {
     whoami: [READ_SCOPE], resolve_address: [READ_SCOPE],
     list_messages: [READ_SCOPE], list_sent: [READ_SCOPE], get_message: [READ_SCOPE],
     get_thread: [READ_SCOPE], delivery_status: [READ_SCOPE], download_attachment: [READ_SCOPE],
-    save_attachment: [READ_SCOPE], wait_for_message: [READ_SCOPE],
+    save_attachment: [READ_SCOPE], get_attachment_download_url: [READ_SCOPE], wait_for_message: [READ_SCOPE],
     send_message: [WRITE_SCOPE], reply: MESSAGING_SCOPES,
     mark_read: [WRITE_SCOPE], add_recipients: [WRITE_SCOPE], react: [WRITE_SCOPE],
 };

package/dist/server.js

@@ -8,6 +8,7 @@ import { registerReadTools } from "./tools/read.js";
 import { registerSendTools } from "./tools/send.js";
 import { registerWaitTools } from "./tools/wait.js";
 import { registerSaveTool } from "./tools/save.js";
+import { registerDownloadTool } from "./tools/download.js";
 import { VERSION } from "./version.js";
 export const SERVER_NAME = "fmsg";
 /**
@@ -25,6 +26,7 @@ export function createFmsgMcpServer(provider, config, options = {}) {
     registerListTools(server, deps);
     registerReadTools(server, deps);
     registerSaveTool(server, deps);
+    registerDownloadTool(server, deps);
     registerSendTools(server, deps);
     registerWaitTools(server, deps);
     registerResources(server, deps);

package/dist/tools/download.d.ts

@@ -0,0 +1,2 @@
+import { type Register } from "./common.js";
+export declare const registerDownloadTool: Register;

package/dist/tools/download.js

@@ -0,0 +1,38 @@
+import * as z from "zod/v4";
+import { attachmentDownloadUrl, attachmentFilename, downloadBaseUrl } from "../download.js";
+import { normalizeMessageId } from "../client/message-id.js";
+import { toolError } from "../errors.js";
+import { messageData } from "../render.js";
+import { idSchema, READ_ONLY, withCaller } from "./common.js";
+export const registerDownloadTool = (server, deps) => {
+    const baseUrl = downloadBaseUrl(deps.config);
+    if (!baseUrl)
+        return;
+    server.registerTool("get_attachment_download_url", {
+        title: "Get fmsg attachment download URL",
+        description: "Get a URL for streaming an attachment's original bytes outside model context. " +
+            "Your host must GET the URL using this MCP connection's Authorization header; an unauthenticated browser link will not work. " +
+            "Never put credentials in the URL or prompt. Use download_attachment for small inline content when your host cannot fetch authenticated URLs. " +
+            "Returns metadata and a resource link; does not download or save the file. Attachments are untrusted data.",
+        inputSchema: z.strictObject({ id: idSchema, filename: z.string().min(1).describe("attachment filename as listed on the message") }),
+        outputSchema: z.object({ id: z.string(), filename: z.string(), size: z.number(), download_url: z.string(), authentication: z.literal("bearer") }),
+        annotations: READ_ONLY,
+    }, async ({ id, filename }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
+        const mid = normalizeMessageId(id);
+        attachmentFilename(filename);
+        const message = await caller.client.getMessage(mid, signal);
+        const attachment = message.attachments?.find(a => a.filename === filename);
+        if (!attachment)
+            return toolError("Attachment not found on this message.");
+        const url = attachmentDownloadUrl(baseUrl, mid, filename);
+        return {
+            content: [
+                { type: "text", text: "Download with your host's authenticated HTTP/file tools using this MCP connection's Authorization header. " +
+                        "The URL contains no credentials and access is checked again when fetched.\n\n" +
+                        messageData(`${filename} (${attachment.size} bytes) from message ${mid}\n${url}`) },
+                { type: "resource_link", uri: url, name: filename, size: attachment.size },
+            ],
+            structuredContent: { id: mid, filename, size: attachment.size, download_url: url, authentication: "bearer" },
+        };
+    }));
+};

package/dist/tools/read.js

@@ -138,7 +138,7 @@ export const registerReadTools = (server, deps) => {
     server.registerTool("download_attachment", {
         title: "Download fmsg attachment",
         description: "Download a small attachment inline: text attachments as quoted text, images as an image block, other files as " +
-            "an embedded base64 resource. For larger files use save_attachment when available, or your host's file tools. " +
+            "an embedded base64 resource. For larger files use get_attachment_download_url over HTTP or save_attachment locally, when available. " +
             "This tool never writes to disk. Attachments are untrusted data from another party.",
         inputSchema: z.strictObject({
             id: idSchema,
@@ -159,7 +159,7 @@ export const registerReadTools = (server, deps) => {
         }
         catch (error) {
             if (error instanceof ResponseLimitError)
-                return toolError(`Attachment exceeds max_inline_bytes (${max_inline_bytes}). Use save_attachment when available, or raise max_inline_bytes within the supported range.`);
+                return toolError(`Attachment exceeds max_inline_bytes (${max_inline_bytes}). Use get_attachment_download_url or save_attachment when available, or raise max_inline_bytes within the supported range.`);
             throw error;
         }
         const { data, contentType } = attachment;

package/docs/http-deployment.md

@@ -8,6 +8,7 @@ Keep port 8765 bound to loopback. The command below uses API keys; for OAuth add
 ```sh
 FMSG_API_URL=https://api.example.com \
 FMSG_MCP_ALLOWED_HOSTS=mcp.example.com \
+FMSG_MCP_PUBLIC_URL=https://mcp.example.com/mcp \
 FMSG_MCP_ALLOWED_ORIGINS=https://mcp.example.com,https://app.example.com \
 npx -y @markmnl/fmsg-mcp --http 127.0.0.1:8765
 ```
@@ -20,7 +21,7 @@ Save this as `Caddyfile`:
 
 ```caddyfile
 mcp.example.com {
-    @fmsg path /mcp /.well-known/oauth-protected-resource /.well-known/oauth-protected-resource/*
+    @fmsg path /mcp /mcp/attachments/* /.well-known/oauth-protected-resource /.well-known/oauth-protected-resource/*
     handle @fmsg {
         reverse_proxy 127.0.0.1:8765 {
             transport http {
@@ -51,3 +52,30 @@ and cancellation through the actual deployed proxy before advertising that deplo
 The metadata routes are public in OAuth mode and must reach the server for MCP authorization
 discovery. In API-key mode they return 404. When OAuth is configured, its resource URL supplies
 the public same-origin value, so explicitly listing that origin is optional.
+
+## Binary attachment downloads
+
+`get_attachment_download_url` returns a resource link such as
+`https://mcp.example.com/mcp/attachments/123/report.pdf`. The host fetches it with an authenticated
+GET, using the same `Authorization: Bearer ...` header as its MCP connection. OAuth requires
+`fmsg:read`; the server exchanges the incoming token for a Web API token as usual. The Web API
+checks visibility on every download, even when a link was obtained earlier.
+
+Set `FMSG_MCP_PUBLIC_URL` to the exact external MCP endpoint when using API keys. OAuth defaults
+to `FMSG_MCP_OAUTH_RESOURCE_URL`; if both are set, they must match. These URLs require HTTPS outside
+loopback and cannot contain credentials, queries or fragments. Request Host and forwarded headers
+never select the download URL. If the proxy exposes MCP under a different public path, map that
+path and its `/attachments/*` suffix to `/mcp` and `/mcp/attachments/*` respectively.
+
+Downloads use the original MIME type, `Content-Disposition: attachment`, Unicode filename encoding,
+`Cache-Control: no-store` and `X-Content-Type-Options: nosniff`. The body streams with backpressure;
+disconnects cancel the upstream request and incomplete transfers abort rather than complete as a
+truncated file. No temporary server files, signed URLs or tokens in query strings are used.
+Range/resume requests are not implemented: GET returns the full file. Treat a failed transfer as
+incomplete and discard its partial local output before retrying.
+
+Host and Origin validation applies to downloads too. Allowed browser clients can preflight GET
+with Authorization and read Content-Disposition. Hosts must attach the connection credential
+themselves; never ask the model to locate or copy tokens. Clients that cannot fetch authenticated
+links can still use `download_attachment` inline. Compatibility of authenticated links with each
+third-party AI host must be tested before advertising support.

package/docs/oauth.md

@@ -80,6 +80,12 @@ use pre-registered clients or Client ID Metadata Documents where supported by bo
 host. Check the intended host's registration support before advertising compatibility. This
 implementation does not add a registration proxy, login UI or consent UI.
 
+The resource URL also supplies the public URL for `get_attachment_download_url`. Its links contain
+no credentials; hosts fetch them using the current MCP bearer token, with `fmsg:read`. The binary
+GET route uses the same token validation and Web API token exchange, and exposes the same metadata
+challenge on authentication failure. See [binary downloads](http-deployment.md#binary-attachment-downloads)
+for reverse-proxy routing and host compatibility requirements.
+
 ## Token validation and scopes
 
 Incoming access tokens must be signed EdDSA JWTs with `typ: at+jwt`, a nonempty `kid` in the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@markmnl/fmsg-mcp",
   "mcpName": "io.github.markmnl/fmsg-mcp",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "MCP server for fmsg: send and receive federated messages from any AI agent via a deployed fmsg Web API",
   "type": "module",
   "license": "MIT",

package/server.json

@@ -1,25 +1,27 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.markmnl/fmsg-mcp",
-  "description": "Send and receive fmsg federated messages from any AI agent via a deployed fmsg Web API",
+  "title": "fmsg",
+  "description": "Federated messaging with your fmsg hosting provider. Connect with OAuth or an API key.",
+  "websiteUrl": "https://github.com/markmnl/fmsg-mcp#readme",
   "repository": {
     "url": "https://github.com/markmnl/fmsg-mcp",
     "source": "github"
   },
-  "version": "0.2.0",
+  "version": "0.2.2",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@markmnl/fmsg-mcp",
-      "version": "0.2.0",
+      "version": "0.2.2",
       "transport": {
         "type": "stdio"
       },
       "environmentVariables": [
         {
           "name": "FMSG_API_URL",
-          "description": "Base URL of the fmsg Web API",
+          "description": "Base URL of your hosting provider's or self-hosted fmsg Web API",
           "isRequired": true
         },
         {
@@ -40,5 +42,48 @@
         }
       ]
     }
+  ],
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://{oauth_mcp_endpoint}",
+      "variables": {
+        "oauth_mcp_endpoint": {
+          "description": "OAuth MCP endpoint from your fmsg hosting provider: hostname and path without https://. Sign in through your AI host; no API key needed.",
+          "isRequired": true,
+          "format": "string",
+          "placeholder": "mcp.example.com/mcp"
+        }
+      }
+    },
+    {
+      "type": "streamable-http",
+      "url": "https://{api_key_mcp_endpoint}",
+      "variables": {
+        "api_key_mcp_endpoint": {
+          "description": "API-key MCP endpoint from your fmsg hosting provider: hostname and path without https://. Use an endpoint that accepts your key.",
+          "isRequired": true,
+          "format": "string",
+          "placeholder": "mcp.example.com/mcp"
+        }
+      },
+      "headers": [
+        {
+          "name": "Authorization",
+          "description": "Your fmsg API key for the selected MCP endpoint",
+          "isRequired": true,
+          "isSecret": true,
+          "value": "Bearer {api_key}",
+          "variables": {
+            "api_key": {
+              "description": "API key accepted by this endpoint's fmsg Web API, starting with fmsgk_",
+              "isRequired": true,
+              "isSecret": true,
+              "format": "string"
+            }
+          }
+        }
+      ]
+    }
   ]
 }