Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

support effectful, request-aware annotations for MCP

Open
  • Is something wrong?
#9,610 2 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
32/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
typescript
Domain
backend-api-design

Research direction

Start by reading McpSchema.EnabledWhen, the tool annotation APIs, and the HTTP request scoped server setup mentioned in the issue. Work out how effectful annotations should run with authenticated request services and how their dependencies interact with shared server services, including subscriptions and legacy reverse requests. Done means a design and implementation that supports request-aware annotations with clear execution rules and tests for per-caller visibility and metadata.

Written by the indexing model from the issue text.

Description

enhancement
What is the problem this feature would solve?

Is there any way to have the EnabledWhen from McpSchema be based on an Effect? Or another approach to achieve that behavior?

The tools we expose are based on user permissions and customer settings
~ David (Discord)

Currently its quite difficult to expose tools based on the authenticated user's permissions and customer settings. These checks can require database or service calls and if we want one shared MCP server to filter tools for each caller and check access is needed again before execution.

McpSchema.EnabledWhen currently accepts a sync predicate over protocol version, client capabilities, and client information, but it cannot run an Effect or receive authenticated request services. Checking permissions inside a handler protects execution, but the tool still appears in tools/list.

The same need can apply to other annotations. For example, a tool's title or metadata could depend on customer settings or the user's locale. Could we support effectful annotations generally, with clear rules about when they run?

What is the feature you are proposing to solve the problem?

One option is to keep .annotate for static values and add .annotateEffect for values computed when handling a request:

const JokeTool = Tool.make("DadJoke", {
	parameters: Tool.EmptyParams,
	success: Schema.String
})
	.annotateEffect(
		McpSchema.EnabledWhen,
		Effect.gen(function*() {
			const user = yield* CurrentUser
			const permissions = yield* Permissions
			const allowed = yield* permissions.hasSenseOfHumor(user)
			return () => allowed
		})
	)
	.annotateEffect(
		Tool.Title,
		Effect.gen(function*() {
			const user = yield* CurrentUser
			const settings = yield* UserSettings
			return yield* settings.notSafeForWorkTitle(user.id)
		})
	)

The example returns a predicate because that is EnabledWhen's current value type. Allowing an effectful predicate directly could be another option, but would only address visibility.

CurrentUser, Permissions, and UserSettings are application services. Authentication provides the principal for the current request. Client-supplied MCP metadata is not proof of identity. The API would need to track these dependencies and distinguish request services from shared application services.

What alternatives have you considered?

We can load permissions with an Effect, then capture the result in EnabledWhen. For different callers, our example builds a fresh registry inside each HTTP request using Layer.fresh and McpServer.layerHttpRequestScoped.

This works, but rebuilds the registry for each request and requires sessionless clients. It does not support subscriptions or legacy reverse requests. We would like request-aware annotations without requiring this server setup.

Dominant language
TypeScript
Stars
16.7k
Forks
808
Avg merge
10h 12m
Merged PRs (30d)
813

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Effect-TS/effect

All issues in Effect-TS/effect

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.