@ttoss/http-server-mcp 0.26.2 → 0.27.1

package/MIGRATIONS.md

@@ -0,0 +1,38 @@
+# Migrations
+
+## `tools/list` is no longer public by default
+
+`auth.publicMethods` now defaults to `['initialize']` instead of
+`['initialize', 'tools/list']`. A server with `auth` configured no longer
+serves its tool catalogue to unauthenticated callers.
+
+```diff
+ createMcpRouter(mcpServer, {
+   auth: {
+     cognitoUserPool: { userPoolId: '...', clientId: '...' },
++    // Only needed if unauthenticated callers must keep listing tools.
++    publicMethods: ['initialize', 'tools/list'],
+   },
+ });
+```
+
+**What you will observe if you miss this.** An unauthenticated `tools/list`
+returns `401` with `WWW-Authenticate: Bearer resource_metadata="…"` instead of
+`200` and the catalogue. It fails on the first such request rather than on
+particular inputs, so a smoke test against a deployed server surfaces it
+immediately.
+
+**Who is affected.** Only consumers that configure `auth` and never set
+`publicMethods`. Anyone already passing `publicMethods` — including
+`publicMethods: []` — is unaffected, and so is any server without `auth`.
+
+**Who should not restore the old value.** OAuth clients do not need it. The
+`401` and its RFC 9728 challenge are what start the authorization flow, and a
+client that lists tools anonymously still cannot call one; the flow reaches the
+authorization redirect identically with `tools/list` open or closed. Restore it
+only to serve callers that will never authenticate, and note what that exposes:
+every tool name, description, and input schema, which for an OpenAPI-derived
+server is a map of the whole underlying API.
+
+The one-time startup warning that pre-announced this change is gone, since the
+default it warned about is now the secure one.

package/README.md

@@ -371,7 +371,7 @@ The `WWW-Authenticate: Bearer resource_metadata="…"` header is how MCP clients
 
 The two behaviors the [MCP authorization spec](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/authorization/) requires for client bootstrapping are built into the `auth` option, so you no longer need the hand-rolled middleware shown above:
 
