|
| 1 | +# WebMCP |
| 2 | + |
| 3 | +Web Model Context Protocol (WebMCP) is an [emerging web standard](https://github.com/webmachinelearning/webmcp/) that allows web applications to expose structured tools directly to AI agents running natively in the browser. Tools defined by an application allow AI assistants to interact with it directly, providing additional capabilities to the agent and reducing the need for DOM interactions. |
| 4 | + |
| 5 | +For example, an application to register a new user might provide a WebMCP tool for a browser's AI agent to create the user directly rather than requiring the agent to go through a complex wizard UI via DOM interactions. |
| 6 | + |
| 7 | +Angular provides experimental support for WebMCP, allowing you to easily register tools tied to your application's dependency injection lifecycle and automatically turn your Signal Forms into AI-ready tools. |
| 8 | + |
| 9 | +IMPORTANT: The WebMCP spec is very early in its lifecycle and is undergoing frequent changes. As such, WebMCP support in Angular is currently [**experimental**](reference/releases#experimental). APIs are subject to change even outside of major versions. |
| 10 | + |
| 11 | +## Provide tools for the application |
| 12 | + |
| 13 | +Use [`provideExperimentalWebMcpTools`](api/core/provideExperimentalWebMcpTools) in your application config to register tools for the entire lifecycle of the application. Tools provided this way are automatically registered when the application initializes and unregistered when the application is destroyed. |
| 14 | + |
| 15 | +The `execute` callback is invoked in the injection context of the associated `Injector`, meaning you can [`inject`](api/core/inject) services directly. |
| 16 | + |
| 17 | +```ts {header:"main.ts"} |
| 18 | +import {Service, inject, provideExperimentalWebMcpTools} from '@angular/core'; |
| 19 | +import {bootstrapApplication} from '@angular/platform-browser'; |
| 20 | +import {AppRoot} from './app-root'; |
| 21 | + |
| 22 | +@Service() |
| 23 | +class Greeter { |
| 24 | + sayHello(): string { |
| 25 | + return 'Hello agent!'; |
| 26 | + } |
| 27 | +} |
| 28 | + |
| 29 | +bootstrapApplication(AppRoot, { |
| 30 | + providers: [ |
| 31 | + provideExperimentalWebMcpTools([ |
| 32 | + { |
| 33 | + name: 'greet', |
| 34 | + description: 'Greets the agent.', |
| 35 | + inputSchema: {type: 'object', properties: {}}, |
| 36 | + execute: () => { |
| 37 | + const greeter = inject(Greeter); |
| 38 | + |
| 39 | + return {content: [{type: 'text', text: greeter.sayHello()}]}; |
| 40 | + }, |
| 41 | + }, |
| 42 | + ]), |
| 43 | + ], |
| 44 | +}); |
| 45 | +``` |
| 46 | + |
| 47 | +### Define tool parameters |
| 48 | + |
| 49 | +When a tool requires input from the AI assistant, define the expected arguments inside `inputSchema` using [JSON Schema](https://json-schema.org/) syntax. Angular automatically infers the parameter types passed into your `execute` callback based on the schema definition. |
| 50 | + |
| 51 | +```ts {header:"main.ts"} |
| 52 | +import {provideExperimentalWebMcpTools} from '@angular/core'; |
| 53 | +import {bootstrapApplication} from '@angular/platform-browser'; |
| 54 | +import {AppRoot} from './app-root'; |
| 55 | + |
| 56 | +bootstrapApplication(AppRoot, { |
| 57 | + providers: [ |
| 58 | + provideExperimentalWebMcpTools([ |
| 59 | + { |
| 60 | + name: 'searchCatalog', |
| 61 | + description: 'Searches the store catalog for products matching a query.', |
| 62 | + inputSchema: { |
| 63 | + type: 'object', |
| 64 | + properties: { |
| 65 | + query: { |
| 66 | + type: 'string', |
| 67 | + description: 'The search keywords.', |
| 68 | + }, |
| 69 | + maxResults: { |
| 70 | + type: 'number', |
| 71 | + description: 'Maximum number of results to return.', |
| 72 | + }, |
| 73 | + }, |
| 74 | + required: ['query'], |
| 75 | + additionalProperties: false, |
| 76 | + }, |
| 77 | + execute: ({query, maxResults}) => { |
| 78 | + // Type of `query` is inferred as `string`. |
| 79 | + // Type of `maxResults` is inferred as `number | undefined`. |
| 80 | + |
| 81 | + // Consider validating this at runtime, since inputs may not be validated to match the schema. |
| 82 | + if (typeof query !== 'string') throw new Error(`Bad query: ${query}`); |
| 83 | + if (typeof maxResults !== 'number' && maxResults !== undefined) |
| 84 | + throw new Error(`Bad maxResults: ${maxResults}`); |
| 85 | + |
| 86 | + const limit = maxResults ?? 5; |
| 87 | + return { |
| 88 | + content: [{type: 'text', text: `Returning up to ${limit} results for "${query}".`}], |
| 89 | + }; |
| 90 | + }, |
| 91 | + }, |
| 92 | + ]), |
| 93 | + ], |
| 94 | +}); |
| 95 | +``` |
| 96 | + |
| 97 | +TIP: Use `required: ['param1', 'param2', ...]` to remove `undefined` from the types of those parameters and use `additionalProperties: false` to restrict the argument object's type to only these parameters. |
| 98 | + |
| 99 | +## Provide tools for a route |
| 100 | + |
| 101 | +When building complex applications, you may only want certain tools available when the user is viewing specific routes. You can achieve this by providing tools directly in route definitions. |
| 102 | + |
| 103 | +```ts {header:"routes.ts"} |
| 104 | +import {provideExperimentalWebMcpTools} from '@angular/core'; |
| 105 | +import {Routes} from '@angular/router'; |
| 106 | + |
| 107 | +export const routes: Routes = [ |
| 108 | + { |
| 109 | + path: 'dashboard', |
| 110 | + loadComponent: () => import('./dashboard').then((m) => m.Dashboard), |
| 111 | + providers: [ |
| 112 | + provideExperimentalWebMcpTools([ |
| 113 | + { |
| 114 | + name: 'exportDashboardReports', |
| 115 | + description: 'Exports the current dashboard analytics.', |
| 116 | + inputSchema: {type: 'object', properties: {}}, |
| 117 | + execute: () => ({ |
| 118 | + content: [{type: 'text', text: 'Dashboard export successfully triggered.'}], |
| 119 | + }), |
| 120 | + }, |
| 121 | + ]), |
| 122 | + ], |
| 123 | + }, |
| 124 | +]; |
| 125 | +``` |
| 126 | + |
| 127 | +NOTE: When registering tools to a particular route, consider configuring the router to use [`withExperimentalAutoCleanupInjectors`](api/router/withExperimentalAutoCleanupInjectors) to ensure tools are automatically _unregistered_ when the user navigates away from the route. Without this option, WebMCP tools declared on routes will remain accessible to AI agents even after the user has navigated to a different route. |
| 128 | + |
| 129 | +```ts {header:"app.config.ts"} |
| 130 | +import {ApplicationConfig} from '@angular/core'; |
| 131 | +import {provideRouter, withExperimentalAutoCleanupInjectors} from '@angular/router'; |
| 132 | +import {routes} from './routes'; |
| 133 | + |
| 134 | +export const appConfig: ApplicationConfig = { |
| 135 | + providers: [provideRouter(routes, withExperimentalAutoCleanupInjectors())], |
| 136 | +}; |
| 137 | +``` |
| 138 | + |
| 139 | +## Provide tools within services |
| 140 | + |
| 141 | +For dynamic use cases, the [`declareExperimentalWebMcpTool`](api/core/declareExperimentalWebMcpTool) function registers a tool directly within an injection context and automatically unregisters it when that context is destroyed. |
| 142 | + |
| 143 | +```ts {header:"counter.ts"} |
| 144 | +import {Service, declareExperimentalWebMcpTool, signal, inject} from '@angular/core'; |
| 145 | + |
| 146 | +@Service() |
| 147 | +export class Counter { |
| 148 | + readonly count = signal(0); |
| 149 | + |
| 150 | + constructor() { |
| 151 | + declareExperimentalWebMcpTool({ |
| 152 | + name: 'getCounter', |
| 153 | + description: 'Reads the global counter.', |
| 154 | + inputSchema: {type: 'object', properties: {}}, |
| 155 | + execute: () => ({ |
| 156 | + content: [{type: 'text', text: `The count is: ${this.count()}.`}], |
| 157 | + }), |
| 158 | + }); |
| 159 | + } |
| 160 | +} |
| 161 | +``` |
| 162 | + |
| 163 | +While `declareExperimentalWebMcpTool` works in any injection context, watch out for [name collisions](#name-collisions) and prefer using it in root services. |
| 164 | + |
| 165 | +## Implicit tools in Signal Forms |
| 166 | + |
| 167 | +You can create a WebMCP tool implicitly from an existing Angular [Signal Form](essentials/signal-forms) with minimal configuration. Angular converts your form models into rich WebMCP tools, effectively supporting highly dynamic forms without requiring you to manually write JSON schemas or event handlers. |
| 168 | + |
| 169 | +### Enable the WebMCP forms feature |
| 170 | + |
| 171 | +First, add [`provideExperimentalWebMcpForms`](api/forms/signals/provideExperimentalWebMcpForms) to your root application providers: |
| 172 | + |
| 173 | +```ts {header:"main.ts"} |
| 174 | +import {bootstrapApplication} from '@angular/platform-browser'; |
| 175 | +import {provideExperimentalWebMcpForms} from '@angular/forms/signals'; |
| 176 | +import {AppRoot} from './app-root'; |
| 177 | + |
| 178 | +bootstrapApplication(AppRoot, { |
| 179 | + providers: [provideExperimentalWebMcpForms()], |
| 180 | +}); |
| 181 | +``` |
| 182 | + |
| 183 | +### Opt in a Signal Form |
| 184 | + |
| 185 | +Second, when defining a Signal Form using [`form`](api/forms/signals/form), pass the `experimentalWebMcpTool` configuration option to opt-in to an implicit WebMCP tool. Angular will inspect your form's data model and automatically generate a JSON schema for connected AI agents. |
| 186 | + |
| 187 | +```ts {header:"user-registration.ts"} |
| 188 | +import {Component, signal} from '@angular/core'; |
| 189 | +import {form, required, minLength} from '@angular/forms/signals'; |
| 190 | + |
| 191 | +@Component({ |
| 192 | + selector: 'app-user-registration', |
| 193 | + templateUrl: './user-registration.html', |
| 194 | +}) |
| 195 | +export class UserRegistration { |
| 196 | + private readonly model = signal({ |
| 197 | + firstName: '', |
| 198 | + lastName: '', |
| 199 | + age: 0, |
| 200 | + hobbies: ['Web Development'], |
| 201 | + }); |
| 202 | + |
| 203 | + readonly userForm = form( |
| 204 | + this.model, |
| 205 | + (f) => { |
| 206 | + required(f.firstName, {message: 'First name is mandatory.'}); |
| 207 | + required(f.lastName, {message: 'Last name is mandatory.'}); |
| 208 | + }, |
| 209 | + { |
| 210 | + // Implicitly registers a WebMCP tool named `registerUser` with parameters derived from `model`. |
| 211 | + experimentalWebMcpTool: { |
| 212 | + name: 'registerUser', |
| 213 | + description: 'Registers a new user.', |
| 214 | + }, |
| 215 | + submission: { |
| 216 | + action: async (formValue) => { |
| 217 | + console.log('Submitting user:', formValue); |
| 218 | + // ... |
| 219 | + }, |
| 220 | + }, |
| 221 | + }, |
| 222 | + ); |
| 223 | +} |
| 224 | +``` |
| 225 | + |
| 226 | +In this example, Angular generates a WebMCP tool with a JSON schema which: |
| 227 | + |
| 228 | +1. includes `firstName`, `lastName`, `age`, and `hobbies` as parameters inferred from the initial value of the `model` signal. |
| 229 | +2. defines `firstName` and `lastName` as _required_ fields as inferred from the [`required`](api/forms/signals/required) validator. |
| 230 | +3. defines `hobbies` as an array of strings, allowing the agent to provide an arbitrary amount of hobbies. |
| 231 | + |
| 232 | +Beyond inferring the input schema, Angular also connects the WebMCP tool to the form's validation logic and submission handler. This means the agent will observe any validation errors triggered by its inputs or any failures which happen during submission, allowing it to self-correct and potentially retry. |
| 233 | + |
| 234 | +NOTE: Async validators are _not_ triggered and should be handled by the submission action. |
| 235 | + |
| 236 | +#### Constraints |
| 237 | + |
| 238 | +Angular infers the WebMCP schema from the initial value of your form model. This requires: |
| 239 | + |
| 240 | +- Concrete initial values (`''`, `0`, `false`): Angular cannot infer data types from `null` or `undefined`. |
| 241 | +- Non-empty arrays (`['Hello!']`): Angular cannot infer data types from an empty array and requires at least one initial value. |
| 242 | + |
| 243 | +## Best practices |
| 244 | + |
| 245 | +Keep the following best practices in mind: |
| 246 | + |
| 247 | +### Name collisions |
| 248 | + |
| 249 | +WebMCP requires each tool to have a unique name and will throw an error if the same tool name is registered multiple times. This means calling `declareExperimentalWebMcpTool` or `provideExperimentalWebMcpTools` in a context where they might be registered multiple times (such as a component constructor) may lead to errors at runtime. |
| 250 | + |
| 251 | +Prefer placing tools on application providers, route providers, or root services where possible. When putting tools on a component, including [implicit tools in Signal Forms](#implicit-tools-in-signal-forms), ensure that component is only ever rendered on the page at most _once_ at any given time. |
| 252 | + |
| 253 | +### Validate tool inputs |
| 254 | + |
| 255 | +Angular does not provide any implicit validation that the inputs provided by an agent actually match the defined JSON schema. Consider explicitly validating arguments to the `execute` function before using them to ensure reliability. |
| 256 | + |
| 257 | +### Testing |
| 258 | + |
| 259 | +Consider using a mock WebMCP implementation like [`@mcp-b/webmcp-polyfill`](https://www.npmjs.com/package/@mcp-b/webmcp-polyfill) to effectively unit test your tools. |
0 commit comments