AAL (Agent Access Layer)

WebMCP gives agents tools. AAL adds identity, user-authorized permissions, spending limits, approvals, and verifiable receipts to WebMCP for consequential actions.

Comment

Inspiration

WebMCP gives AI agents a much better way to interact with the web.

Instead of looking at pixels, finding buttons, and simulating clicks, an agent can discover structured tools that a website exposes directly:

search_products()
add_to_cart()
place_order()
change_subscription()

That felt like a major shift. But it also exposed a missing layer.

If a website gives an agent place_order(), who says the agent is allowed to call it?

WebMCP provides the interface between a website and an agent, but consequential actions introduce a different set of questions:

  • Which user is the agent acting for?
  • Which tools did that user authorize?
  • How much can the agent spend?
  • How long does that authority last?
  • Which actions still require human approval?
  • What happens if execution fails halfway through?
  • Can we prove what was actually authorized and executed?

We built AAL — Agent Access Layer to answer those questions.

The simplest way we describe it is:

WebMCP gives agents tools. AAL gives them permission to use them.

What it does

AAL adds a delegation and transaction layer around WebMCP.

A user can connect an agent to a website and grant it explicit authority: which WebMCP tools it can call, under what limits, and which actions require additional approval.

For a simple read, the agent can call the tool normally.

For a consequential action, AAL turns the call into a transaction:

Agent calls WebMCP tool
        ↓
Site prepares exact action
        ↓
AAL checks permissions + limits
        ↓
User or policy approves
        ↓
Site commits the action
        ↓
Signed receipt

Under the hood, AAL focuses on four things:

Delegation — explicit grants connect a user, a site, an agent session, a set of tools, and bounded permissions.

Authorization — consequential WebMCP calls use a prepare → approve → commit flow instead of allowing page JavaScript to directly trigger effects.

Accountability — grants, commitments, approvals, and outcomes are linked together with signed, verifiable receipts.

Metering — agent activity can be measured using evidence tied to the authorized call, creating a path toward websites charging agents or agent platforms for usage.

We also built an AAL SDK so this isn't limited to our demo. A developer building a WebMCP-powered site can integrate AAL into their existing tools and add delegation, permissions, approvals, limits, and receipts without rebuilding the protocol from scratch.

The goal is for a developer to go from:

WebMCP tool

to:

WebMCP tool + AAL policy = authorized agent capability

For the demo, we pushed this all the way through a payment flow using WebMCP + AAL + x402 + Base Sepolia test USDC.

The agent can construct a transaction, but it cannot approve its own consequential action. The user sees the exact payment terms, explicitly approves them, the designated wallet authorizes the payment, and the resulting execution can be reconciled into a verifiable receipt.

How we built it

We intentionally treated WebMCP as the tool transport, not the security boundary.

AAL is built around three core pieces, packaged behind an SDK that WebMCP developers can integrate into their own sites.

AAL SDK

The SDK is the developer-facing layer.

It gives WebMCP-powered sites a straightforward way to:

  • register tools with AAL
  • declare which tools are read-only or consequential
  • define permissions and limits
  • connect server-side prepare and commit handlers
  • add agent delegation
  • trigger approval when required
  • handle revocation and session state
  • return signed transaction receipts

The goal was to hide as much protocol complexity as possible while keeping the important security boundaries intact.

Developers should be able to keep building normal WebMCP tools while AAL handles the authorization lifecycle around them.

WebMCP adapter

A lightweight browser adapter detects WebMCP and exposes the site's tools to the agent.

It handles the agent-facing interaction, consent UX, approvals, pending states, and receipt presentation.

But it intentionally has very little authority.

It cannot decide that an agent is authorized to spend money, mutate application state, or bypass a policy.

Site transaction service

The site's backend is the actual enforcement point.

It:

  • authenticates the site's user
  • validates the WebMCP tool against a server-owned catalog
  • verifies the agent's grant
  • enforces tool and spending limits
  • prepares the exact proposed effect
  • reserves authorization capacity
  • verifies required approval
  • executes server-side handlers
  • records the resulting state
  • signs receipts

One of our most important rules is:

Page JavaScript never gets to decide that an agent is authorized to perform a consequential action.

Grant Service

The Grant Service handles explicit delegation.

The user approves a grant covering a specific site, specific WebMCP tools, limits, expiration, and required forms of evidence.

The site keeps the actual grant and enforcement logic server-side; the browser receives only the information necessary to drive the experience.

We built the protocol around deterministic schemas, signatures, canonical hashes, idempotency keys, state machines, revocation, and conformance vectors so authorization decisions can be reproduced instead of depending on implementation-specific behavior.

For the x402 demo, we added a separate trusted approval surface and a deliberately constrained testnet payment flow so we could test AAL against a real consequential action rather than just a toy API call.

Challenges we ran into

WebMCP exposes capability, not authority

The first challenge was architectural.

