Next.js and WebMCP: The Skill That Makes Your Site Speak the Language of AI Agents

I've spent the last few months getting my hands dirty with WebMCP on caprai.dev, and I have to admit the experience has been enlightening. Not in the romantic sense of the term, but in the practical one: I made mistakes, corrected them, and now I know exactly what it takes to make a Next.js site truly ready for AI agents living in the browser.

When I say "AI agents in the browser," I'm referring to those assistants that are now starting to populate Chrome, Edge, and other browsers. Gemini watching you while you browse, ChatGPT Desktop trying to understand what's in front of you. The problem is that these agents, until yesterday, were like tourists without a map: they had to guess how a site works by looking at its HTML, trying to interpret buttons, forms, and links without any guidance.

I Created a Skill

From all this experience, I created a Skill through which you can easily guide your Coding Agent in structuring a WebMCP for a Next.js project, and you can find it here https://github.com/capraidev/nextjs-webmcp

WebMCP: The Missing Protocol

WebMCP is the standard that the W3C is defining to solve this problem. The idea is simple but powerful: instead of letting the agent guess, the site itself declares what it can do. Can I search for content? Yes, here's how. Want to read an article? Use this tool. Need to fill out a form? Here are the rules.

It's not science fiction, it's pragmatism. And implementing it on Next.js, with all its rendering and optimization mechanisms, requires a surgical approach.

A Single Registry: The Most Important Lesson

The mistake I made in the first iteration was the one everyone makes: describing tools in different places. One version for the browser, one for the server, one for llms.txt, maybe a fourth for future documentation. The result? Guaranteed divergence within a week.

The solution I adopted is a single registry. Tools are described once and only once, with complete schema, validation rules, and usage limits. From that central registry:

• Browser-available tools are generated
• The API route that executes them server-side is fed
• llms.txt is compiled for those who prefer to read text
• The groundwork is laid for future remote MCP endpoints

Zero duplication, zero scattered logic. When you modify a tool, the change propagates everywhere. It's the kind of architecture that lets you sleep soundly.

Reads and Writes: A Fundamental Distinction

One thing I learned by observing agent behavior is that there's a substantial difference between reading and writing. Read operations—searching articles, consulting a catalog—are relatively safe. They respect existing access rules, don't modify anything, have no consequences.

Actions with real consequences, however, stay where they should be: in visible forms. The agent can help you fill them out, can suggest what to write, but you press the "submit" button. Physical person, physical responsibility.

Newsletter subscription? The agent fills in the fields, you confirm. Contact message? Same mechanism. Payments, registrations, data processing consent: all out, on purpose. Not because it can't be done technically, but because it shouldn't be done ethically.

Security and Privacy: Not Optional

The first time I launched WebMCP on caprai.dev, PageSpeed immediately pointed out problems with the Content Security Policy. Nonces, Trusted Types, Cross-Origin-Opener-Policy: all aspects that in a rushed implementation you tend to ignore or work around.

Instead, they need to be addressed head-on. The skill I developed includes precise guidance on how to make WebMCP coexist with a strict CSP, how to handle dynamic nonces in Next.js, how to configure Trusted Types without opening holes.

And then there are the basic but essential protections: no personal data in tool responses, rate limiting per IP to prevent abuse, strict input validation to prevent prompt injection. These are precautions that seem obvious on paper, but in practice require constant attention.

From Code to Production: The Complete Path

One of the most delicate parts was managing the Chrome and Edge origin trial. For those who don't know, WebMCP is still in experimental phase, and to activate it you need a specific token for your domain. On Vercel, this token must be configured as an environment variable, complete with expiration reminder.

I included in the skill:

• Ready-to-adapt TypeScript templates for your domain
• Automated tests that verify each tool before deployment
• Checks that prevent silent regressions
• Scripts to verify which tools each page exposes
• Lighthouse audits specific to "Agentic browsing"

This last point was a revelation. Lighthouse introduced dedicated audits to verify how agent-friendly a site is. Passing them all requires care, but the feedback is immediate and valuable.

The Mistakes That Cost Me Time

It's worth talking about what didn't work on the first try. I tried to dynamically generate WebMCP tools based on page context. Interesting idea, disastrous implementation. Agents got confused, tools changed between renders, caching became a nightmare.

Solution: static tools, always the same, clearly documented. You manage context in parameters, not in availability.

Another mistake: blindly trusting client-side validation. Agents, by definition, bypass the visual interface. If your only validation is a React form, you're in trouble. You need strict server-side validation, with explicit schema and clear error messages.

Why Do It, and Why Do It Right

You might wonder if it's worth investing time in a standard still being defined. My answer, having done it, is yes. Not because WebMCP will definitely become the dominant standard, but because the approach it enforces—explicitly declaring your site's capabilities—is inherently sound.

Even if WebMCP were replaced by something else tomorrow, having a centralized registry of available tools, rigorous validation, clear separation between reading and writing—all of this remains valuable. It's solid architecture disguised as a standard implementation.

And then there's the fact that AI agents in the browser are here to stay. Call them WebMCP, call them something else, but the need to interface in a structured way with websites won't disappear. Better to be ready now, with a clean and verified implementation, than to catch up later.

The Future Is Conversational, But It Must Be Safe

The idea of a web where agents can search, read, help you fill out forms is fascinating. But only if done with care. Only if security and privacy are integrated from day zero, not added as a patch afterward.

The skill I developed on caprai.dev represents exactly this: a complete path, from mistakes to solution, to make a Next.js site ready for this future. With production code, tests, verifications, and above all with awareness of where to draw boundaries.

Because yes, we want agents to help us. But they must do so respecting the rules that we, as creators of web experiences, decide to impose. WebMCP is the tool. Using it well is our responsibility.