-- **`publicMethods`** — JSON-RPC methods that bypass verification, read from the request body's `method` field. Defaults to `['initialize', 'tools/list']` so clients can discover the server before authenticating. Pass `[]` to require a token for every method, or a custom list to change the exempt set. Leaving it unset serves the full tool catalogue — every tool name, description, and input schema — to unauthenticated callers, and logs a one-time warning explaining that and how to close it. Set `publicMethods` explicitly (even to the same default) to silence the warning.
+- **`publicMethods`** — JSON-RPC methods that bypass verification, read from the request body's `method` field. Defaults to `['initialize', 'server/discover']` — the lifecycle handshake of each protocol era, which the spec sanctions so a client can complete it before it can discover the authorization server. Pass `[]` to require a token for every method, or a custom list to change the exempt set. Adding `tools/list` serves the full tool catalogue — every tool name, description, and input schema — to unauthenticated callers; see [`publicMethods` and OAuth clients](#publicmethods-and-oauth-clients) before doing so.
 - **`resourceMetadataUrl`** — the URL a `401` advertises as `WWW-Authenticate: Bearer resource_metadata="<url>"` (RFC 9728) instead of a bare `Bearer`, pointing MCP clients at the protected-resource metadata document. **You normally do not set it**: when the document is served — i.e. both `resourceServerUrl` and `authorizationServerUrl` are configured — it defaults to the RFC 9728 location this router serves it at, so the header and the routes cannot drift apart. When the document is not served, the header stays a bare `Bearer` rather than naming a location with no route. The field exists for the one configuration where this router deliberately does not serve the document — an `oauthServer()` in the same deployment already answers that path, so this router is mounted without `resourceServerUrl`/`authorizationServerUrl` to avoid two routers on one path, and has nothing to derive from. Compute the value with `protectedResourceMetadataUrl` from [`@ttoss/auth-core`](https://ttoss.dev/docs/modules/packages/auth-core) rather than typing it, so both halves apply the same §3.1 rule.
 
 ```typescript
@@ -383,12 +383,12 @@ createMcpRouter(mcpServer, {
     resourceServerUrl: 'https://mcp.example.com',
     authorizationServerUrl:
       'https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxx',
-    // publicMethods defaults to ['initialize', 'tools/list'].
+    // publicMethods defaults to ['initialize', 'server/discover'].
   },
 });
 ```
 
-Every field is optional, and the `publicMethods` default matches what MCP clients expect for discovery.
+Every field is optional.
 
 ### Supporting clients that connect to the bare origin
 
@@ -502,7 +502,7 @@ Creates a Koa router configured to handle MCP protocol requests.
     - `auth.verifyToken` — Custom async token verifier `(token: string) => Promise<unknown>`
     - `auth.requiredScopes` — Router-level scope guard; returns 403 if any scope is missing
     - `auth.resourceServerUrl` + `auth.authorizationServerUrl` — Enable the protected-resource metadata document, served at both `/.well-known/oauth-protected-resource` and the RFC 9728 path-derived `/.well-known/oauth-protected-resource<path>`; the metadata `resource` is set to `resourceServerUrl + path` so clients following `resource` land on the actual MCP endpoint
-    - `auth.publicMethods` — JSON-RPC methods that bypass verification (default `['initialize', 'tools/list']`)
+    - `auth.publicMethods` — JSON-RPC methods that bypass verification (default `['initialize', 'server/discover']`)
     - `auth.resourceMetadataUrl` — URL advertised in the RFC 9728 `WWW-Authenticate: Bearer resource_metadata="…"` header on a 401. Defaults to the location derived from `resourceServerUrl` + `path` (the one this router serves), so the header cannot drift from the routes; set it only when a separate `oauthServer()` serves the document and this router is mounted without `resourceServerUrl`/`authorizationServerUrl`
     - `auth.resourceIndicator` — Expected `aud` value(s) (RFC 8707); rejects tokens minted for a different resource. See [Resource indicator validation](#resource-indicator-validation-rfc-8707)
 
@@ -873,14 +873,19 @@ expect(call.status).toBe(200);
 
 ### `publicMethods` and OAuth clients
 
-`auth.publicMethods` defaults to `['initialize', 'tools/list']`, which lets clients discover the server before they have a token. This default has an important effect on OAuth-aware clients (e.g. a Claude connector):
+`auth.publicMethods` defaults to `['initialize', 'server/discover']`: the lifecycle handshake is reachable without a token, nothing else is. There are two entries because the exemption is about _the handshake_, not the method name — `initialize` is the 2025-era handshake and `server/discover` its `2026-07-28` replacement, since that revision removed `initialize` outright. Naming only one leaves the other era unable to negotiate at all.
 
-- With the default, `initialize` returns `200` unauthenticated, so an OAuth client concludes the server is public and never starts the OAuth flow — while `notifications/initialized` still returns `401`, breaking the handshake. The visible symptom is "connected, no tools available, no sign-in prompt".
-- Setting `publicMethods: []` makes `initialize` return `401` + `WWW-Authenticate`, which triggers the client's OAuth discovery and PKCE flow.
+**Adding `tools/list` is a deliberate exposure.** It serves the full tool catalogue — every name, description, and input schema — to anyone who can reach the endpoint. Those leak internal resource names and domain vocabulary, and for an OpenAPI-derived server the schemas mirror the REST surface, so the catalogue becomes an unauthenticated map of the whole API including operations the caller could never invoke. It buys an OAuth client nothing, because the `401` is what starts the authorization flow and a client that lists tools anonymously still cannot call one. Open it only to serve callers that will never authenticate:
 
-Use the default when token auth is handled outside the OAuth flow (Cognito, API keys, Bearer tokens). Set `publicMethods: []` only when you want OAuth clients to self-discover and authenticate before anything else.
+```typescript
+publicMethods: ['initialize', 'tools/list'],
+```
+
+**Whether `initialize` should be public depends on how tokens are issued.** Keep the default when token auth is handled outside the OAuth flow (Cognito, API keys, Bearer tokens minted elsewhere). Set `publicMethods: []` when you want OAuth clients to authenticate before anything else — `initialize` then returns `401` + `WWW-Authenticate` on the very first request, so discovery starts there rather than one step later.
 
-Leaving `publicMethods` unset also exposes the full tool catalogue (`tools/list`) to unauthenticated callers — a tool's name, description, and input schema can leak internal resource names and, for an OpenAPI-derived server, the shape of the whole underlying API. A one-time warning is logged when `auth` is configured without an explicit `publicMethods`, naming the exposure and how to close it. This default is a candidate to tighten to `['initialize']` in a future major; track the decision in [ttoss/ttoss#1176](https://github.com/ttoss/ttoss/issues/1176).
+Either way the authorization flow works. Driving the official MCP client SDK against this router shows the RFC 9728 challenge resolving to the protected-resource document, the authorization server, and the redirect, whether the `401` arrives on `initialize` (`publicMethods: []`) or on the request after it (the default). `tests/unit/tests/oauth-client-flow.test.ts` asserts it.
+
+**Whether the handshake should be public at all is a separate question.** `publicMethods: []` closes both eras, and the authorization flow still works — RFC 9728 discovery is driven by the challenge itself, so a client authenticates from its very first request instead of one step later.
 
 ## AWS Lambda Deployment
 
@@ -931,6 +936,12 @@ Keep the following in mind:
 
 > This differs from [`awslabs/run-model-context-protocol-servers-with-aws-lambda`](https://github.com/awslabs/run-model-context-protocol-servers-with-aws-lambda), which wraps **stdio**-based MCP servers into Lambda by spawning a child process per invocation. `@ttoss/http-server-mcp` already speaks Streamable HTTP, so that wrapper is unnecessary — you deploy it like any other HTTP handler.
 
+## Migrations
+
+Breaking changes and what they require of consumers are listed in
+[MIGRATIONS.md](https://github.com/ttoss/ttoss/blob/main/packages/http-server-mcp/MIGRATIONS.md),
+newest first.
+
 ## Related Packages
 
 - [@ttoss/http-server](https://ttoss.dev/docs/modules/packages/http-server) - HTTP server foundation

package/dist/index.cjs

@@ -326,8 +326,24 @@ var createGatedToolRegistrar = ({
 
 //#endregion
 //#region src/index.ts
-/** MCP lifecycle/discovery methods reachable before a client authenticates. */
-var DEFAULT_PUBLIC_METHODS = ["initialize", "tools/list"];
+/**
+* MCP lifecycle handshakes reachable before a client authenticates.
+*
+* One entry per protocol era, because the exemption the MCP authorization spec
+* sanctions is about *the handshake* — a client has to complete it before it
+* can discover the authorization server — not about a method name:
+*
+* - `initialize` is the 2025-era handshake.
+* - `server/discover` is its `2026-07-28` replacement. That revision removed
+*   `initialize` entirely, so naming only `initialize` left the modern era
+*   with no public method at all — the asymmetry ttoss/ttoss#1222 fixed.
+*
+* A future revision that renames the handshake again needs a matching entry
+* here; nothing detects that automatically.
+*
+* `tools/list` is deliberately absent — see {@link McpAuthOptions.publicMethods}.
+*/
+var DEFAULT_PUBLIC_METHODS = ["initialize", "server/discover"];
 /**
 * Asserts that a verified token's `aud` claim includes at least one of the
 * expected resource indicator values. `aud` may be a single string or an
@@ -547,7 +563,6 @@ var createMcpRouter = (server, options = {}) => {
       })
     } : void 0;
     const resourceMetadataUrl = auth.resourceMetadataUrl ?? metadata?.url;
-    if (auth.publicMethods === void 0) console.warn(`[@ttoss/http-server-mcp] "auth" is configured but "publicMethods" was not set, so it defaults to ${JSON.stringify(DEFAULT_PUBLIC_METHODS)}. This means "tools/list" — the full tool catalogue, including names, descriptions, and input schemas — is served to unauthenticated callers. To require a token for "tools/list" too, set publicMethods: ['initialize']. To keep the current behaviour and silence this warning, set publicMethods: ${JSON.stringify(DEFAULT_PUBLIC_METHODS)} explicitly.`);
     const publicMethods = new Set(auth.publicMethods ?? DEFAULT_PUBLIC_METHODS);
     const verify = (0, _ttoss_http_server_auth.authMiddleware)({
       strategies: ["oauth"],

package/dist/index.d.cts

@@ -892,11 +892,35 @@ interface McpAuthOptions {
   requiredScopes?: string[];
   /**
    * JSON-RPC methods (read from `body.method`) that bypass verification.
-   * Leaving this unset serves `tools/list` — the full tool catalogue —
-   * to unauthenticated callers, and logs a one-time warning explaining how
-   * to close it. Set explicitly (even to the same default) to silence the
-   * warning; set to `['initialize']` to require a token for `tools/list` too.
-   * @default ['initialize', 'tools/list']
+   *
+   * The lifecycle handshake is public because the MCP authorization spec
+   * sanctions it: a client completes it before it can discover the
+   * authorization server. That means one entry per protocol era —
+   * `initialize` on 2025, `server/discover` on `2026-07-28`, which removed
+   * `initialize` — so neither era is left unable to negotiate. Nothing else
+   * is public, so a server with `auth` configured serves no tool metadata to
+   * an unauthenticated caller.
+   *
+   * Opening `tools/list` is a deliberate choice, not a default. It serves the
+   * full tool catalogue — every name, description, and input schema — to
+   * anyone who can reach the endpoint, which for an OpenAPI-derived server is
+   * a map of the whole underlying API. It buys an OAuth client nothing: the
+   * `401` and its RFC 9728 `WWW-Authenticate` challenge are what start the
+   * authorization flow, and a client that lists tools anonymously still
+   * cannot call one. Set it only to serve callers that will never
+   * authenticate.
+   *
+   * @default ['initialize', 'server/discover']
+   *
+   * @example
+   * ```typescript
+   * // Restore unauthenticated tool discovery.
+   * publicMethods: ['initialize', 'tools/list'],
+   *
+   * // Require a token for the handshake too, so an OAuth client
+   * // self-discovers from its very first request.
+   * publicMethods: [],
+   * ```
    */
   publicMethods?: string[];
   /**
@@ -1114,9 +1138,10 @@ interface McpRouterOptions {
    * OAuth / JWT authentication configuration for the MCP endpoint.
    *
    * When set, incoming MCP requests must include a valid Bearer token in the
-   * `Authorization` header — except for `publicMethods` (by default
-   * `initialize` and `tools/list`), which bypass verification so clients can
-   * discover the server before authenticating. Invalid or missing tokens
+   * `Authorization` header — except for `publicMethods` (by default the
+   * lifecycle handshake of each protocol era: `initialize` and
+   * `server/discover`), which bypass verification so a client can complete
+   * the handshake before authenticating. Invalid or missing tokens
    * receive a `401` response with `WWW-Authenticate: Bearer` (or
    * `Bearer resource_metadata="..."` when `resourceMetadataUrl` is set, per
    * RFC 9728). Tokens that fail a `requiredScopes` check receive `403`.

package/dist/index.d.mts

@@ -893,11 +893,35 @@ interface McpAuthOptions {
   requiredScopes?: string[];
   /**
    * JSON-RPC methods (read from `body.method`) that bypass verification.
-   * Leaving this unset serves `tools/list` — the full tool catalogue —
-   * to unauthenticated callers, and logs a one-time warning explaining how
-   * to close it. Set explicitly (even to the same default) to silence the
-   * warning; set to `['initialize']` to require a token for `tools/list` too.
-   * @default ['initialize', 'tools/list']
+   *
+   * The lifecycle handshake is public because the MCP authorization spec
+   * sanctions it: a client completes it before it can discover the
+   * authorization server. That means one entry per protocol era —
+   * `initialize` on 2025, `server/discover` on `2026-07-28`, which removed
+   * `initialize` — so neither era is left unable to negotiate. Nothing else
+   * is public, so a server with `auth` configured serves no tool metadata to
+   * an unauthenticated caller.
+   *
+   * Opening `tools/list` is a deliberate choice, not a default. It serves the
+   * full tool catalogue — every name, description, and input schema — to
+   * anyone who can reach the endpoint, which for an OpenAPI-derived server is
+   * a map of the whole underlying API. It buys an OAuth client nothing: the
+   * `401` and its RFC 9728 `WWW-Authenticate` challenge are what start the
+   * authorization flow, and a client that lists tools anonymously still
+   * cannot call one. Set it only to serve callers that will never
+   * authenticate.
+   *
+   * @default ['initialize', 'server/discover']
+   *
+   * @example
+   * ```typescript
+   * // Restore unauthenticated tool discovery.
+   * publicMethods: ['initialize', 'tools/list'],
+   *
+   * // Require a token for the handshake too, so an OAuth client
+   * // self-discovers from its very first request.
+   * publicMethods: [],
+   * ```
    */
   publicMethods?: string[];
   /**
@@ -1115,9 +1139,10 @@ interface McpRouterOptions {
    * OAuth / JWT authentication configuration for the MCP endpoint.
    *
    * When set, incoming MCP requests must include a valid Bearer token in the
-   * `Authorization` header — except for `publicMethods` (by default
-   * `initialize` and `tools/list`), which bypass verification so clients can
-   * discover the server before authenticating. Invalid or missing tokens
+   * `Authorization` header — except for `publicMethods` (by default the
+   * lifecycle handshake of each protocol era: `initialize` and
+   * `server/discover`), which bypass verification so a client can complete
+   * the handshake before authenticating. Invalid or missing tokens
    * receive a `401` response with `WWW-Authenticate: Bearer` (or
    * `Bearer resource_metadata="..."` when `resourceMetadataUrl` is set, per
    * RFC 9728). Tokens that fail a `requiredScopes` check receive `403`.

package/dist/index.mjs

@@ -323,8 +323,24 @@ var createGatedToolRegistrar = ({
 
 //#endregion
 //#region src/index.ts
-/** MCP lifecycle/discovery methods reachable before a client authenticates. */
-var DEFAULT_PUBLIC_METHODS = ["initialize", "tools/list"];
+/**
+* MCP lifecycle handshakes reachable before a client authenticates.
+*
+* One entry per protocol era, because the exemption the MCP authorization spec
+* sanctions is about *the handshake* — a client has to complete it before it
+* can discover the authorization server — not about a method name:
+*
+* - `initialize` is the 2025-era handshake.
+* - `server/discover` is its `2026-07-28` replacement. That revision removed
+*   `initialize` entirely, so naming only `initialize` left the modern era
+*   with no public method at all — the asymmetry ttoss/ttoss#1222 fixed.
+*
+* A future revision that renames the handshake again needs a matching entry
+* here; nothing detects that automatically.
+*
+* `tools/list` is deliberately absent — see {@link McpAuthOptions.publicMethods}.
+*/
+var DEFAULT_PUBLIC_METHODS = ["initialize", "server/discover"];
 /**
 * Asserts that a verified token's `aud` claim includes at least one of the
 * expected resource indicator values. `aud` may be a single string or an
@@ -544,7 +560,6 @@ var createMcpRouter = (server, options = {}) => {
       })
     } : void 0;
     const resourceMetadataUrl = auth.resourceMetadataUrl ?? metadata?.url;
-    if (auth.publicMethods === void 0) console.warn(`[@ttoss/http-server-mcp] "auth" is configured but "publicMethods" was not set, so it defaults to ${JSON.stringify(DEFAULT_PUBLIC_METHODS)}. This means "tools/list" — the full tool catalogue, including names, descriptions, and input schemas — is served to unauthenticated callers. To require a token for "tools/list" too, set publicMethods: ['initialize']. To keep the current behaviour and silence this warning, set publicMethods: ${JSON.stringify(DEFAULT_PUBLIC_METHODS)} explicitly.`);
     const publicMethods = new Set(auth.publicMethods ?? DEFAULT_PUBLIC_METHODS);
     const verify = authMiddleware({
       strategies: ["oauth"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.26.2",
+  "version": "0.27.1",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",
@@ -30,6 +30,7 @@
     }
   },
   "files": [
+    "MIGRATIONS.md",
     "dist"
   ],
   "dependencies": {
@@ -37,10 +38,11 @@
     "@modelcontextprotocol/server": "^2.0.0",
     "zod": "^4.4.3",
     "@ttoss/auth-core": "^0.14.1",
-    "@ttoss/http-server-auth": "^0.6.4",
-    "@ttoss/http-server": "^0.8.1"
+    "@ttoss/http-server": "^0.8.1",
+    "@ttoss/http-server-auth": "^0.6.4"
   },
   "devDependencies": {
+    "@modelcontextprotocol/client": "^2.0.0",
     "@types/koa": "^3.0.3",
     "jest": "^30.4.2",
     "supertest": "^7.2.2",