[Improvement] Reconsider --dynamic-toolsets and --optimize-response now that the transport is stateless #179

Follow-up to #173 (MCP spec 2026-07-28 migration) and #174. Two flags now look like they cost more than they return. Both are documented public options, so this issue is for deciding what to do rather than a patch — and either half can be split out.

All figures below were measured on main after #178, 62 tools enabled, Node 24.

1. --dynamic-toolsets is unsound on the HTTP transport

MCP 2026-07-28 removed protocol sessions, so there is no per-client scope left to hold toolset state. #173 responded by sharing one ToolsetGroup across every per-request server, which is the only thing that makes enable_toolset mean anything — but it also makes the state process-wide.

src/createBacklogMcpServer.ts says as much:

Sharing it makes toolset state process-wide, which is the only scope left now that the protocol has no sessions.

Verified against a running server (--transport http --dynamic-toolsets --enable-toolsets space):

tools/list                          -> 10 tools
tools/call enable_toolset {issue}   -> "Toolset issue enabled"
tools/list                          -> 37 tools

The 10 → 37 change is visible to every client of that process, not just the caller. On a single-user desktop setup that is the intended behaviour. On a shared or multi-tenant HTTP deployment one client silently rewrites what every other client sees, and there is no way to undo it (there is no disable_toolset).

The related tools/list cache hint is correctly withheld in this mode, so at least clients are not caching a list that can grow.

Options

1. Reject the combination at startup — --dynamic-toolsets with --transport http exits with an explanatory error. Simplest, and honest about what the protocol can express.
2. Warn and keep going — cheaper for existing users, but leaves the surprise in place.
3. stdio only — same as (1) but framed as a documented restriction.
4. Per-request scope — derive the enabled set from a request header or the tool call itself. Real work, and no spec support for it.

I lean towards (1): the feature's contract ("enabling persists for me") cannot be honoured for a single client on this transport, so failing fast beats a silent shared mutation.

2. --optimize-response pays a permanent prompt cost to save a variable one

The flag exists to shrink tool responses by letting the client select fields. It does that by adding a fields parameter whose description embeds a generated type definition — on every tool, in every tools/list.

Of that, 31.4 KB (44% of the whole payload) is fields descriptions. It is a fixed, up-front cost paid on every session, against a saving that only materialises when the agent actually uses field selection on a large response.

Three things make the trade worse

fields is a required parameter. extendSchema builds it as z.string().describe(desc) with no .optional(), so enabling the flag makes every call fail unless fields is supplied:

tools/call get_space {}
-> Invalid arguments for tool get_space: fields: Invalid input: expected string, received undefined

This is long-standing, not a regression — I built v0.14.0 and reproduced it identically. Whether it is intended is worth settling either way.

The generated type definition is very coarse. mapZodTypeToGraphQLType only distinguishes String / Int / Boolean / JSON plus nullability. ZodArray has no branch at all and falls through to String, so arrays are described incorrectly:

type Document {
  id: String!
  attachments: String      <- z.array(DocumentFileInfoSchema)
  tags: String             <- z.array(DocumentTagSchema)
  createdUser: JSON        <- nested objects collapse to JSON
}

It is the only consumer of a large hand-written surface. outputSchema is never passed to the MCP SDK (registerOnce sends inputSchema only) and never validates a response. Its only runtime use is generating these descriptions. Dropping the flag would make redundant:

• src/types/zod/backlogOutputDefinition.ts — 549 lines, 56 schemas, hand-maintained in parallel with the types backlog-js already ships
• src/utils/generateFieldsDescription.ts and src/handlers/transformers/wrapWithFieldPicking.ts
• the graphql dependency (~1 MB), used only for parse / SelectionSetNode in one file

The duplication is not theoretical: #178 deleted a DocumentSchema that matched neither backlog-js's Document.Document nor the API — wrong id type, name/content instead of title/plain/json — and nothing noticed, because nothing validates against it.

Options

1. Keep it, make fields optional. Smallest change; leaves the 31.4 KB in place.
2. Keep it, shrink the description. Emit field names only and drop the type definition block. Most of the 31.4 KB is the type def, which is coarse enough to be of limited use.
3. Deprecate and remove it. Recovers the payload, 549 lines, and a 1 MB dependency. Breaking, so it needs a version decision.
4. Compromise: default off (already is) plus (2), and revisit removal later.

Not proposed: publishing outputSchema over MCP

Worth recording since it comes up naturally — the spec has supported tool output schemas since 2025-06-18, and these zod schemas already exist. Converted to JSON Schema they total 220.2 KB across 62 tools (versus 33.0 KB for all input schemas). Publishing them would take tools/list past 260 KB. Not viable at this size.

Method

Both payload figures come from driving the built server over stdio with a tools/list call and measuring JSON.stringify(result.tools).length, with and without the flag. The dynamic-toolsets behaviour was reproduced against the HTTP transport with real requests. Happy to attach the scripts if useful.