[ { "id": "BC-001", "title": "Remove @frontmcp/plugins meta-package", "package": "@frontmcp/plugins", "category": "removal", "severity": "high", "old": "import { CachePlugin } from '@frontmcp/plugins'", "new": "import { CachePlugin } from '@frontmcp/plugin-cache'", "migration": "Replace all @frontmcp/plugins imports with direct plugin package imports: @frontmcp/plugin-cache, @frontmcp/plugin-codecall, @frontmcp/plugin-dashboard, @frontmcp/plugin-remember.", "codemod": "yes" }, { "id": "BC-002", "title": "Remove LoadSkillTool alias", "package": "@frontmcp/sdk", "category": "removal", "severity": "low", "old": "import { LoadSkillTool } from '@frontmcp/sdk'", "new": "import { LoadSkillsTool } from '@frontmcp/sdk'", "migration": "Rename LoadSkillTool to LoadSkillsTool (note the plural 's').", "codemod": "yes" }, { "id": "BC-003", "title": "Remove ContextStorage alias", "package": "@frontmcp/sdk", "category": "removal", "severity": "low", "old": "import { ContextStorage } from '@frontmcp/sdk'", "new": "import { FrontMcpContextStorage } from '@frontmcp/sdk'", "migration": "Rename ContextStorage to FrontMcpContextStorage.", "codemod": "yes" }, { "id": "BC-004", "title": "Remove authInfo getter on ExecutionContextBase", "package": "@frontmcp/sdk", "category": "removal", "severity": "medium", "old": "this.authInfo", "new": "this.getAuthInfo()", "migration": "Replace direct property access `this.authInfo` with method call `this.getAuthInfo()` in tool/resource/prompt contexts.", "codemod": "yes" }, { "id": "BC-005", "title": "Remove session token from FrontMcpTokens", "package": "@frontmcp/sdk", "category": "removal", "severity": "low", "old": "FrontMcpTokens.session", "new": "No replacement - session token was unused.", "migration": "Remove any references to FrontMcpTokens.session.", "codemod": "no" }, { "id": "BC-006", "title": "Remove session/request aliases on ProviderViews", "package": "@frontmcp/sdk", "category": "removal", "severity": "medium", "old": "views.session or views.request", "new": "views.context", "migration": "Replace `views.session` and `views.request` with `views.context`.", "codemod": "yes" }, { "id": "BC-007", "title": "Remove deprecated createTemplateHelpersLocal from SDK", "package": "@frontmcp/sdk", "category": "removal", "severity": "low", "old": "import { createTemplateHelpersLocal } from '@frontmcp/sdk'", "new": "import { createTemplateHelpers } from '@frontmcp/uipack/runtime'", "migration": "Use createTemplateHelpers from @frontmcp/uipack/runtime instead of the deprecated local version.", "codemod": "yes" }, { "id": "BC-008", "title": "Remove legacy SSE transport", "package": "@frontmcp/sdk", "category": "removal", "severity": "high", "old": "import { SSEServerTransport } from '@frontmcp/sdk'", "new": "import { RecreateableSSEServerTransport } from '@frontmcp/sdk'", "migration": "Replace SSEServerTransport with RecreateableSSEServerTransport which supports session recreation.", "codemod": "yes" }, { "id": "BC-009", "title": "Remove CimdCache alias", "package": "@frontmcp/auth", "category": "removal", "severity": "low", "old": "import { CimdCache } from '@frontmcp/auth'", "new": "import { InMemoryCimdCache } from '@frontmcp/auth'", "migration": "Rename CimdCache to InMemoryCimdCache, or use the createCimdCache factory function.", "codemod": "yes" }, { "id": "BC-010", "title": "Remove dev-key-persistence module", "package": "@frontmcp/auth", "category": "removal", "severity": "medium", "old": "import { loadDevKey, saveDevKey } from '@frontmcp/auth'", "new": "import { createKeyPersistence } from '@frontmcp/utils'", "migration": "Replace loadDevKey/saveDevKey/deleteDevKey with createKeyPersistence() from @frontmcp/utils.", "codemod": "no" }, { "id": "BC-011", "title": "Remove TransportIdGenerator._mode parameter", "package": "@frontmcp/auth", "category": "change", "severity": "low", "old": "TransportIdGenerator.createId('jwt')", "new": "TransportIdGenerator.createId()", "migration": "Remove the _mode parameter from TransportIdGenerator.createId() calls.", "codemod": "yes" }, { "id": "BC-012", "title": "Remove WidgetServingModeLegacy type alias", "package": "@frontmcp/uipack", "category": "removal", "severity": "low", "old": "WidgetServingModeLegacy", "new": "WidgetServingMode", "migration": "Use WidgetServingMode instead of WidgetServingModeLegacy. Remove 'mcp-resource' value references.", "codemod": "yes" }, { "id": "BC-013", "title": "Remove RuntimePayload interface", "package": "@frontmcp/uipack", "category": "removal", "severity": "medium", "old": "import { RuntimePayload } from '@frontmcp/uipack'", "new": "Use the specific runtime types instead.", "migration": "Replace RuntimePayload with the appropriate specific runtime type.", "codemod": "no" }, { "id": "BC-014", "title": "Remove legacy renderer asset fields", "package": "@frontmcp/uipack", "category": "removal", "severity": "medium", "old": "reactRuntime, reactDomRuntime, markdownEngine, handlebarsRuntime", "new": "Use the CDN resource system instead.", "migration": "Remove legacy asset fields from renderer configuration. Use the CDN resource system for runtime dependencies.", "codemod": "no" }, { "id": "BC-015", "title": "Remove legacy build options", "package": "@frontmcp/uipack", "category": "removal", "severity": "medium", "old": "sampleInput, sampleOutput, injectAdapters, minify, platform", "new": "Use the updated build API.", "migration": "Remove deprecated build options: sampleInput, sampleOutput, injectAdapters, minify, platform.", "codemod": "no" }, { "id": "BC-016", "title": "Remove buildToolUIMulti and legacy build types", "package": "@frontmcp/uipack", "category": "removal", "severity": "medium", "old": "import { buildToolUIMulti, BuildTargetPlatform } from '@frontmcp/uipack'", "new": "Use buildToolUI with individual targets.", "migration": "Replace buildToolUIMulti with individual buildToolUI calls. Remove BuildTargetPlatform, MultiBuildOptions, MultiBuildResult type imports.", "codemod": "no" }, { "id": "BC-017", "title": "Remove frontmcp/* meta keys", "package": "@frontmcp/uipack", "category": "removal", "severity": "low", "old": "FrontMCPMetaFields interface", "new": "Use ui/* prefixed meta keys.", "migration": "Replace frontmcp/* meta keys with ui/* prefixed keys.", "codemod": "yes" }, { "id": "BC-018", "title": "Remove deprecated transpiler functions", "package": "@frontmcp/uipack", "category": "removal", "severity": "low", "old": "import { executeTranspiledCode, transpileAndExecute } from '@frontmcp/uipack'", "new": "Use the bundler API instead.", "migration": "Replace executeTranspiledCode and transpileAndExecute with the bundler API.", "codemod": "no" }, { "id": "BC-019", "title": "Remove DataTransformOptions alias", "package": "@frontmcp/adapters", "category": "removal", "severity": "low", "old": "import { DataTransformOptions } from '@frontmcp/adapters'", "new": "import { ResponseTransformOptions } from '@frontmcp/adapters'", "migration": "Rename DataTransformOptions to ResponseTransformOptions.", "codemod": "yes" }, { "id": "BC-020", "title": "Remove dataTransforms field alias", "package": "@frontmcp/adapters", "category": "removal", "severity": "low", "old": "dataTransforms: { ... }", "new": "responseTransforms: { ... }", "migration": "Rename the dataTransforms field to responseTransforms in OpenAPI adapter configuration.", "codemod": "yes" }, { "id": "BC-021", "title": "Remove deprecated reservePort", "package": "@frontmcp/testing", "category": "removal", "severity": "low", "old": "import { reservePort } from '@frontmcp/testing'", "new": "import { acquirePort } from '@frontmcp/testing'", "migration": "Replace reservePort with acquirePort from the port registry.", "codemod": "yes" }, { "id": "BC-022", "title": "Remove legacy test constants", "package": "@frontmcp/testing", "category": "removal", "severity": "low", "old": "EXPECTED_FRONTMCP_TOOLS_LIST_META_KEYS, EXPECTED_FRONTMCP_TOOL_CALL_META_KEYS", "new": "No replacement - these constants are no longer needed.", "migration": "Remove references to EXPECTED_FRONTMCP_TOOLS_LIST_META_KEYS and EXPECTED_FRONTMCP_TOOL_CALL_META_KEYS.", "codemod": "no" }, { "id": "BC-023", "title": "Remove ProviderScope.SESSION and ProviderScope.REQUEST", "package": "@frontmcp/di", "category": "removal", "severity": "high", "old": "scope: ProviderScope.SESSION or scope: ProviderScope.REQUEST", "new": "scope: ProviderScope.CONTEXT", "migration": "Replace ProviderScope.SESSION and ProviderScope.REQUEST with ProviderScope.CONTEXT. Both mapped to CONTEXT internally.", "codemod": "yes" }, { "id": "BC-026", "title": "Flatten auth modes", "package": "@frontmcp/auth", "category": "change", "severity": "high", "old": "auth: { mode: 'orchestrated', type: 'remote', remote: { provider: '...' } }", "new": "auth: { mode: 'remote', provider: '...' }", "migration": "Replace mode: 'orchestrated' with mode: 'local' or mode: 'remote'. Remove the type sub-discriminator. Flatten remote provider fields to top level.", "codemod": "yes" }, { "id": "BC-027", "title": "Flatten remote provider fields to top level", "package": "@frontmcp/auth", "category": "change", "severity": "high", "old": "auth: { mode: 'transparent', remote: { provider: '...', scopes: ['read'] } }", "new": "auth: { mode: 'transparent', provider: '...', scopes: ['read'] }", "migration": "Hoist remote.provider, remote.clientId, remote.clientSecret, remote.scopes to the top level of the auth config.", "codemod": "yes" }, { "id": "BC-028", "title": "Remove splitByApp auth restriction", "package": "@frontmcp/sdk", "category": "change", "severity": "medium", "old": "splitByApp: true with auth?: never", "new": "splitByApp: true with server-level auth allowed", "migration": "Server-level auth is now allowed in splitByApp mode. Apps inherit server auth by default and can override per-app.", "codemod": "no" }, { "id": "BC-029", "title": "Single source of truth for auth schemas", "package": "@frontmcp/sdk", "category": "change", "severity": "medium", "old": "Auth schemas duplicated in libs/sdk/src/common/types/options/auth/ and libs/auth/src/options/", "new": "Auth schemas only in libs/auth/src/options/, imported via @frontmcp/auth", "migration": "Import auth types from @frontmcp/auth instead of @frontmcp/sdk internal paths.", "codemod": "yes" }, { "id": "BC-030", "title": "Simplify advanced config nesting", "package": "@frontmcp/auth", "category": "change", "severity": "medium", "old": "tokenStorage: { type: 'redis', config: { host: '...' } }", "new": "tokenStorage: 'memory' | { redis: { host: '...' } }", "migration": "Simplify tokenStorage and cimd cache configuration to use flattened format.", "codemod": "yes" }, { "id": "BC-031", "title": "inputSchema accepts ZodRawShape only", "package": "@frontmcp/sdk", "category": "change", "severity": "medium", "old": "inputSchema: z.object({ name: z.string() })", "new": "inputSchema: { name: z.string() }", "migration": "Pass a plain object (ZodRawShape) to inputSchema instead of z.object(). Remove z.object() wrapper.", "codemod": "yes" }, { "id": "BC-032", "title": "Remove rawInputSchema/rawOutputSchema from user-facing API", "package": "@frontmcp/sdk", "category": "removal", "severity": "low", "old": "@Tool({ rawInputSchema: {...} })", "new": "Use inputSchema with ZodRawShape instead.", "migration": "Remove rawInputSchema and rawOutputSchema from @Tool() decorator options. Use inputSchema with ZodRawShape format.", "codemod": "yes" }, { "id": "BC-033", "title": "HTTP server binds loopback by default", "package": "@frontmcp/sdk", "category": "change", "severity": "high", "old": "// no security config → server bound 0.0.0.0 (all interfaces)", "new": "http: { security: { bindAddress: 'all' } } // or FRONTMCP_BIND_ADDRESS=all", "migration": "The HTTP transport now binds 127.0.0.1 unless told otherwise. A server that said nothing about security previously published itself on every interface, and since auth is opt-in that put unauthenticated tools, jobs and telemetry on the network by default. If your server must be reachable from another host — a container, a VM, behind a reverse proxy — set `http.security.bindAddress: 'all'` (or a specific address), or set the `FRONTMCP_BIND_ADDRESS=all` environment variable, which needs no rebuild and is the right fit for a Dockerfile or compose file. Distributed builds (`frontmcp build --target distributed`, which sets `FRONTMCP_DEPLOYMENT_MODE=distributed`) still bind all interfaces automatically. Local development and stdio transports are unaffected.", "codemod": "no" }, { "id": "BC-034", "title": "HTTP server sends no CORS headers by default", "package": "@frontmcp/sdk", "category": "change", "severity": "medium", "old": "// no cors config → { origin: true, credentials: false } (any origin reflected)", "new": "http: { cors: { origin: ['https://app.example.com'] } }", "migration": "CORS now defaults to off — no headers, so a browser will not let another origin read the response. The previous default reflected any request Origin, which meant any page a developer visited could read a local server's responses. If a browser on another origin needs access, configure it explicitly: `http.cors: { origin: [...] }`, or `http.cors: { origin: true }` to restore the old permissive behaviour. Non-browser clients are unaffected — CORS is not a server-side access control.", "codemod": "no" }, { "id": "BC-035", "title": "DNS-rebinding protection (Host validation) is on by default", "package": "@frontmcp/sdk", "category": "change", "severity": "medium", "old": "// no security config → Host/Origin never validated (any Host accepted)", "new": "http: { security: { dnsRebindingProtection: { allowedHosts: ['api.example.com'] } } }", "migration": "DNS-rebinding protection (`http.security.dnsRebindingProtection`) now defaults to ON. A request whose `Host` (or `X-Forwarded-Host`) is not one this server answers to gets a 403, before routing and before the body is read. This closes GHSA-mc9g-v2cp-vfff: a malicious page can rebind its own domain to the victim's loopback address and reach a local MCP server as a same-origin service, and neither loopback binding nor CORS prevents it.\n\nWhen `allowedHosts` is not configured it is derived from what the process actually listens on: the loopback aliases (`localhost`, `127.0.0.1`, `[::1]`, with and without the bound port). Matching is case-insensitive and treats `host` and `host:80`/`host:443` as equal. A Unix-socket listener derives nothing — the socket's filesystem permissions are the boundary and a rebound browser cannot reach it — so Host checking is skipped there.\n\nA server bound to a routable address (`0.0.0.0`, `::`, a specific NIC) is reached under a hostname the process cannot know, so a DERIVED list is NOT enforced there: FrontMCP logs a warning and leaves Host checking off until you name the public host. Set `http.security.dnsRebindingProtection.allowedHosts` (or the `FRONTMCP_ALLOWED_HOSTS` env var) on a proxied deployment to turn it on — the bound NIC address is then added to the list alongside your public name. To opt out entirely, set `http.security.dnsRebindingProtection.enabled: false`.\n\nAlso fixed: `strict: true` previously derived a port-less allow-list (`['localhost', '127.0.0.1']`) and compared it against a raw `Host`, so it rejected every request on a non-default port.", "codemod": "no" }, { "id": "BC-036", "title": "Dashboard auth requires a token, and enabled/auth cover its MCP endpoint", "package": "@frontmcp/plugin-dashboard", "category": "change", "severity": "medium", "old": "DashboardPlugin.init({ auth: { enabled: true } }) // parsed; neither the page nor the MCP endpoint checked a token", "new": "DashboardPlugin.init({ enabled: true, auth: { enabled: true, token: process.env.DASHBOARD_TOKEN } }) // MCP clients send it as Bearer or x-frontmcp-dashboard-token", "migration": "`dashboardAuthSchema` now rejects `auth.enabled: true` without a non-empty `auth.token`, so a half-configured dashboard fails at startup instead of serving. Previously the combination parsed cleanly and the token was never checked at all (GHSA-rgxj-434m-vxh3), so a dashboard an operator believed was protected was public. Set a token, or set `auth.enabled: false` if the dashboard is meant to be reachable without one.\n\n`enabled` and `auth` now cover the dashboard's MCP endpoint and its tools (`dashboard:graph`, `dashboard:list-tools`, `dashboard:list-resources`), not only the page. With `enabled: false`, or with `NODE_ENV=production` and no `enabled`, the page and the MCP endpoint answer `404` and the tools refuse with `DASHBOARD_DISABLED` on every transport. To keep the dashboard in production, set `enabled: true` together with `auth`.\n\nWith `auth` on, the MCP endpoint needs the token too, in addition to the server's own authentication, which still applies first. An MCP client sends it as `Authorization: Bearer ` or, when `Authorization` carries the server's own token, as `x-frontmcp-dashboard-token: `. `?token=` is accepted for the page only. The page, opened with the token, sets an HttpOnly, `SameSite=Strict` cookie (`frontmcp_dashboard`, `Secure` on https) that its own client uses. `createDirect` and stdio have no way to send the token, so with `auth` on the tools refuse there.\n\n`basePath` moves only the page. The MCP endpoint stays at the dashboard app's route (`/dashboard`, after `http.entryPath`), and the page's client now uses it; it used `/sse` before.\n\nConsequence to plan for: on a server with non-public auth, the page's client carries the dashboard cookie but no server credential, so its graph and SSE stream get `401` from the server's authentication. Run the dashboard on a public/development server, or front it with a proxy that injects a credential, scoped to the dashboard's own routes (`/dashboard`, `/dashboard/sse` and `/dashboard/message`) and holding no grant beyond the dashboard scope. Injecting a server credential across the MCP endpoint instead would let any page on that origin issue arbitrary authenticated JSON-RPC.\n\nOnly the Node server (`bootstrap`, `createHandler`) serves the dashboard's route. `createFetchHandler`, `createDirect`, `connect()` and stdio serve the server's own apps; up to 1.8.2 they served the dashboard's scope instead whenever `DashboardApp` was in `apps`. They still serve it when `DashboardApp` is the only app.\n\nSignature changes: `generateDashboardHtml(options, mcpPath?)` and `createDashboardAuthValidator(auth, surface = 'page')`.\n\nRelated: dashboard options are process-wide, and a second, CONFLICTING auth configuration in the same process now throws rather than silently replacing the first — accepting it would make one server's token valid on another's dashboard. Call `resetDashboardOptions()` between constructions if you build several servers serially.", "codemod": "no" }, { "id": "BC-037", "title": "register_job / register_workflow are no longer registered by default", "package": "@frontmcp/sdk", "category": "change", "severity": "medium", "old": "@FrontMcp({ jobs: { enabled: true } }) // register_job and register_workflow were exposed", "new": "@FrontMcp({ jobs: { enabled: true, allowDynamicRegistration: true } })", "migration": "`register_job` and `register_workflow` take a raw `script` string and register it as a dynamic job, so an MCP client that can reach them can run arbitrary code in the server process. They were added to the tool surface automatically whenever any app declared jobs (GHSA-58v2-gpcc-jmqv). They are now omitted unless the server opts in, and a call that reaches them without the opt-in fails with `DynamicJobRegistrationDisabledError`.\n\nThe opt-in is `jobs.allowDynamicRegistration`. It is in addition to — not instead of — the `create` permission check on the entry, so a server that turns it on still authorizes each registration.\n\nThe other management tools (`list_jobs`, `execute_job`, `get_job_status`, `remove_job`, and their `*_workflow` counterparts) are unaffected.", "codemod": "no" }, { "id": "BC-038", "title": "approval and featureFlag without a plugin that enforces them stop the server", "package": "@frontmcp/sdk", "category": "change", "severity": "medium", "old": "@Tool({ name: 'wipe_disk', approval: true }) // no ApprovalPlugin installed: the tool ran without approval", "new": "@FrontMcp({ apps: [OpsApp], plugins: [ApprovalPlugin.init()] }) // or remove `approval` from the tool", "migration": "A server now refuses to start with `UnenforcedMetadataError`, naming the entries, when a tool, resource, resource template, prompt, skill or agent declares metadata that only a plugin enforces and no plugin that enforces it reaches the entry. That metadata is `approval` (`@frontmcp/plugin-approval`), `featureFlag` (`@frontmcp/plugin-feature-flags`), and any key a plugin declares with `@Plugin({ enforcesMetadata })`. Previously the field did nothing: an `approval: true` tool ran for anyone, and a flagged-off entry was listed and served.\n\nA plugin reaches an entry when it is installed on the server, on the entry's app, or on another app of the same server (the approval and feature-flag gates also cover apps that have no plugin of their own). With `splitByApp`, every app is a server of its own and needs its own plugin. A tool declared inside an `@Agent` is reached only by plugins installed on that agent.\n\n`@Agent({ approval })` and `@Agent({ featureFlag })` now reach the agent's `invoke_` tool, so an installed plugin gates the agent like a tool. They were ignored before.\n\nInstall the plugin that enforces the field, or remove the field. A custom plugin that enforces a metadata key of its own declares it with `enforcesMetadata` on the plugin class whose hooks enforce it.", "codemod": "no" }, { "id": "BC-039", "title": "createFetchHandler() rejects a misconfigured server when it's called", "package": "@frontmcp/sdk", "category": "change", "severity": "low", "old": "const handler = await FrontMcpInstance.createFetchHandler(config); // misconfigured: the first request threw", "new": "const handler = await FrontMcpInstance.createFetchHandler(config); // misconfigured: rejects here, like createDirect()", "migration": "On Node and Bun, `FrontMcpInstance.createFetchHandler()` now builds the server when it's called, so a misconfigured server (for example `approval` without its plugin, `authorities` without the `authorities` option, or a missing `JWT_SECRET` in production) rejects there with the same error `createDirect()` throws. Previously the handler was returned and its first request threw.\n\nOn edge isolates (Cloudflare Workers, Vercel Edge, Deno), the server is still built on the first request, because module evaluation there forbids timers, randomness and I/O. What the config settles on its own is checked when the handler is created (`assertStaticStartupConfig()`, which `createEdgeMcp()` also runs), and a build that fails later answers every request with a structured `500 server_misconfigured` and logs the error.\n\nLet the awaited `createFetchHandler()` fail your startup (or catch it) instead of expecting the first request to report configuration errors.", "codemod": "no" }, { "id": "BC-040", "title": "availableWhen.surface holds for agents, jobs and HTTP triggers", "package": "@frontmcp/sdk", "category": "change", "severity": "medium", "old": "@Tool({ name: 'lookup', availableWhen: { surface: ['mcp'] } }) // an agent's model could still call it", "new": "@Tool({ name: 'lookup', availableWhen: { surface: ['mcp', 'agent'] } }) // reachable by MCP clients and agents", "migration": "`availableWhen.surface` now applies to every caller the docs list, not only MCP clients. The model an agent runs, and `this.callTool()` in an agent's own code, call on the `'agent'` surface; job and workflow steps on `'job'`; webhook handlers on `'http-trigger'`. A tool whose `surface` leaves one of them out is no longer offered to, or run for, that caller. A tool's own `this.callTool()` stays unrestricted. MCP Apps' `ui/callServerTool` counts as `'mcp'`, and a task keeps the surface of the call that created it. `getCallSurface()` now also works inside prompts.\n\nList every surface that should reach an entry, for example `surface: ['mcp', 'agent']`.", "codemod": "no" }, { "id": "BC-041", "title": "An authorities rule that names an unknown profile stops the server", "package": "@frontmcp/sdk", "category": "change", "severity": "low", "old": "@Tool({ name: 'purge', authorities: 'admn' }) // started, then refused everyone", "new": "@Tool({ name: 'purge', authorities: 'admin' }) // an unknown name now stops the server at startup", "migration": "An `authorities` rule that names a profile not defined in `@FrontMcp({ authorities: { profiles } })`, alone or in a list, now stops the server at startup with `AuthConfigurationError: Invalid authorities rule: … names an unknown profile \"admn\"`, on every entry kind the startup check covers (tools, resources, resource templates, prompts, agents, tools inside agents and skills). Previously the server started and refused every caller at call time.\n\nFix the name, or define the profile.", "codemod": "no" }, { "id": "BC-042", "title": "OAuth: tokens name the server's real address; public-mode and allowlist fixes", "package": "@frontmcp/sdk", "category": "change", "severity": "low", "old": "// createFetchHandler: tokens carried aud \"http://undefined\" and the boot-time iss", "new": "// createFetchHandler: aud and iss from the request URL, unless issuer/local.issuer or FRONTMCP_PUBLIC_URL is set", "migration": "- Through `createFetchHandler()`, the resource URL and a token's `iss` come from the request's URL; they were `http://undefined` and the boot-time issuer. A configured `issuer` or `local.issuer`, else `FRONTMCP_PUBLIC_URL`, takes precedence on every entry point. A deployment that sets `FRONTMCP_PUBLIC_URL` without `local.issuer` now issues tokens with that `iss`, so tokens issued before the upgrade are refused once and clients refresh or sign in again.\n- An explicit `auth: { mode: 'public' }` answers `/oauth/authorize` and `/oauth/token` like a server without `auth` (an anonymous code to loopback redirect URIs only) instead of 500. Static mode answers 400.\n- A `dcr.allowedClientIds` refusal of a registered client using its own `redirect_uri` redirects there with `error=unauthorized_client`; it was a 400 page.\n- `scopes_supported` in both discovery documents lists the literal `allowedScopes` entries. `*` globs are granted but not advertised.", "codemod": "no" }, { "id": "BC-043", "title": "OpenAPI adapter: a secured call needs a credential for its scheme on the request as sent", "package": "@frontmcp/adapters", "category": "change", "severity": "medium", "old": "OpenapiAdapter.init({ ..., passthroughCallerToken: true }) // an API-key operation went out with no key", "new": "OpenapiAdapter.init({ ..., authProviderMapper: { ApiKeyAuth: (ctx) => keyFor(ctx) } }) // refused without a key", "migration": "A secured operation is refused before any request, with `Authentication required for tool '…'`, unless the request as sent carries a credential for one of its schemes. Credentials can come from `staticAuth`, `authProviderMapper`, `securityResolver`, a header set by `additionalHeaders` or `headersMapper` (an API key in its named header, `Authorization` for bearer and OAuth2), or the tool input with `securitySchemesInInput` or `includeSecurityInInput`.\n\n`passthroughCallerToken` fills only HTTP bearer schemes: an API-key or OAuth2 operation it can't satisfy is refused. Before, it was sent with no credential. When the server and the tool input both give a credential for a scheme, the server's wins. `securitySchemesInInput` is rated HIGH at startup, like `includeSecurityInInput`. `inputTransforms` and `headersMapper` also run for calls that are then refused.\n\nSupply each scheme's credential from a server-side option.", "codemod": "no" }, { "id": "BC-044", "title": "CodeCall reports syntax_error and tool_error", "package": "@frontmcp/plugin-codecall", "category": "change", "severity": "low", "old": "if (result.status === 'runtime_error') { /* parse errors, tool failures and script errors */ }", "new": "switch (result.status) { case 'syntax_error': case 'tool_error': case 'runtime_error': /* ... */ }", "migration": "CodeCall runs scripts with the tool namespaces and `throwOnError` of `@enclave-vm/core` 2.15.3. A parse error is now `syntax_error`, with the line and column in the script. A failing tool is `tool_error`, with the tool's error code (a time-out is `TIMEOUT`) and without the tool's arguments. The script's own errors stay `runtime_error`. Before, all three were `runtime_error`, and a tool time-out ended the script with status `timeout`.\n\nA namespace call with `{ throwOnError: false }` returns the same `{ success, error }` shape as `callTool`. Namespaces whose tool names start with `_` aren't offered; call those tools with `callTool`.\n\nCheck `status` for the new kinds.", "codemod": "no" }, { "id": "BC-045", "title": "A request is in a session only if it presented one", "package": "@frontmcp/sdk", "category": "change", "severity": "medium", "old": "// 2026-07-28: every request got a new session id, so session-scoped memory lasted one request", "new": "// 2026-07-28: no session; session-scoped memory belongs to the signed-in caller (or refuses anonymous ones)", "migration": "A session counts as verified only when the request presented it (`mcp-session-id`, or a legacy SSE `sessionId`) and the server accepted it. Under MCP 2026-07-28, no request is in a session, even one that sends back an id the server issued. The id the server makes up for a request that has none is no longer a session.\n\nState kept per session therefore falls back to the caller's identity: Remember `session` and `tool` memory, feature-flag targeting, approval session records, `CONTEXT` providers, elicitation owners, the secure store's `session` scope, and session-scoped auth-provider credentials. An unauthenticated caller without a session gets `RememberIdentityError` from Remember's session-scoped memory, and `SessionIdentityRequiredError` from the secure store's `session` scope. Legacy SSE sessions now count as verified, so approvals and rate-limit partitions apply per SSE session. A static-key caller is no longer anonymous: its results are cached `private`, and it can own 2026-07-28 tasks. `authInfoFromAuthorization(authorization, presentedSessionId?)` takes the presented id; without it, `extra.sessionId` isn't set.\n\nFor state that must outlive a request under 2026-07-28, sign callers in or use `user` scope.", "codemod": "no" }, { "id": "BC-046", "title": "Durable Object sessions serve only the caller that opened them", "package": "@frontmcp/sdk", "category": "change", "severity": "low", "old": "// any caller presenting a Durable Object session's Mcp-Session-Id reached its persistent transport", "new": "// only the caller that opened the session; anyone else gets 404 Session not found", "migration": "A Durable Object's stateful MCP session (`createEdgeMcp({ sessions })`) serves only the caller that opened it. Its `Mcp-Session-Id` addresses the Durable Object but is not an id `session:verify` can check against the caller's token, so the `http:request` flow's new `checkPersistentSessionOwner` stage binds the session to the caller of its first request, before every protocol handler (MCP 2026-07-28 included): its verified issuer and subject (a token refresh keeps them), else its token (an anonymous grant). The owner is kept in the Durable Object's storage, so an instance rebuilt after eviction keeps it. Any other caller that presents the id gets `404` with JSON-RPC error `-32001 Session not found` on `POST`, `GET` and `DELETE`, and the owner's session is untouched. On a public server, an anonymous caller without a token has no identity to bind, so the unguessable session id remains the only credential. The owner can now end its session with `DELETE`; before, every `DELETE` of a Durable Object session answered 404.\n\nA client that shares one session between users, or signs in as a different user mid-session, must `initialize` a new session.", "codemod": "no" }, { "id": "BC-047", "title": "OAuth: one issuer for every entry point, and on every authorization response", "package": "@frontmcp/sdk", "category": "change", "severity": "medium", "old": "// Node server: iss = http://localhost:3001 whatever the request; FRONTMCP_PUBLIC_HOST beat FRONTMCP_PUBLIC_URL; error redirects had no iss", "new": "// one order everywhere: issuer/local.issuer > FRONTMCP_PUBLIC_URL > FRONTMCP_PUBLIC_HOST > request origin; iss on every authorization response", "migration": "Discovery (`/.well-known/oauth-authorization-server` `issuer`, protected resource metadata `authorization_servers`), the RFC 9207 `iss` on every authorization response, and token `iss` all use one order, on FrontMCP's Node server and under `createFetchHandler()` alike: `issuer` / `local.issuer`, then `FRONTMCP_PUBLIC_URL`, then `FRONTMCP_PUBLIC_HOST` (the boot-time issuer), then the request's origin. `FRONTMCP_PUBLIC_URL` now wins over `FRONTMCP_PUBLIC_HOST`; on the Node server with nothing pinned, the issuer follows the request instead of `http://localhost:`; discovery names a configured `local.issuer`; and `expectedAudience` no longer pins the boot-time issuer (tokens name the address they were issued at, and any listed address's issuer, or the 1.8.4 boot-time one, is accepted). Error redirects now carry `iss` too, and the authorization server metadata advertises `authorization_response_iss_parameter_supported: true`.\n\nTokens minted by 1.8.4 on a Node server reached at another host than `localhost:` carry the boot-time `iss` and are refused unless `expectedAudience` is set; clients re-authorize or refresh. In production, pin `FRONTMCP_PUBLIC_URL` or set `local.issuer`.", "codemod": "no" }, { "id": "BC-048", "title": "Protected resource metadata lists the scopes each auth mode grants", "package": "@frontmcp/sdk", "category": "change", "severity": "low", "old": "// scopes_supported: ['openid', 'profile', 'email', ...] in every mode", "new": "// scopes_supported: what the mode grants (anonymousScopes / scopes / requiredScopes + scopes / allowedScopes)", "migration": "`scopes_supported` in the protected resource metadata no longer lists `openid`, `profile` and `email` in public, static and transparent mode. Public mode (or no `auth`) lists `anonymousScopes`, static mode `scopes`, transparent mode `requiredScopes` then `scopes`, each plus the `authProviders` scopes; local and remote mode list `allowedScopes` as before. An empty list leaves the field out. `ScopeEntry.getAllSupportedScopes()` now returns only the `authProviders` scopes.", "codemod": "no" }, { "id": "BC-049", "title": "MCP 2026-07-28 anonymous and static-key callers get no session", "package": "@frontmcp/sdk", "category": "change", "severity": "low", "old": "// production, no MCP_SESSION_SECRET: anonymous / static-key 2026-07-28 call -> 500 SESSION_SECRET_REQUIRED", "new": "// served; no session is minted for 2026-07-28 requests or skills HTTP requests", "migration": "`session:verify` no longer mints an encrypted session for an MCP 2026-07-28 request, or for a skills HTTP request (`/skills`, `/llm.txt`, `/llm_full.txt` with `auth: 'inherit'`): it identifies the caller for that request only. `MCP_SESSION_SECRET` is therefore needed only for session clients (Durable Object sessions, protocol before 2026-07-28); before, an anonymous or static-key 2026-07-28 call, or a static-mode skills HTTP request, answered `500 SESSION_SECRET_REQUIRED` in production without it. Under 2026-07-28, `this.authInfo.sessionId` is the same per-request id as `this.context.sessionId`, and `verifiedSessionId` stays `undefined`; key state that must outlive a request on the caller, not on the session id.", "codemod": "no" }, { "id": "BC-050", "title": "`invoke_` runs the `agents:call-agent` flow", "package": "@frontmcp/sdk", "category": "change", "severity": "low", "old": "// invoke_ called execute() directly: AgentCallHook hooks never ran, this.context threw in execute()", "new": "// invoke_ runs tools:call-tool, then agents:call-agent (hooks run; gates applied once)", "migration": "Calling `invoke_` now runs the `agents:call-agent` flow after `tools:call-tool`, so `AgentCallHook` hooks and an agent class's own hooks on that flow run; before, the flow never ran. The agent's authorities, rate limit, concurrency and timeout are still applied once, by the tool flow. `this.context` now works inside an agent's own `execute()`.", "codemod": "no" }, { "id": "BC-051", "title": "Channel sources: webhooks are served, completions are delivered", "package": "@frontmcp/sdk", "category": "change", "severity": "low", "old": "// webhook, agent-completion and job-completion channel sources never fired", "new": "// webhook: POST route (ipFilter-guarded); completions: delivered to the originating session", "migration": "Channel `webhook` sources are served as `POST` routes on the HTTP server, guarded like `http.routes` (`throttle.ipFilter`). A webhook path on a FrontMCP path, or one shared by two channels, now fails startup. `createDirect`, stdio and `createFetchHandler` serve no webhook route. `agent-completion` and `job-completion` sources now deliver their events, only to the session that ran the agent or job; a run with no session is delivered to no one. Before, none of the three sources did anything.", "codemod": "no" }, { "id": "BC-052", "title": "Elicitation on a server-defaulted 2026-07-28 call without the capability", "package": "@frontmcp/sdk", "category": "change", "severity": "low", "old": "// header-less 2025-03-26 client via createFetchHandler: elicit() -> -32021", "new": "// ElicitationNotSupportedError, as for a legacy-protocol call", "migration": "An unversioned call that is served as MCP 2026-07-28 only by default (`transport.defaultProtocolVersion`, the Worker default), from a client without the elicitation capability, now gets `ElicitationNotSupportedError` from `elicit()`, as a legacy-protocol call does, instead of `-32021` (missing elicitation capability). A client that declares 2026-07-28 itself still gets `-32021`.", "codemod": "no" }, { "id": "BC-053", "title": "Edge isolates answer a failed server build instead of throwing", "package": "@frontmcp/sdk", "category": "change", "severity": "medium", "old": "// a build failure other than a startup check or missing secret: fetch() rejected, and every request rebuilt", "new": "// 500 server_misconfigured or 503 server_unavailable (Retry-After); rebuilds back off from 1 s to 60 s", "migration": "On an edge isolate (`createEdgeMcp()`, `createFetchHandler()` / `@FrontMcp`, session Durable Objects), a server that fails to build no longer throws out of `fetch`. A configuration fault, now including a config the schema refuses (`CONFIG_INVALID`), answers `500 {\"error\":\"server_misconfigured\",\"code\":...}`; anything else answers `503 {\"error\":\"server_unavailable\",\"code\":\"SERVER_START_FAILED\"}` with `Retry-After`, without echoing the error. A failed build is kept, and refuses requests, for 1 s after the first failure, doubling up to 60 s, instead of being rebuilt by every request. Code that caught the rejected `fetch` promise should read the response status instead.", "codemod": "no" }, { "id": "BC-054", "title": "Browser builds run a workflow's ready steps one at a time", "package": "@frontmcp/sdk", "category": "change", "severity": "low", "old": "// browser, no AsyncContext: parallel steps overlapped, failed and were retried", "new": "// browser, no AsyncContext: ready steps run one at a time", "migration": "In a browser build without `AsyncContext`, a workflow runs its ready steps one at a time whatever its `maxConcurrency`. Before, steps started together overlapped, failed the request-context overlap check and were retried, and a workflow could end `failed`. Node and Workers still run steps concurrently.", "codemod": "no" }, { "id": "BC-055", "title": "skills/load reports tools the caller's surface hides as missing", "package": "@frontmcp/sdk", "category": "change", "severity": "low", "old": "// skills/load: a surface-hidden tool was listed as available, with its input schema", "new": "// listed in missingTools, available: false, no schema", "migration": "A skill's tool that `availableWhen.surface` doesn't offer the caller is reported in `missingTools`, with `available: false` and no input schema, from `skills/load`, the `skills:load` flow, `GET /skills/{id}` and `/llm_full.txt`; `isComplete` is then false. Before, it was reported as available, with its schema.", "codemod": "no" }, { "id": "BC-056", "title": "OpenAPI adapter: includeSecurityInInput as a list sends the listed credentials", "package": "@frontmcp/adapters", "category": "change", "severity": "low", "old": "// includeSecurityInInput: ['ApiKey'] -> argument in the schema, value never sent", "new": "// the listed schemes' input values are sent; the others need a credential source", "migration": "`generateOptions.includeSecurityInInput` as a list of scheme names now works like `securitySchemesInInput`: the listed schemes' values from the tool input are sent (before, they were added to the input schema and dropped). The schemes the list leaves out now need a credential source at startup (`authProviderMapper`, `staticAuth`, `additionalHeaders` / `headersMapper`, or `passthroughCallerToken` for bearer); before, a list skipped that check entirely. The startup warning names the listed schemes. Give the other schemes a credential source, or use `includeSecurityInInput: true`.", "codemod": "no" }, { "id": "BC-057", "title": "CodeCall reports the script's own lines, and tool_error has no toolInput", "package": "@frontmcp/plugin-codecall", "category": "change", "severity": "low", "old": "// illegal_access at line 6 for a script's line 2; tool_error schema declared toolInput", "new": "// illegal_access at the script's own line; no toolInput", "migration": "`illegal_access` messages name the script's own lines; before, they named lines of the enclave's transformed code (2 or more past the script's line). A line that is none of the script's is omitted. `tool_error` results never include `toolInput`; the schema field is optional and deprecated.", "codemod": "no" } ]