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

WebMCP loses important context when tools appear or disappear

Open
  • Is something wrong?
#262 7 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
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
javascript
Domain
api

Research direction

Read the related discussions #87, #96, #102, and #167 to understand how this proposal overlaps with existing work. The issue asks for a standard way to expose why a capability is unavailable while leaving authorization with the site, but does not identify files, tests, or a specific API. Done would mean a concrete design for preserving that context in the agent-visible tool surface.

Written by the indexing model from the issue text.

Description

Problem

WebMCP currently gives agents a very simple view of capability state: a tool is either available or it is not.

That works for simple cases, but real applications have much richer state behind those tools.

A tool may become unavailable because:

  • the user does not have permission
  • their subscription does not include the feature
  • they switched organizations or workspaces
  • the current workflow is not ready for that action
  • a resource is still processing
  • the feature is temporarily unavailable

The site usually knows exactly why.

But when the site responds by simply registering or unregistering the tool, that meaning is lost. The agent only sees that the tool disappeared.

I think this creates a form of semantic context blindness.

Example

Imagine a reporting application.

A user asks an agent:

"Export this report."

Earlier, the agent could see:

export_report

The user then switches to another workspace where exports are not included in their plan.

The application unregisters export_report.

Now the agent only knows:

export_report no longer exists.

It cannot tell whether:

  • the user lacks permission
  • the workspace plan does not support exports
  • the report is not ready yet
  • exports are temporarily unavailable
  • or something else changed

Those situations should lead to very different agent behavior.

If the agent knew:

Export is unavailable because this workspace does not include report exports.

it could explain that to the user and continue helping with the parts of the workflow that are still available.

Developer-side problem

Leaving this entirely to application code also makes developers responsible for keeping the WebMCP tool registry synchronized with constantly changing application state. It also poses security concerns, due to constant changes that would need to happen, and coding changes that need to be maintained by a developer.

For example:
.js

if (canExport) {
registerTool(exportReport)
} else {
unregisterTool("export_report")
}

That seems simple until an application has dozens of tools and permissions can change because of login/logout, organization switching, subscription changes, role changes, feature flags, or async workflow state.

It becomes easy to:

  • forget to remove a tool when access changes
  • repeatedly register/unregister tools unnecessarily
  • create races where an agent plans around a tool just as it disappears
  • hide an entire tool even though only one operation inside it is restricted

Async/service-style tools make this even more noticeable.

For example, one manage_report tool might allow a user to view and edit a report, while exporting requires an additional permission. Removing the entire tool because export is unavailable would also hide the operations the user is still allowed to perform.

What I think is missing

I am not suggesting that WebMCP should become an OAuth or authorization system, or that the browser should understand every site’s permission model.

The site should remain responsible for authentication and authorization.

But it may be useful for WebMCP to have a standard way for a site to preserve some of the meaning behind capability changes instead of reducing everything to:

tool exists / tool does not exist

For example, a site could communicate that a capability is currently unavailable and optionally provide a reason such as:

  • permission required
  • entitlement required
  • authentication required
  • invalid current state
  • temporarily unavailable

The exact API is less important to me than preserving that semantic context.

Related discussions

This seems related to:

  • #87 — authentication/session context
  • #96 — scopes and delegation context
  • #102 — per-tool scopes
  • #167 — dynamic tool updates and registration churn

I think this is slightly different from those discussions because the core problem is not specifically scopes.

The broader issue is that rich application capability state is currently being projected into a binary tool-presence signal, and useful context is lost between the site and the agent.

MCP naturally sits at the backend authorization boundary; WebMCP does not. WebMCP therefore needs a cleaner way to project backend capability state into the agent-visible tool surface, without reducing everything to syncing tools with register/unregister.

Dominant language
Bikeshed
Stars
4.7k
Forks
328
Avg merge
1d 21h
Merged PRs (30d)
15

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 webmachinelearning/webmcp

All issues in webmachinelearning/webmcp

Similar issues

More Backend & API Design issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.