@elfa-ai/mcp 3.0.0 → 4.2.0

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # Changelog
 
+## 4.2.0
+
+### Added
+
+- **OAuth sign-in for hosted deployments** (`ELFA_MCP_AUTH=oauth`, HTTP transport only). Clients such as ChatGPT, Claude and Codex can connect with a browser sign-in instead of an API key. The server acts as an OAuth resource server under the MCP authorization spec:
+  - It serves RFC 9728 protected-resource metadata at `/.well-known/oauth-protected-resource/mcp` (and at the root path).
+  - A request with no credential gets `401` with a `WWW-Authenticate: Bearer resource_metadata=…` challenge.
+  - Each bearer token is checked against the authorization server's introspection endpoint, which returns the Elfa API key the request runs as. The token itself is never forwarded to the Elfa API.
+  - The token must be issued for this server: its audience has to match `ELFA_MCP_RESOURCE_URL`.
+  - Valid answers are cached for up to 60 seconds.
+  - An unreachable authorization server returns `503`, not `401`, so clients don't restart sign-in because of an outage.
+- An `x-elfa-api-key` header still works in OAuth mode, so API-key users of the same deployment are unaffected.
+
+### Changed
+
+- `getMarketEvents-v2` is no longer listed as unexposed. The Elfa API dropped it from the published spec, so there is nothing left to account for.
+- In OAuth mode `ELFA_API_KEY` is ignored. Every request brings its own credential, and an environment key would otherwise be handed to any caller that sends none. API-key mode keeps its environment fallback.
+
+## 4.1.0
+
+### Security
+
+- **DNS rebinding protection is now armed by default on the HTTP transport.** `enableDnsRebindingProtection` was only passed when `ELFA_MCP_ALLOWED_ORIGINS` was set, and that variable is unset in the documented local run (`ELFA_MCP_TRANSPORT=http npx -y @elfa-ai/mcp`), so the control shipped present but disarmed. The transport accepted any `Host` and any `Origin` while holding `ELFA_API_KEY`, which let a page the user visits re-point its own hostname at `127.0.0.1` and reach `tools/list` and `tools/call` at that process's own privilege — including the `auto_*` tools that spend credits. Binding to `127.0.0.1` was never a mitigation, because the victim's browser is already on loopback.
+
+  Setting the origin allowlist did not close it either. `allowedOrigins` was passed but `allowedHosts` never was, and the SDK guards each check with its own `length > 0` test, so `Host` validation never ran. An origin allowlist cannot carry this alone: a rebound request is same-origin and sends no `Origin` header, which leaves `Host` as the only header still naming the attacker's domain.
+
+  Refs GHSA-w48q-cv73-mx4w / CVE-2025-66414. Reported by mcpdone.
+
+### Added
+
+- **`ELFA_MCP_ALLOWED_HOSTS`**, a comma separated `Host` allowlist. It defaults to the loopback names the server binds — `ELFA_MCP_HOST:PORT`, `localhost:PORT` and `127.0.0.1:PORT` — so the documented local run is closed with no configuration.
+
+### Changed
+
+- **Action required for hosted deployments.** The host allowlist fails closed, so a deployment answering on any `Host` other than the loopback names the server binds now returns `403` until it sets `ELFA_MCP_ALLOWED_HOSTS`. That covers a public domain, a reverse proxy, and a container that maps the port to a different one than the server binds, since the default is derived from `ELFA_MCP_PORT`.
+
+  A minor rather than a major, because nothing about the interaction with this server changes: the eleven tools, their arguments, the stdio transport and every client-facing contract are untouched. A self-hosted HTTP deployment needs one environment variable.
+
+  **Migration:** set `ELFA_MCP_ALLOWED_HOSTS` to the host values the deployment serves, for example `ELFA_MCP_ALLOWED_HOSTS=mcp.example.com`. The stdio transport is unaffected and needs no change.
+
+## 4.0.0
+
+### Removed
+
+- **`ELFA_HMAC_SECRET` and request signing are gone.** Elfa no longer documents HMAC signing for `/v2/auto/*` — the API key alone authenticates every route, including mutations. Removed here: the `ELFA_HMAC_SECRET` environment variable, the `x-elfa-hmac-secret` request header on the HTTP transport, the `elfa_hmac_secret` field in the Claude Desktop bundle, and the registry entry in `server.json`.
+
+  **Migration:** unset `ELFA_HMAC_SECRET` and stop sending `x-elfa-hmac-secret`. Neither is read any more. Nothing replaces them.
+
+- **The client-side signing gate is gone.** `auto_query_write` and `auto_draft` no longer inspect a query's action shape and pre-reject it before sending. Every action type Elfa documents for API-key Auto — `notify`, `telegram_bot`, `webhook`, `llm` — is accepted with the API key alone, so the gate could only produce false rejections.
+
+- **`hmacEnabled` is no longer reported by `api_status`.** The field was removed from the key-status response, so surfacing it would report something the API no longer sends.
+
+- **`pacifica` is no longer a valid `auto_validate` exchange.** The documented enum for `method=symbol` is now `hyperliquid`, `gmx`, `binance`.
+
+### Changed
+
+- **Spec refreshed to `2.6.3`** from `2.5.0`. A credit is now $0.0145, so the x402 reference prices move to $0.0145 (1 credit), $0.0725 (5 credits) and $0.261 (18 credits). Accounts already on PAYG keep $0.009 per credit until 28 September 2026, 16:00 UTC.
+- **`getMarketEvents-v2` is recorded as deliberately unexposed.** It is limited to select Enterprise customers and the published operation takes no parameters, so there is no usable tool surface. Eleven tools, unchanged.
+- Install troubleshooting no longer claims a `403` on an Auto call means Auto is not enabled in the portal. There is no separate Auto enablement step; a new API key can call `/v2/auto/*` immediately.
+- `SECURITY.md` now states that the API key is read from the environment on stdio and can arrive per request as `x-elfa-api-key` over HTTP, and refers to the tools by their current names.
+
 ## 3.0.0
 
 ### Removed

