dsh-mcp-client: support per-server tool filtering at registration (allowedTools)

[scs001]

Motivation

The MCP client bridge registers every tool a server's tools/list reports
(mcp__<server>__<rawName>). Large servers make this expensive: our platform's
registry hosts servers with 161, 71 and 52 tools, and a persona that needs
three of them still pays the full tool-schema surface in context tokens — on
128k-class windows this is a material fraction — plus measurably worse
tool-choice quality on weaker models.

Filtering is fundamentally a client-side concern: the context cost happens
at the client, and servers the client reaches directly (user-deployed, not
behind a filtering gateway) can be narrowed nowhere else.

Downstream platforms can approximate this today with ctx.tools.restrict()
per agent scope, but that path has real friction: restrict() throws on
unknown names (MCP tool sets are dynamic — drift between composition and
sync breaks the composition), it must be applied per-agent-scope after tool
sync, and the filtered tools still exist in the registry (guard-only
enforcement degrades to "visible but not callable").

Proposal

Add an optional config field to both StdioConfig and StreamableHttpConfig:

/** Tool leaf names to register; omitted tools never enter the tool
 *  registry. Absent/undefined = register every tool (today's behavior). */
allowedTools?: string[];

Semantics we'd propose (and would be happy to contribute):

1. Filter at tool synchronization, not after registration: names not in
   the list are never registered — no schema in the model-facing roster, no
   execution path, nothing for tool_search-style introspection to see.
2. Leaf names, not public names: serverName is already the entry's own
   config; the list matches the raw name from tools/list.
3. Re-applied on reconnect/resync: a server adding tools after connect
   stays filtered; a server removing an allowed tool behaves exactly as it
   does today for any tool (the registration disappears).
4. No failure on list drift: unknown names in allowedTools are inert
   (the tool simply never appears), matching how a static list must behave
   against a dynamic server surface. A failOnStartupError: true entry whose
   server is unreachable fails exactly as today — the field is orthogonal.
5. Empty array = register nothing (an explicit "no tools" mount is useful:
   health-checking a server without exposing its surface).

Non-goals

• Pattern/wildcard matching (exact names first; a platform needing patterns
  can expand them against its own catalog snapshot).
