Skip to content

Add request-aware visibility to McpServer - #9661

Merged
tim-smart merged 11 commits into
v4/next-minorfrom
agent/nelson/f3776b531b6f
Oct 22, 2026
Merged

tim-smart merged 11 commits into
v4/next-minorfrom
agent/nelson/f3776b531b6f

Conversation

@tim-smart

@tim-smart tim-smart commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Adds McpServer.visibility, which hides tools, resources and prompts per request based on services that MCP middleware provides, for example a CurrentUser. EnabledWhen stays as it is; it can only see client capabilities.

const AdminOnly = McpServer.visibility(() => Effect.map(CurrentUser, (user) => user.isAdmin))

McpServer.toolkit(AdminTools).pipe(
  Layer.provide(AdminOnly.combine(Auth).layer),
  Layer.provide(AdminTools.toLayer({ ... }))
)

Behaviour

  • visibility returns an ordinary Middleware, so .layer, .layerGlobal, .combine and { global: true } work as they do for middleware. The check receives MiddlewareOptions and returns Effect<boolean, E extends McpErrorBase, R>. R must come from middleware combined outside it, or from the transport; otherwise .layer is MissingRequestDependencies.
  • On tools/list, resources/list, resources/templates/list and prompts/list, only the middleware outside the innermost visibility runs, once for each registration. So audit.combine(adminOnly) keeps audit off list requests, and a stack with no visibility never runs on list. Expensive lookups such as resolving the user from a token are expected to be cached by the middleware.
  • MiddlewareOptions keeps its flat shape. MiddlewareMethod gains the four list methods; on list requests target is the registration's name, URI or URI template, and payload is undefined. None of this has shipped yet.
  • A failure in that middleware or in a check fails the whole list request with the usual JSON-RPC error. It never hides an entry.
  • On calls, reads, gets and completions, the check runs in the registration's normal middleware pass, before the handler. A hidden registration returns the existing not-found error (Tool 'x' not found, Resource 'x' not found, Prompt 'x' not found, Unknown completion reference or argument). This also covers input_required continuation rounds, which return not-found rather than InvalidToolContinuation.
  • A hidden static resource returns ResourceNotFound. It doesn't fall through to a template that also matches its URI.
  • Middleware provided both locally and globally now runs once. Before this change, makeInvoke concatenated the two stacks without deduping.
  • The 2026-07-28 tools/call header mirroring looks up the descriptor with the sync EnabledWhen check only. A hidden tool with an x-mcp-header parameter can therefore answer a mismatched header with 400 before not-found, as agreed in the design.
  • list_changed notifications are unchanged. Clients see visibility changes on their next list request.

Implementation

  • The core (mcpCore.ts) list methods take the McpInvocation and can fail with RequestRejected. Each registration has an optional visible effect, and the core filters the isVisible candidates with it, in registration order.
  • A visibility compiles to a gate middleware function, marked in a WeakSet. makeInvoke returns invoke and visible. visible runs the middleware from the innermost gate outwards around Effect.void, through the same path as invoke, and maps Hidden to false.
  • Hidden calls fail with an internal Hidden error, which makeInvoke recognises by instanceof before it checks the handler-failure annotation and replaces with the method's not-found error. Hidden has an MCP error shape, because middleware outside the gate sees it.
  • Legacy adapters share a small listForClient helper.
  • MCP.md has a new "Per-request visibility" section.

Testing

Each behaviour change landed as tests first, in separate commits, and the implementations didn't change their assertions.

  • pnpm vitest run packages/effect/test/ai: 1610 passed.
  • pnpm tstyche --target '>=5.9' packages/effect/typetest/ai/: 184 passed on both targets.
  • pnpm lint, pnpm jsdocs --check and pnpm circular pass. pnpm ai-docgen produces no changes.
  • tsc is clean on packages/effect/src plus the MCP tests. I didn't run the repo-wide pnpm check; CI will.

Typed tool-selector options are out of scope.

Closes EFF-2132

@changeset-bot

changeset-bot Bot commented Oct 21, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: fec3794

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 33 packages
Name Type
effect Minor
@effect/opentelemetry Minor
@effect/vitest Minor
@effect/ai-anthropic Minor
@effect/ai-cloudflare Minor
@effect/ai-openai-compat Minor
@effect/ai-openai Minor
@effect/ai-openrouter Minor
@effect/ai-typesafe Minor
@effect/atom-react Minor
@effect/atom-solid Minor
@effect/atom-vue Minor
@effect/platform-browser Minor
@effect/platform-bun Minor
@effect/platform-deno Minor
@effect/platform-node-shared Minor
@effect/platform-node Minor
@effect/sql-clickhouse Minor
@effect/sql-d1 Minor
@effect/sql-libsql Minor
@effect/sql-mssql Minor
@effect/sql-mysql2 Minor
@effect/sql-pg Minor
@effect/sql-pglite Minor
@effect/sql-sqlite-bun Minor
@effect/sql-sqlite-do Minor
@effect/sql-sqlite-node Minor
@effect/sql-sqlite-react-native Minor
@effect/sql-sqlite-wasm Minor
@effect/docgen Minor
@effect/doctest Minor
@effect/graphql-generator Minor
@effect/openapi-generator Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Bundle Size Analysis