package/README.md

@@ -48,7 +48,6 @@ Ask *"what's trending in crypto right now?"* to confirm it works.
 | Variable | Required | Purpose |
 | --- | --- | --- |
 | `ELFA_API_KEY` | yes | Authenticates every request |
-| `ELFA_HMAC_SECRET` | no | Signs Auto mutations when signing is required. Notification-only query mutations do not need it |
 | `ELFA_TIMEOUT` | no | Request timeout in ms, default `120000` |
 | `ELFA_RETRIES` | no | Retries on failure, default `0` |
 | `ELFA_MCP_MAX_RESPONSE_CHARS` | no | Response size ceiling, default `60000` |
@@ -58,8 +57,6 @@ The timeout is high and retries are off on purpose. The interpretation endpoints
 
 Some MCP clients apply their own timeout, often around 60 seconds. `narratives` and `market_chat` can exceed that; the request still completes and is still charged, even if the client gives up first.
 
-Without `ELFA_HMAC_SECRET` notification-only Auto mutations still work. Anything else returns a message telling you what to set.
-
 ## Tools
 
 <!-- tools:start -->
@@ -69,10 +66,10 @@ Without `ELFA_HMAC_SECRET` notification-only Auto mutations still work. Anything
 | Tool | Mode | Cost | What it does |
 | --- | --- | --- | --- |
 | `api_status` | read | Free | Check API key tier, credit usage and remaining requests. Also confirms the API is reachable. |
-| `mentions` | read | 1 per call | Social mentions from X and Telegram. mode=top ranks a ticker's mentions by engagement, mode=search filters by keyword or account, mode=news returns the token news feed. |
+| `mentions` | read | 1 per call | Social mentions from X and Telegram. mode=top ranks a ticker's mentions by engagement, mode=search filters by keyword or account, mode=news returns the token news feed, which is X posts from accounts tagged as news sources rather than articles from news outlets. |
 | `trending` | read | 1 per call | What is gaining social attention. scope=tokens for tickers, scope=contracts_twitter or scope=contracts_telegram for contract addresses. |
 | `narratives` | read | 5 per call | Written narrative analysis with source links. scope=market extracts market-wide narratives, scope=keywords summarises events for specific keywords. |
-| `account_stats` | read | 1 per call | Smart follower and engagement stats for an X account. |
+| `account_stats` | read | 1 per call | Smart follower and engagement stats for an X account. Legacy: it still works, but will be removed on 28 October 2026. |
 | `market_chat` | read | Varies by speed | Ask for written market analysis. Supports conversational chat, macro overview, quick summary, token intro, token analysis and account analysis. |
 | `auto_build` | read | 1 plus LLM usage | Turn a plain-language monitoring request into an EQL query. Returns a draft to validate and activate, it does not activate anything itself. |
 | `auto_validate` | read | Free | Check EQL syntax and get a cost estimate before activating, or check that a symbol has market data on a venue. |
@@ -85,9 +82,6 @@ Not exposed as tools:
 - `chat-stream-v2` — A tool call returns one result, so streaming adds nothing. market_chat covers the same analysis.
 - `auto-stream-queries-v2` — Long lived streams have no tool equivalent. Poll with auto_query.
 - `auto-stream-query-v2` — Long lived streams have no tool equivalent. Poll with auto_query.
-- `auto-list-exchanges-v2` — Exchange connections are no longer part of the documented Auto surface.
-- `auto-connect-exchange-v2` — Exchange connections are no longer part of the documented Auto surface.
-- `auto-disconnect-exchange-v2` — Exchange connections are no longer part of the documented Auto surface.
 
 <!-- tools:end -->
 
@@ -128,7 +122,61 @@ The same server runs over Streamable HTTP for hosted deployments:
 ELFA_MCP_TRANSPORT=http ELFA_MCP_PORT=3000 npx -y @elfa-ai/mcp
 ```
 
-It is stateless — no sessions, one server instance per request, safe behind a load balancer. Credentials come from `x-elfa-api-key` and `x-elfa-hmac-secret` request headers, falling back to the environment. Set `ELFA_MCP_ALLOWED_ORIGINS` to a comma separated allowlist when exposing it publicly.
+It is stateless — no sessions, one server instance per request, safe behind a load balancer. Credentials come from the `x-elfa-api-key` request header, falling back to the environment, or from an OAuth sign-in (see below).
+
+DNS rebinding protection is on by default. The server accepts only the loopback names it binds — `localhost:PORT` and `127.0.0.1:PORT` — which covers the local run above and nothing else. Any deployment that answers on a different `Host` must list the values it serves:
+
+```bash
+ELFA_MCP_ALLOWED_HOSTS=mcp.example.com
+```
+
+That includes a public domain, a reverse proxy, and a container that maps the port to a different one than the server binds. A `Host` the list does not cover is rejected with 403.
+
+| Variable | Required | Purpose |
+| --- | --- | --- |
+| `ELFA_MCP_TRANSPORT` | no | `http` to serve over Streamable HTTP, default `stdio` |
+| `ELFA_MCP_HOST` | no | Bind address, default `127.0.0.1` |
+| `ELFA_MCP_PORT` | no | Bind port, default `3000` |
+| `ELFA_MCP_ALLOWED_HOSTS` | no | Comma separated `Host` allowlist, defaults to the loopback names bound |
+| `ELFA_MCP_ALLOWED_ORIGINS` | no | Comma separated `Origin` allowlist |
+
+Set `ELFA_MCP_ALLOWED_ORIGINS` as well when browsers call the server directly. It complements the host allowlist rather than replacing it: a rebound request is same origin, so it carries no `Origin` header for that list to check, and the `Host` header is the only one still naming the attacker's domain.
+
+### OAuth sign-in
+
+A hosted server can let clients sign in through a browser instead of sending an API key. Set `ELFA_MCP_AUTH=oauth` and the server becomes an OAuth resource server under the MCP authorization spec:
+
+1. A request with no credential gets `401` and a `WWW-Authenticate` challenge.
+2. The challenge points the client to the protected-resource metadata at `/.well-known/oauth-protected-resource/mcp`.
+3. That metadata names the authorization server, where the user signs in.
+4. The client then sends `Authorization: Bearer <token>`.
+5. The server checks the token against the authorization server's introspection endpoint. The endpoint answers with the Elfa API key the request runs as, so the token never reaches the Elfa API.
+
+```bash
+ELFA_MCP_TRANSPORT=http \
+ELFA_MCP_AUTH=oauth \
+ELFA_MCP_RESOURCE_URL=https://mcp.example.com/mcp \
+ELFA_OAUTH_ISSUER=https://auth.example.com \
+ELFA_OAUTH_INTROSPECTION_URL=https://auth.example.com/introspect \
+ELFA_OAUTH_INTROSPECTION_TOKEN=... \
+ELFA_MCP_ALLOWED_HOSTS=mcp.example.com \
+npx -y @elfa-ai/mcp
+```
+
+| Variable | Required in OAuth mode | Purpose |
+| --- | --- | --- |
+| `ELFA_MCP_AUTH` | yes | `oauth` to enable, default `apikey` |
+| `ELFA_MCP_RESOURCE_URL` | yes | Canonical URL of this endpoint. Tokens must be issued for exactly this value |
+| `ELFA_OAUTH_ISSUER` | yes | Authorization server listed in the metadata |
+| `ELFA_OAUTH_INTROSPECTION_URL` | yes | Where tokens are checked |
+| `ELFA_OAUTH_INTROSPECTION_TOKEN` | yes | Bearer sent to the introspection endpoint |
+| `ELFA_OAUTH_SCOPES` | no | Comma separated scopes to advertise, default `elfa` |
+
+Notes:
+
+- An `x-elfa-api-key` header still works in OAuth mode.
+- `ELFA_API_KEY` is ignored in OAuth mode, so a caller with no credential never runs as the server's own key.
+- Valid tokens are cached for up to a minute, which bounds how long a revoked token keeps working.
 
 ## Safety
 

package/dist/index.js

@@ -18,11 +18,8 @@ function messageOf(error) {
   if (typeof error === "string") return error;
   return "Unknown error";
 }
-function missingCredential(what) {
-  if (what === "apiKey") {
-    return `No Elfa API key configured. Set ELFA_API_KEY in the MCP server environment, or send it as an x-elfa-api-key header when using the HTTP transport. Get a key at ${DOCS}.`;
-  }
-  return `This action requires request signing. Set ELFA_HMAC_SECRET in the MCP server environment, then retry. Notification-only Auto queries work without it. See ${DOCS}/auto/api-key-auth.`;
+function missingCredential() {
+  return `No Elfa API key configured. Set ELFA_API_KEY in the MCP server environment, or send it as an x-elfa-api-key header when using the HTTP transport. Get a key at ${DOCS}.`;
 }
 function describeError(error) {
   const status = statusOf(error);
@@ -31,7 +28,7 @@ function describeError(error) {
     case 400:
       return `Request rejected as invalid: ${detail}. Check the argument values and retry.`;
     case 401:
-      return `Authentication failed: ${detail}. Verify ELFA_API_KEY, and ELFA_HMAC_SECRET if this action requires signing.`;
+      return `Authentication failed: ${detail}. Verify ELFA_API_KEY.`;
     case 402:
       return `Out of credits: ${detail}. Top up or upgrade the plan, then retry.`;
     case 403:
@@ -60,21 +57,18 @@ var CredentialError = class extends Error {
 };
 function buildDeps(config, overrides = {}) {
   const apiKey = overrides.apiKey ?? config.apiKey;
-  const hmacSecret = overrides.hmacSecret ?? config.hmacSecret;
   if (!apiKey) {
-    throw new CredentialError(missingCredential("apiKey"));
+    throw new CredentialError(missingCredential());
   }
   const sdk = new ElfaSDK({
     elfaApiKey: apiKey,
     timeout: config.timeout,
     retries: config.retries,
-    ...hmacSecret ? { hmacSecret } : {},
     ...config.baseUrl ? { baseUrl: config.baseUrl } : {},
     ...config.extraHeaders ? { headers: config.extraHeaders } : {}
   });
   return {
     sdk,
-    hasHmac: Boolean(hmacSecret),
     maxResponseChars: config.maxResponseChars
   };
 }
@@ -118,15 +112,44 @@ function list(value) {
   if (!value) return [];
   return value.split(",").map((entry) => entry.trim()).filter(Boolean);
 }
+var ConfigError = class extends Error {
+};
+function oauthConfig(env) {
+  const required = {
+    ELFA_MCP_RESOURCE_URL: env.ELFA_MCP_RESOURCE_URL,
+    ELFA_OAUTH_ISSUER: env.ELFA_OAUTH_ISSUER,
+    ELFA_OAUTH_INTROSPECTION_URL: env.ELFA_OAUTH_INTROSPECTION_URL,
+    ELFA_OAUTH_INTROSPECTION_TOKEN: env.ELFA_OAUTH_INTROSPECTION_TOKEN
+  };
+  const missing = Object.entries(required).filter(([, value]) => !value).map(([name]) => name);
+  if (missing.length > 0) {
+    throw new ConfigError(
+      `ELFA_MCP_AUTH=oauth requires ${missing.join(", ")}.`
+    );
+  }
+  return {
+    resource: required.ELFA_MCP_RESOURCE_URL,
+    issuer: required.ELFA_OAUTH_ISSUER,
+    introspectionUrl: required.ELFA_OAUTH_INTROSPECTION_URL,
+    introspectionToken: required.ELFA_OAUTH_INTROSPECTION_TOKEN,
+    scopes: list(env.ELFA_OAUTH_SCOPES).length > 0 ? list(env.ELFA_OAUTH_SCOPES) : ["elfa"]
+  };
+}
 function loadConfig(env = process.env) {
   const transport = env.ELFA_MCP_TRANSPORT === "http" ? "http" : "stdio";
+  const auth = env.ELFA_MCP_AUTH === "oauth" ? "oauth" : "apikey";
+  if (auth === "oauth" && transport !== "http") {
+    throw new ConfigError("ELFA_MCP_AUTH=oauth needs ELFA_MCP_TRANSPORT=http.");
+  }
   return {
     transport,
     port: num(env.ELFA_MCP_PORT, DEFAULT_PORT),
     host: env.ELFA_MCP_HOST || DEFAULT_HOST,
     allowedOrigins: list(env.ELFA_MCP_ALLOWED_ORIGINS),
-    apiKey: env.ELFA_API_KEY || void 0,
-    hmacSecret: env.ELFA_HMAC_SECRET || void 0,
+    allowedHosts: list(env.ELFA_MCP_ALLOWED_HOSTS),
+    // In oauth mode every request brings its own credential. An environment
+    // key would be handed to any caller that sends none, so it is ignored.
+    apiKey: auth === "oauth" ? void 0 : env.ELFA_API_KEY || void 0,
     baseUrl: env.ELFA_BASE_URL || void 0,
     extraHeaders: headers(env.ELFA_EXTRA_HEADERS),
     timeout: num(env.ELFA_TIMEOUT, DEFAULT_TIMEOUT),
@@ -134,7 +157,9 @@ function loadConfig(env = process.env) {
     maxResponseChars: num(
       env.ELFA_MCP_MAX_RESPONSE_CHARS,
       DEFAULT_MAX_RESPONSE_CHARS
-    )
+    ),
+    auth,
+    oauth: auth === "oauth" ? oauthConfig(env) : void 0
   };
 }
 
@@ -148,7 +173,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 // package.json
 var package_default = {
   name: "@elfa-ai/mcp",
-  version: "3.0.0",
+  version: "4.2.0",
   description: "Model Context Protocol server for the Elfa API - crypto social intelligence and the Auto condition engine",
   license: "MIT",
   author: "Elfa AI",
@@ -337,29 +362,6 @@ function pickDefined(input) {
   }
   return out;
 }
-var NOTIFICATION_ACTIONS = /* @__PURE__ */ new Set(["notify", "telegram_bot", "webhook"]);
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function isNotificationAction(action) {
-  if (!isRecord(action)) return false;
-  if (typeof action.type !== "string") return false;
-  if (NOTIFICATION_ACTIONS.has(action.type)) return true;
-  if (action.type === "llm") {
-    if (!isRecord(action.params)) return false;
-    if (!isRecord(action.params.callback)) return false;
-    const callbackAction = action.params.callback.action;
-    if (!isRecord(callbackAction)) return false;
-    return typeof callbackAction.type === "string" && NOTIFICATION_ACTIONS.has(callbackAction.type);
-  }
-  return false;
-}
-function requiresSignature(query) {
-  if (!isRecord(query)) return true;
-  const actions = query.actions;
-  if (!Array.isArray(actions) || actions.length === 0) return true;
-  return !actions.every(isNotificationAction);
-}
 
 // src/tools/account.ts
 function registerAccountStats(server, deps) {
@@ -367,7 +369,7 @@ function registerAccountStats(server, deps) {
     "account_stats",
     {
       title: "Account stats",
-      description: "Smart follower and engagement stats for an X account. 1 credit per call. Use it to judge whether an account's reach is real before weighting what it posts.",
+      description: "Smart follower and engagement stats for an X account. 1 credit per call. Use it to judge whether an account's reach is real before weighting what it posts. Returns raw metrics, not a reputation score, so the signal is in the ratios. Legacy: it still works today and keeps working until 28 October 2026, when it will be removed, and it is not being extended before then. Build new work on mentions with mode=search, which returns the posting account alongside each post's engagement metrics.",
       inputSchema: {
         username: z2.string().describe("X username, with or without the @.")
       },
@@ -486,9 +488,6 @@ function registerAutoDraft(server, deps) {
         if (!args.query) {
           return fail("method=upsert needs a query. Build one with auto_build.");
         }
-        if (requiresSignature(args.query) && !deps.hasHmac) {
-          return fail(missingCredential("hmacSecret"));
-        }
       }
       const needsId = args.method === "get" || args.method === "delete" || args.method === "convert";
       if (needsId && !args.draftId) {
@@ -656,7 +655,7 @@ function registerAutoQueryWrite(server, deps) {
     "auto_query_write",
     {
       title: "Write Auto queries",
-      description: "Activate, cancel or delete an Auto query. Creating costs 5 credits plus LLM usage, cancel and delete are free. An activated query runs unattended and fires its action without asking again, so validate it with auto_validate and confirm the cost and the action with the user before calling this. Queries whose action is not a plain notification also need request signing.",
+      description: "Activate, cancel or delete an Auto query. Creating costs 5 credits plus LLM usage, cancel and delete are free. An activated query runs unattended and fires its action without asking again, so validate it with auto_validate and confirm the cost and the action with the user before calling this.",
       inputSchema: {
         method: z6.enum(["create", "cancel", "delete"]).describe(
           "create activates a new query. cancel stops an active one. delete removes one that has already finished."
@@ -682,9 +681,6 @@ function registerAutoQueryWrite(server, deps) {
         if (!args.query) {
           return fail("method=create needs a query. Build one with auto_build.");
         }
-        if (requiresSignature(args.query) && !deps.hasHmac) {
-          return fail(missingCredential("hmacSecret"));
-        }
       } else if (!args.queryId) {
         return fail(`method=${args.method} needs queryId. Find one with auto_query.`);
       }
@@ -708,7 +704,7 @@ function registerAutoQueryWrite(server, deps) {
 
 // src/tools/autoValidate.ts
 import { z as z7 } from "zod";
-var EXCHANGES = ["hyperliquid", "gmx", "binance", "pacifica"];
+var EXCHANGES = ["hyperliquid", "gmx", "binance"];
 function registerAutoValidate(server, deps) {
   server.registerTool(
     "auto_validate",
@@ -869,7 +865,7 @@ function registerMentions(server, deps) {
     "mentions",
     {
       title: "Mentions",
-      description: "Social mentions from X and Telegram. 1 credit per call. Returns engagement metrics and a link per post, not the post text. mode=top ranks one ticker's mentions by engagement. mode=search filters by keywords or by account. mode=news returns the token news feed.",
+      description: "Social mentions from X and Telegram. 1 credit per call. Returns engagement metrics and a link per post, not the post text. mode=top ranks one ticker's mentions by engagement. mode=search filters by keywords or by account. mode=news returns the token news feed, which is X posts from accounts tagged as news sources rather than articles from news outlets.",
       inputSchema: {
         mode: z9.enum(["top", "search", "news"]).describe(
           "top needs ticker. search needs keywords or accountName. news is a feed and needs neither."
@@ -1116,7 +1112,6 @@ var REPORTED = [
   "depositCredits",
   "spendCapCredits",
   "athenaEnabled",
-  "hmacEnabled",
   "scopes"
 ];
 function summarise(data) {
@@ -1242,7 +1237,7 @@ var INSTRUCTIONS = `Elfa gives you crypto social intelligence plus Auto, a condi
 
 Start cheap. trending, mentions and account_stats cost 1 credit. narratives costs 5 and market_chat costs more, so reach for them only when metrics are not enough. If a call fails on auth or credits, check api_status.
 
-Auto is a three step flow: auto_build drafts EQL from plain language, auto_validate checks it and returns the cost, auto_query_write activates it. Never activate without showing the user the estimated cost and the action that will fire. Some Auto mutations need ELFA_HMAC_SECRET set; notification-only ones do not.
+Auto is a three step flow: auto_build drafts EQL from plain language, auto_validate checks it and returns the cost, auto_query_write activates it. Never activate without showing the user the estimated cost and the action that will fire.
 
 Auto has no push channel here. Poll auto_query with method=get and wait for pollAfterSeconds between calls.
 
@@ -1266,6 +1261,111 @@ function createServer(deps) {
   return server;
 }
 
+// src/oauth.ts
+import { createHash } from "crypto";
+var CACHE_TTL_MS = 6e4;
+var CACHE_MAX_ENTRIES = 1e4;
+var INTROSPECTION_TIMEOUT_MS = 5e3;
+var IntrospectionUnavailableError = class extends Error {
+};
+function protectedResourceMetadataPath(resource) {
+  const { pathname } = new URL(resource);
+  const suffix = pathname === "/" ? "" : pathname.replace(/\/+$/, "");
+  return `/.well-known/oauth-protected-resource${suffix}`;
+}
+function protectedResourceMetadataUrl(resource) {
+  const url = new URL(resource);
+  return `${url.origin}${protectedResourceMetadataPath(resource)}`;
+}
+function protectedResourceMetadata(config) {
+  return {
+    resource: config.resource,
+    authorization_servers: [config.issuer],
+    scopes_supported: config.scopes,
+    bearer_methods_supported: ["header"],
+    resource_name: "Elfa",
+    resource_documentation: "https://docs.elfa.ai/mcp"
+  };
+}
+function bearerChallenge(config, error) {
+  const parts = [
+    `resource_metadata="${protectedResourceMetadataUrl(config.resource)}"`,
+    `scope="${config.scopes.join(" ")}"`
+  ];
+  if (error) {
+    parts.unshift(`error="${error.code}"`);
+    parts.push(`error_description="${error.description.replace(/"/g, "'")}"`);
+  }
+  return `Bearer ${parts.join(", ")}`;
+}
+function bearerToken(authorization) {
+  if (!authorization) return void 0;
+  const match = /^Bearer\s+(\S+)\s*$/i.exec(authorization);
+  return match?.[1];
+}
+var TokenVerifier = class {
+  constructor(config, fetchImpl = fetch, now = Date.now) {
+    this.config = config;
+    this.fetchImpl = fetchImpl;
+    this.now = now;
+  }
+  config;
+  fetchImpl;
+  now;
+  cache = /* @__PURE__ */ new Map();
+  /** The API key for a valid token, or undefined when the token is not valid. */
+  async verify(token) {
+    const cacheKey = createHash("sha256").update(token).digest("hex");
+    const cached = this.cache.get(cacheKey);
+    if (cached && cached.expiresAtMs > this.now()) return cached;
+    if (cached) this.cache.delete(cacheKey);
+    const body = await this.introspect(token);
+    if (!body.active || typeof body.elfa_api_key !== "string") return void 0;
+    const audiences = Array.isArray(body.aud) ? body.aud : [body.aud];
+    if (!audiences.includes(this.config.resource)) return void 0;
+    const tokenExpiryMs = typeof body.exp === "number" ? body.exp * 1e3 : this.now() + CACHE_TTL_MS;
+    if (tokenExpiryMs <= this.now()) return void 0;
+    const verified = {
+      apiKey: body.elfa_api_key,
+      expiresAtMs: Math.min(tokenExpiryMs, this.now() + CACHE_TTL_MS)
+    };
+    if (this.cache.size >= CACHE_MAX_ENTRIES) {
+      const oldest = this.cache.keys().next().value;
+      if (oldest !== void 0) this.cache.delete(oldest);
+    }
+    this.cache.set(cacheKey, verified);
+    return verified;
+  }
+  async introspect(token) {
+    let response;
+    try {
+      response = await this.fetchImpl(this.config.introspectionUrl, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${this.config.introspectionToken}`,
+          "content-type": "application/json"
+        },
+        body: JSON.stringify({ token }),
+        signal: AbortSignal.timeout(INTROSPECTION_TIMEOUT_MS)
+      });
+    } catch (error) {
+      throw new IntrospectionUnavailableError(
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+    if (!response.ok) {
+      throw new IntrospectionUnavailableError(
+        `introspection returned HTTP ${response.status}`
+      );
+    }
+    try {
+      return await response.json();
+    } catch {
+      throw new IntrospectionUnavailableError("introspection returned invalid JSON");
+    }
+  }
+};
+
 // src/http.ts
 var MCP_PATH = "/mcp";
 function header(req, name) {
@@ -1279,8 +1379,18 @@ function jsonRpcError(res, status, message) {
     id: null
   });
 }
-function createHttpApp(config) {
+function defaultAllowedHosts(config) {
+  const hosts = /* @__PURE__ */ new Set();
+  for (const name of [config.host, "localhost", "127.0.0.1", "[::1]"]) {
+    hosts.add(`${name}:${config.port}`);
+    if (config.port === 80) hosts.add(name);
+  }
+  return [...hosts];
+}
+function createHttpApp(config, options = {}) {
   const app = express();
+  const oauth = config.oauth;
+  const verifier = options.verifier ?? (oauth ? new TokenVerifier(oauth) : void 0);
   app.disable("x-powered-by");
   app.use(express.json({ limit: "4mb" }));
   app.use(
@@ -1295,6 +1405,47 @@ function createHttpApp(config) {
   app.get("/healthz", (_req, res) => {
     res.json({ ok: true });
   });
+  if (oauth) {
+    const sendMetadata = (_req, res) => {
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Cache-Control", "public, max-age=300");
+      res.json(protectedResourceMetadata(oauth));
+    };
+    const metadataPath = protectedResourceMetadataPath(oauth.resource);
+    app.get(metadataPath, sendMetadata);
+    if (metadataPath !== "/.well-known/oauth-protected-resource") {
+      app.get("/.well-known/oauth-protected-resource", sendMetadata);
+    }
+  }
+  async function resolveApiKey(req, res) {
+    const headerKey = header(req, "x-elfa-api-key");
+    if (headerKey || !oauth || !verifier) return headerKey ?? null;
+    const token = bearerToken(header(req, "authorization"));
+    if (!token) {
+      res.setHeader("WWW-Authenticate", bearerChallenge(oauth));
+      jsonRpcError(res, 401, "Authorization required. Sign in to Elfa to use this server.");
+      return void 0;
+    }
+    try {
+      const verified = await verifier.verify(token);
+      if (verified) return verified.apiKey;
+    } catch (error) {
+      if (error instanceof IntrospectionUnavailableError) {
+        jsonRpcError(res, 503, "Authorization service unavailable, try again shortly.");
+        return void 0;
+      }
+      throw error;
+    }
+    res.setHeader(
+      "WWW-Authenticate",
+      bearerChallenge(oauth, {
+        code: "invalid_token",
+        description: "The access token is invalid or expired"
+      })
+    );
+    jsonRpcError(res, 401, "Invalid or expired access token.");
+    return void 0;
+  }
   app.post(MCP_PATH, async (req, res) => {
     const origin = header(req, "origin");
     if (origin && config.allowedOrigins.length > 0 && !config.allowedOrigins.includes(origin)) {
@@ -1304,13 +1455,14 @@ function createHttpApp(config) {
     let server;
     let transport;
     try {
-      const deps = buildDeps(config, {
-        apiKey: header(req, "x-elfa-api-key"),
-        hmacSecret: header(req, "x-elfa-hmac-secret")
-      });
+      const apiKey = await resolveApiKey(req, res);
+      if (apiKey === void 0) return;
+      const deps = buildDeps(config, { apiKey: apiKey ?? void 0 });
       server = createServer(deps);
       transport = new StreamableHTTPServerTransport({
-        ...config.allowedOrigins.length > 0 ? { allowedOrigins: config.allowedOrigins, enableDnsRebindingProtection: true } : {}
+        enableDnsRebindingProtection: true,
+        allowedHosts: config.allowedHosts.length > 0 ? config.allowedHosts : defaultAllowedHosts(config),
+        ...config.allowedOrigins.length > 0 ? { allowedOrigins: config.allowedOrigins } : {}
       });
       res.on("close", () => {
         void transport?.close();

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "server": {
     "name": "elfa",
-    "version": "3.0.0",
+    "version": "4.2.0",
     "docs": "https://docs.elfa.ai",
     "spec": "https://docs.elfa.ai/swagger/swagger.json",
     "specScope": "/v2"
@@ -26,7 +26,7 @@
     {
       "name": "mentions",
       "title": "Mentions",
-      "summary": "Social mentions from X and Telegram. mode=top ranks a ticker's mentions by engagement, mode=search filters by keyword or account, mode=news returns the token news feed.",
+      "summary": "Social mentions from X and Telegram. mode=top ranks a ticker's mentions by engagement, mode=search filters by keyword or account, mode=news returns the token news feed, which is X posts from accounts tagged as news sources rather than articles from news outlets.",
       "credits": "1 per call",
       "annotations": {
         "readOnlyHint": true,
@@ -76,7 +76,7 @@
     {
       "name": "account_stats",
       "title": "Account stats",
-      "summary": "Smart follower and engagement stats for an X account.",
+      "summary": "Smart follower and engagement stats for an X account. Legacy: it still works, but will be removed on 28 October 2026.",
       "credits": "1 per call",
       "annotations": {
         "readOnlyHint": true,
@@ -207,21 +207,6 @@
       "operationId": "auto-stream-query-v2",
       "reason": "sse",
       "note": "Long lived streams have no tool equivalent. Poll with auto_query."
-    },
-    {
-      "operationId": "auto-list-exchanges-v2",
-      "reason": "not-advertised",
-      "note": "Exchange connections are no longer part of the documented Auto surface."
-    },
-    {
-      "operationId": "auto-connect-exchange-v2",
-      "reason": "not-advertised",
-      "note": "Exchange connections are no longer part of the documented Auto surface."
-    },
-    {
-      "operationId": "auto-disconnect-exchange-v2",
-      "reason": "not-advertised",
-      "note": "Exchange connections are no longer part of the documented Auto surface."
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elfa-ai/mcp",
-  "version": "3.0.0",
+  "version": "4.2.0",
   "description": "Model Context Protocol server for the Elfa API - crypto social intelligence and the Auto condition engine",
   "license": "MIT",
   "author": "Elfa AI",