• Deny-lists (allow-only covers the declarative "this integration needs
  exactly these tools" case; per-user trimming is a UI concern on top).

Alternatives considered

• ctx.tools.restrict() per scope: works today, but unknown-name throws +
  per-scope application + post-registration timing make it fragile for
  dynamic MCP surfaces (details above).
• A filtering local proxy per server: semantically clean but costs a process
  per filtered server and protocol-forwarding maintenance.
• Gateway-side filtering: only covers servers behind a filtering gateway;
  user-deployed servers are unreachable.

---

---

Filed from a downstream platform built on @deepseek-ai/dsh (MIT) — happy to
contribute the implementation if the semantics above match your intent.

[argszero]

Checked against master; three source facts first, then a measured seam that reaches your semantics 1-3 today without a core change.

1. Registration is unconditional today. packages/mcp/mcp-client/src/tools.ts:143-150 registers every entry of tools/list, with no filter point. registrationFailure (:130-160) only decides whether a namespace conflict rolls the whole generation back (contain) or propagates (throw).

2. The public name shape matters for your field design. publicToolName() (:81-87) emits mcp__<serverName>__<rawName> verbatim while the raw name already satisfies the DeepSeek function-name contract (<=64 chars, [A-Za-z0-9_-]); otherwise invalid characters become _ and a 12-hex SHA-256 suffix is appended so distinct MCP identities cannot collapse. In that lossy case the raw leaf is not recoverable from the registered name — which is an argument for matching the raw leaf if the field lands upstream.

3. ctx.tools.restrict() is further from your semantics than "friction". packages/core/tools/src/index.ts:1097-1122: it requires a scoped context (:1100 throws for a global one), throws on any unknown name (:1115-1118 — exactly the list drift you describe), and it is a mask over global tools, so the entry stays registered and visible to registry introspection. Your semantics 1 ("never registered") is unreachable that way.

A plugin reaches semantics 1-3 today — measured, not inferred. The registration is ctx.tools.register(definition) on a Cordis service, and that service's instance method is shadowable: Reflect.get(ctx.get('tools'), Symbol.for('cordis.original')) is the raw ToolRuntime, and after inst.register = wrapper a registration made through ctx.tools from another view goes through the wrapper. Measured on @deepseek-ai/dsh-tools@0.2.0-rc.2 + @deepseek-ai/cordis@4.0.4: three registrations (mcp__alpha__lookup, mcp__alpha__search, bash) all reached the shadow. So a plugin mounted before the MCP entries can drop mcp__<server>__<leaf> names at registration time — no schema in the roster, no execution path, nothing for tool_search-style introspection — and it is re-applied on every re-sync, because syncTools re-registers per generation and the disposer map then holds only live registrations.

I am publishing that as @argszero/dsh-mcp-tool-filter: a per-server allowlist keyed by the public leaf, unlisted servers passing through untouched, empty list registering nothing, modes filter / observe (counts, changes nothing) / off, and a report naming both the dropped tools and any configured leaf that never matched anything (so a typo is a visible line instead of a silently missing tool). Unknown configured names are inert, as you propose.

Two honest limits, both of which the plugin states: it sees only the public name (the raw leaf is a closure value — createMcpToolDefinition :229, :235, :263 — never a field on the definition), and it narrows what the client registers, not what the server lists; the fetch still happens. If you add the field upstream, matching the raw leaf is strictly more accurate, and your semantics 4 and 5 fall out naturally.

[argszero]

A published plugin now covers this gap: @argszero/dsh-mcp-tool-filter@0.1.0 (source: https://github.com/argszero/dsh-mcp-tool-filter, MIT).

The seam it uses is the one your report's first semantic asks for — the tool never enters the registry. mcp-client calls ctx.tools.register(definition) by name lookup at call time, so shadowing register on the tools service instance (Reflect.get(ctx.get('tools'), Symbol.for('cordis.original'))) is seen by that call, while a write to the view would only be seen by the writer. It is the same instance-shadow that works for subprocess. restrict() is not the answer here three ways over: it needs a scoped context (global throws by design), it throws on names a changed tools/list no longer produces, and it only masks a definition that stays registered and introspectable.

# profile: list this row BEFORE the mcp-client rows
- id: mcp-tool-filter
  name: '@argszero/dsh-mcp-tool-filter'
  config:
    servers:
      github: [list_issues, get_issue]   # absent key = that server is untouched
      playwright: []                     # empty list = register nothing from it

Mount order matters and is reported rather than assumed: a loader mounts entries in profile order and mcp-client registers its first generation while it starts, so a filter mounted afterwards has missed it — a plugin cannot unregister another plugin's tools. The mount warns, and coverage.preExisting names what it was too late for.

What it deliberately does: allowlist by public leaf name (mcp__<server>__<leaf>), because that is the only spelling the registry has — the raw name lives in a closure on the definition and is never a field, so a normalized/hashed name is matched in its public form. Unlisted servers pass through untouched. mode: observe counts what filter would keep out without removing anything. The snapshot reports configured / covered / idle server keys, unusedLeaves, unmatchable keys with the reason, and preExisting.

Verification behind the claim:

• 70 tests, including an integration suite that mounts the real @deepseek-ai/dsh-tools registry and asks the registry's own projection (schemas()) what it holds — never the plugin's counters.
• Defect injection: 23 mutations across all four modules, every one caught by the suite (0 silent).
• Cross-line probe: the suite runs green on 0.1.7-rc.2, 0.2.0-rc.2 and 0.2.1-alpha.2, each with its own mcp-client — publicToolName() re-derived from that line's shipped bundle and compared 45/45 with the replica the suite generates names from.
• The published tarball was installed by name and byte-compared with the local build (12/12 files identical), then the suite was re-run against the published lib/.

This is a mitigation, not the fix you proposed. The right change is still a per-server allowedTools on the mcp-client entry itself — the same configuration applied one layer earlier, where rawName is still in hand and nothing has to be inferred from a public name. The plugin exists because the seam is reachable today and needs no upstream change; it can be deleted the day the entry grows that field.

[scs001]

Platform maintainer here (the OP context: a multi-tenant agent platform whose registry hosts the 161/71/52-tool servers) — we just shipped the same instance-shadow seam inside our platform bridge, and can add two measured data points to @argszero's report.

1. The seam holds on the older 0.1.1-rc.2 line too, and across both generations we run. Our production matrix freezes @deepseek-ai/dsh-tools@0.1.1-rc.2 + @deepseek-ai/cordis@4.0.4 (and one dev tree still resolves 0.0.1-rc.1 side-by-side). We pinned a sentinel test against the real runtime — 14 assertions — covering: registrations from another view dispatch through the own-prop wrapper; a dropped leaf never appears in schemas(); non-MCP names and unlisted servers pass through untouched; and, the one we were most worried about, receiver/scope attribution survives the wrapper — cordis invokes the forwarded method with the calling view as receiver, so protoRegister.call(this, …) keeps agent-scoped registrations in their scope and nothing leaks to the global layer. Cleanup (delete inst.register) restores the prototype method, which makes the wrapper safe under our plugin-fiber lifecycle (installed via ctx.effect, lifted on dispose/HMR).

2. The raw-leaf point is real and we hit the same edge. Our bridge (like the plugin) matches the public mcp__<server>__<leaf> spelling, and a leaf whose raw name violates the function-name contract comes back with the 12-hex suffix — an allowlist authored against the registry's tools/list (raw names) then misses it. Today that mismatch fails safe for us (the publish gate compares the manifest allowlist against the tool_list snapshot, so a lossy name is caught at publish time, and at runtime the guard denies rather than admits). But we agree completely: the field belongs on the entry, where rawName is still in hand — that is strictly more accurate than anything recoverable from the public name, and semantics 4/5 follow for free.

For anyone landing on this thread with the same need: the plugin works as advertised on our line, and the seam is also small enough (~30 lines) to embed in a host bridge if you would rather keep it inside your own plugin lifecycle. Our proposal stands as the long-term fix — the plugin (and our bridge wrapper) can be deleted the day the entry grows allowedTools.