Generated from PR build output; treat the content below as untrusted.

File Name Current Size Previous Size Difference
arbitrary-combinators.ts 39.18 KB 39.18 KB 0.00 KB (0.00%)
basic.ts 7.08 KB 7.08 KB 0.00 KB (0.00%)
batching.ts 10.95 KB 10.95 KB 0.00 KB (0.00%)
brand.ts 6.71 KB 6.71 KB 0.00 KB (0.00%)
cache.ts 11.39 KB 11.39 KB 0.00 KB (0.00%)
config.ts 22.55 KB 22.55 KB 0.00 KB (0.00%)
differ.ts 21.70 KB 21.70 KB 0.00 KB (0.00%)
http-client.ts 26.51 KB 26.51 KB 0.00 KB (0.00%)
http-router.ts 36.01 KB 36.01 KB 0.00 KB (0.00%)
logger.ts 11.76 KB 11.76 KB 0.00 KB (0.00%)
metric.ts 9.32 KB 9.32 KB 0.00 KB (0.00%)
optic.ts 6.93 KB 6.93 KB 0.00 KB (0.00%)
pubsub.ts 15.82 KB 15.82 KB 0.00 KB (0.00%)
queue.ts 12.64 KB 12.64 KB 0.00 KB (0.00%)
schedule.ts 11.63 KB 11.63 KB 0.00 KB (0.00%)
schema-bigdecimal.ts 13.89 KB 13.89 KB 0.00 KB (0.00%)
schema-binary.ts 40.70 KB 40.70 KB 0.00 KB (0.00%)
schema-class.ts 21.40 KB 21.40 KB 0.00 KB (0.00%)
schema-fromJsonSchemaDocument.ts 32.39 KB 32.39 KB 0.00 KB (0.00%)
schema-representation-roundtrip.ts 27.59 KB 27.59 KB 0.00 KB (0.00%)
schema-string-transformation.ts 15.13 KB 15.13 KB 0.00 KB (0.00%)
schema-string.ts 12.14 KB 12.14 KB 0.00 KB (0.00%)
schema-template-literal.ts 16.06 KB 16.06 KB 0.00 KB (0.00%)
schema-toArbitrary.ts 38.70 KB 38.70 KB 0.00 KB (0.00%)
schema-toCodeDocument.ts 25.79 KB 25.79 KB 0.00 KB (0.00%)
schema-toCodecJson.ts 20.64 KB 20.64 KB 0.00 KB (0.00%)
schema-toEquivalence.ts 20.81 KB 20.81 KB 0.00 KB (0.00%)
schema-toFormatter.ts 20.92 KB 20.92 KB 0.00 KB (0.00%)
schema-toJsonSchemaDocument.ts 25.51 KB 25.51 KB 0.00 KB (0.00%)
schema-toRepresentation.ts 20.91 KB 20.91 KB 0.00 KB (0.00%)
schema.ts 20.59 KB 20.59 KB 0.00 KB (0.00%)
stm.ts 13.95 KB 13.95 KB 0.00 KB (0.00%)
stream.ts 10.19 KB 10.19 KB 0.00 KB (0.00%)

@effect-bot
effect-bot force-pushed the agent/nelson/f3776b531b6f branch 2 times, most recently from feda373 to 99158a7 Compare October 21, 2026 09:57
@effect-bot
effect-bot force-pushed the v4/next-minor branch 4 times, most recently from 36cf926 to dbca9bc Compare October 21, 2026 20:33
@tim-smart
tim-smart force-pushed the agent/nelson/f3776b531b6f branch from 99158a7 to 2f58e6a Compare October 21, 2026 21:03
@tim-smart
tim-smart force-pushed the v4/next-minor branch 4 times, most recently from 8e6e2e0 to 005c3dd Compare October 21, 2026 22:39
@effect-bot
effect-bot force-pushed the v4/next-minor branch 15 times, most recently from 5a41feb to ccbffaa Compare October 21, 2026 23:56
@effect-bot
effect-bot force-pushed the agent/nelson/f3776b531b6f branch from 30bcb15 to fec3794 Compare October 22, 2026 02:36
@tim-smart
tim-smart merged commit 7ce7d03 into v4/next-minor Oct 22, 2026
9 checks passed
@tim-smart
tim-smart deleted the agent/nelson/f3776b531b6f branch October 22, 2026 02:43
@effect-bot effect-bot mentioned this pull request Oct 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant