Declarative API Equivalent

[EisenbergEffect]

I'm curious as to why this is being pursued exclusively as a JavaScript API. It seems that most of this could be done entirely declaratively, or at least that there should be a declarative equivalent. Simply adding a few attributes, combined with existing HTML semantics should do the trick for a lot of scenarios.

<form action="/todos" method="post" tool-name="add-todo" tool-description="Add a new todo item to the list">
  <input type="text" name="description" required tool-prop-description="The text of the todo item">
  <button type="submit">Add Todo</button>
</form>

This might even be a good opportunity to improve forms with features that folks have been asking for for decades, such as:

• Supporting more action values.
• Enable a form to use AJAX
• Do different things with the response from an AJAX form submission (e.g. pass it to the agent vs. put it somewhere in the HTML document).

While agent interaction is a "big thing" right now, it would be great to think of this in the context of the broader, long-term web platform, and come up with a consistent, extensible solution. We should also consider how content creators without JS experience will be able to participate in the agent ecosystem, and strive to be as inclusive as we can.

[vitalets]

I also thought about this approach. But how to declare listTodos tool in this manner?

[EisenbergEffect]

I also that about this approach. But how to declare listTodos tool in this manner?

I think that could be done with a simple link.

<a href="/todos" tool-name="list-todos">All Todos</a>

Whenever an a or form tool is invoked by an agent, the browser could just use fetch to make the request and pass the response back to the agent that invoked the tool.

[MiguelsPizza]

Whenever an a or form tool is invoked by an agent, the browser could just use fetch to make the request and pass the response back to the agent that invoked the tool.

The counter argument here would be that this limits the control the tool creator has over things like param and response parsing. One of the strengths of the MCP spec is you can determine exactly what information to return to the model's context via filtering with existing javascript APIs.

How would we filter the output of href="/todos" so it does not return irrelevant data to the agent's context? Would you build backend endpoints? One for the user and one for the agent?

[EisenbergEffect]

How would we filter the output of href="/todos" so it does not return irrelevant data to the agent's context? Would you build backend endpoints? One for the user and one for the agent?

This can all be handled with standard HTTP/REST patterns.

BTW, I'm not opposed to adding a JS API, but there should be a declarative API as a minimum requirement. Tools defined in HTML and JS could be presented uniformly to the agent. The agent doesn't need to know or care how they were defined.

(I don't want to see the same mistake made with MCP that was made with Web Components. Web Components shipped with a JS only API, and now it's taking years to try to rollout the declarative APIs that everyone actually wished they had to begin with.)

A declarative API would allow all existing HTML to be upgraded to support tools with very little effort (only adding a couple of attributes), it requires no JS experience or tool infrastructure, works with every backend, and fits nicely into RESTful patterns in use for close to two decades. Search engines would be able to determine which pages support tools. Pages with declarative tools would be able to run in No JS restricted environments. Etc. Etc.

[MiguelsPizza]

Search engines would be able to determine which pages support tools. Pages with declarative tools would be able to run in No JS restricted environments

This is a really interesting idea. Just so I'm understanding, an implementation might look like this? (Rails example):

<form action="/todos" method="post" tool-name="add-todo" tool-description="Add a new todo item to the list">
  <input type="text" name="description" required tool-prop-description="The text of the todo item">
  <button type="submit">Add Todo</button>
</form>

class TodosController < ApplicationController
  def create
    @todo = Todo.create(description: params[:description])
    
    respond_to do |format|
       # html for the user execution
      format.html { redirect_to todos_path }
      # JSON for the agent execution
      format.json { render json: @todo }
    end
  end
end

And the browser would translate this HTML to the functional equivalent of this tool:

window.mcp.registerTool('add-todo', {
  description: 'Add a new todo item to the list',
  parameters: {
    type: 'object',
    properties: {
      description: {
        type: 'string',
        description: 'The text of the todo item'
      }
    },
    required: ['description']
  }
}, async (params) => {
  try {
    const formData = new FormData();
    formData.append('description', params.description);

    const res = await fetch('/todos', {
      method: 'POST',
      headers: { 'Accept': 'application/json' },
      body: formData,
      credentials: 'same-origin'
    });

    if (!res.ok) throw new Error(`HTTP ${res.status}`);

    return {
      content: [{
        type: 'text',
        text: `Created todo: ${params.description}`
      }]
    };
  } catch (error) {
    return {
      content: [{
        type: 'text',
        text: `Failed to create todo: ${error.message}`,
      }],
      isError: true
    }
  });

Is this what you had in mind?

[EisenbergEffect]

Yep. That's the idea.

I'm sure there are plenty of details to work out to make it real. But I think there are some big opportunities if we consider the declarative approach. Designing it and the JS API at the same time could also help both turn out better in the end.

[MiguelsPizza]

I spent some time implementing a declarative approach. Here's a working demo with a Go webserver. The web app SSRs the HTML and a JS script parses it to convert forms/links with tool-* attributes into WebMCP tools.

WebMCP-SSR.mp4

After building this out, there's serious utility to this approach but also some limitations.

The first issue is tool explosion. If every list item gets its own update/delete tool, you quickly poison the agent's context with too many tools. You can work around this with hidden forms that expose generic tools taking IDs as parameters, but this is more complex than just adding tags to existing HTML.

The bigger issue is that executing tools needs to be functionally the same as UI interactions. With declarative forms, we lose control over response handling to get both UI updates and JSON responses for agents. I ended up using hidden iframes and query parameters to update the UI while still returning custom responses to the model. With JavaScript tools, you can handle the form submission and response in the same function body, giving you full control over the model's context while staying in sync with UI state. There's probably a better way around this if anyone has ideas.

@anssiko happy to contribute this repo to this project if that's a better home for it.

[anssiko]

An explainer for a declarative WebMCP API proposal is ready for review: PR #26

See also: supplementary demo for hands-on experimentation.

Thank you @MiguelsPizza and @EisenbergEffect for your contributions in advancing this.

[jasonjmcghee]

Just want to bring up PWA manifest link rel as a potential parallel - like: Manifest

<link rel="mcp:tools" href="/.well-known/mcp-tools.json">

[tomayac]

I like this idea, and it resonates with what I was trying to express during the meeting. FWIW, if the URL is a .well-known one, there may not even be need to announce it (as per your <link> suggestion), it could just be discovered naturally.

[khushalsagar]

Summary of the discussion today.

08:48 ... a proposal to enable web pages to expose tools via HTML custom tool-* attributes
08:48 08:48 <anssik> <form action="/todos" method="post" tool-name="add-todo" tool-description="Add a new todo item to the list"> 08:48 <anssik> <input type="text" name="description" required tool-prop-description="The text of the todo item"> 08:48 <anssik> <button type="submit">Add Todo</button> 08:48 <anssik> </form> 08:48 <anssik>
08:49 Anssi: this proposal broadens the scope of the API to content creators
08:49 ... declarative has a significantly broader reach than imperative API among developers, expands to content authors
08:49 q+
08:49 * Zakim sees reillyg, tomayac on the speaker queue
08:49 ... learnings from Web Components suggest an imperative-only API without a declarative is problematic
08:50 ack tomayac
08:50 * Zakim sees reillyg on the speaker queue
08:50 ack reillyg
08:50 * Zakim sees no one on the speaker queue
08:51 Thomas: I'm wondering what's implementers expectation for JS-rendered apps?
08:52 ... do you expect people to harvest declarative instructions to execute as JS, or should there be a separate way, e.g. style?
08:52 q?
08:52 * Zakim sees no one on the speaker queue
08:52 Alex: what do you mean by expectations, Thomas?
08:53 Thomas: what will happen in the ecosystem, e.g. open graph instruction, people can deliver them via JS, you have to have them in HTML delivered from the server
08:53 ... would the same be true for declarative instructions for this API
08:53 Alex: declarative is complementary to

s
08:54 q+
08:54 * Zakim sees kush on the speaker queue
08:54 ... for React usage, JS API provides the needed flexibility
08:54 ... my demo was not expensive to implement
08:55 ... couple of issues noted in the issue, how to handle elicitation
08:55 ... not sure how people want to handle it
08:55 *** anolan (~anolan@ed1fd930.publics.cloak) has quit (anolan)
08:55 ... another is expectation for the web server, WebMCP currently is JSON-RPC protocol and web apps that only serve HTML, do we have them add a new route for JSON?
08:55 q?
08:55 * Zakim sees kush on the speaker queue
08:56 Thomas: one alternative way to deliver would be via .well-known URL with declarative tools the page support?
08:56 q?
08:56 * Zakim sees kush on the speaker queue
08:57 ack kush
08:57 * Zakim sees no one on the speaker queue
08:58 Khushal: we don't know all the use cases for tools, some might be tied to HTML elements, I wonder if we see agent specific tools that make no sense to have UI associated
08:58 ... I like the direction of this issue, wanted to identify edge cases
08:59 ... good to drill down into details of declarative to be able to ship it
08:59 RRSAgent, draft minutes
08:59 I have made the request to generate https://www.w3.org/2025/09/18-webmachinelearning-minutes.html anssik
09:00 Alex: PR welcomes review and comments

[MiguelsPizza]

I like this idea, and it resonates with what I was trying to express during the meeting. FWIW, if the URL is .well-known one, there may not even be need to announce it (as per your <link> suggestion), it could just be discovered naturally.

Ah I see, sorry I misunderstood during the meeting. The .well-known idea is actually currently being incubated by the MCP community for remote MCP servers, with ongoing proposals around a simple /.well-known/mcp.json for decentralized discovery (e.g., listing endpoints, auth hints, and capabilities without needing a central registry).
modelcontextprotocol/modelcontextprotocol#1147

My understanding for the goals for WebMCP is that the tools are executed in the context of the webpage. So even though the agent might live outside of the webpage (like in a browser extension) the call that is made to the API wrapped by the WebMCP tool (or html form) still comes from the document which holds the tool in it's DOM. The benefits of this are as follows:

a) UI state is kept in sync with the agents understanding of the system state (unlike remote MCP call which might not update the UI)

b) The agent does not need a independent authorization path since it is making calls within the existing documents auth context.

c) Tools are scoped to UI state allowing the agent to ingest tools in a more segmented and manageable way

d) Elicitations happen in browser

That said, the MCP work on .well-known could inspire WebMCP/Remote MCP hybrids. Any thoughts on what that would look like @jasonjmcghee @tomayac ?

[jasonjmcghee]

@MiguelsPizza I guess my major question with declarative / trying to do html pure... What's the point? You need JavaScript to take action don't you? Maybe I'm missing part of the motivation. In the server-side action context, you're no longer operating within the browser / client side

[MiguelsPizza]

@jasonjmcghee This is a good question. I'll make the case for it here as I understand it. @EisenbergEffect please add anything I miss.

You need JavaScript to take action don't you?

As I understand it, the current SDK draft for the WebMCP spec implies that the browser manages the WebMCP server. This means when the DOM is rendered or updated, the browser will parse the DOM and register tools with the tab's MCP server if they come from one of three sources:

1. Tools registered in JavaScript with window.mcp/agent.provideContext/registerTool
2. Forms or tags that have been declared as MCP tools (via a tool-name attribute)
3. Tools similar to 1 but registered in the service worker context via self.

When a client calls listTools(), the combined list of tools from these three sources is returned.

When a client calls callTool('some_declarative_tool'), it submits the form from the document's context (no JavaScript required). The only difference from a standard form submission being that the requested response is JSON (this is up for debate, we might not want a different content type at all, per the open questions in PR.

Functionally, what the declarative API is saying is "I want the agent to see this form and be able to submit it" without having to register an onSubmit handler in JavaScript and wrap it in a WebMCP tool.

This is in line with @EisenbergEffect's vision of making the WebMCP APIs accessible to non-JavaScript developers who have no interest in writing JavaScript (like many of the Rails devs I've worked with :) )