A WebMCP tool being available does not mean an agent should automatically be allowed to use it.

We had to separate:

"This tool exists"

from:

"This agent is authorized to use this tool,
for this user,
under these conditions."

That distinction shaped the entire project.

Making the protocol easy enough to actually integrate

Designing a secure authorization protocol is one problem.

Making it something a normal WebMCP developer would actually use is another.

AAL has grants, commitments, proofs, approvals, receipts, revocation, limits, and recovery state. We didn't want every website developer to have to understand or implement all of that themselves.

That is why the SDK became such an important part of the project.

The challenge was finding the right abstraction: hide the protocol machinery without hiding the security model.

A developer should mostly think about their tool, its effects, and the policy around it. AAL should handle the rest.

Browser JavaScript is not trustworthy enough

It would have been much easier to implement authorization in the page itself.

But an XSS vulnerability, compromised dependency, or malicious page script could then alter tool descriptions, transaction terms, or approval flows.

So consequential authorization had to move server-side.

Exactly-once execution is mostly an illusion

One of the hardest problems appeared after an action had been dispatched.

Imagine an agent places an order. The merchant processes it, but the server crashes before receiving the response.

Did it execute?

Simply retrying could create two orders.

Calling it failed could also be wrong.

So AAL has an explicit unknown state.

Instead of pretending every distributed action resolves cleanly, we use durable commitments, idempotency, outcome inspection, reconciliation, and receipt revisions to eventually determine what happened without blindly executing the action again.

Authentication is not the same as approval

Another major challenge was distinguishing:

"The user is here."

from:

"The user approved these exact terms."

For sensitive actions, especially payments, simply authenticating the user is insufficient. The approval has to be cryptographically connected to the actual transaction being executed.

That forced us to model identity, agent-key possession, user authentication, trusted display, payment authorization, and execution evidence as separate signals instead of collapsing everything into one vague notion of "trust."

Accomplishments that we're proud of

We're proud that AAL is not just an architecture around one demo.

We built the SDK so any WebMCP-powered website can start integrating the same authorization model into its own tools.

That was an important milestone for us because the value of an authorization layer comes from being reusable across sites, agents, and use cases.

We're also proud that AAL preserves the simplicity that makes WebMCP interesting.

The developer still starts with:

Expose a WebMCP tool.

Then AAL adds the machinery necessary when that tool crosses from information into authority.

We're especially proud of the end-to-end payment architecture.

A single flow separates:

  1. the agent proposing an action,
  2. AAL determining whether it is permitted,
  3. the user approving the exact transaction,
  4. the wallet authorizing the transfer,
  5. the payment network executing it,
  6. the application fulfilling it, and
  7. AAL producing evidence of the result.

None of those steps is allowed to silently substitute for another.

We also designed the system around failure from the beginning: replay protection, revocation, crashes, duplicate requests, stale grants, payment uncertainty, signer failures, chain reorganizations, and partial execution are states the protocol explicitly models rather than edge cases hidden behind a success boolean.

What we learned

The biggest thing we learned is that agent identity is not the fundamental primitive.

Delegated authority is.

For an agentic web, knowing that a request came from "an AI agent" is much less useful than knowing:

This user authorized this agent to use these WebMCP capabilities on this site, within these limits, until this time.

We also learned that a protocol only matters if developers can actually adopt it.

The SDK forced us to separate what an application developer really needs to think about from what AAL can safely handle underneath.

For most developers, the important questions should be:

What does this tool do?
What authority should it require?
What limits should apply?
Does the user need to approve it?

They shouldn't need to become experts in grants, signatures, canonicalization, replay protection, or distributed transaction recovery just to make their WebMCP site safe for agents.

Finally, the more consequential an agent action becomes, the more important it is to separate proposal, authorization, execution, and evidence.

An agent can propose.

A user or policy can authorize.

A site can execute.

Evidence can tell everyone what actually happened.

Those are different responsibilities.

WebMCP makes the agent-native web interface possible. We think explicit delegation is the next layer it needs to move from calling tools to safely doing real things.

What's next for AAL (Agent Access Layer)

The next step is making the SDK the easiest way to add authorization to a WebMCP-powered site.

We want the integration to feel less like implementing a new security protocol and more like adding standard web middleware:

WebMCP tool
    +
AAL SDK
    +
AAL policy
    =
agent-safe capability

From there, we want to:

  • get the SDK into more real WebMCP sites
  • explore standardized agent-to-site billing
  • simplify the developer API even further
  • validate AAL across different agent hosts
  • expand beyond the initial Node implementation
  • add additional trusted approval profiles
  • improve portable verification of receipts
  • support richer multi-step agent workflows over time

The long-term idea is straightforward:

WebMCP can become the interface agents use to access the web. AAL can become the authorization layer developers add when those agents need permission to actually do things.

Built With

Share this project:

Updates

Submission history