WebAgent Protocol

An open MCP extension for the open web. AI agents can discover, verify, and safely use the tools that any website publishes, starting from nothing but its domain name.

MCP connects a model to tools you have installed. WebAgent Protocol (WAP) lets the model find tools on sites it has never seen:

• Discovery. A website publishes a signed manifest at /.well-known/wap.json.
• Native tools. Claude, Cursor, Codex, or any other MCP host gets the site's capabilities as native tools.
• Signed results. Every answer is signed by the business, so a quoted price is provably the business's price.
• Protection for the business. Proof-of-work and rate limits stop bots from draining the business's AI budget.
• Protection for the user. Actions that change something or spend money are confirmed with the user, and built-in loop protection stops two AIs from talking in circles forever.

Free and open source (MIT). Python 3.11+. It's a library: you install it and build on it, and you choose how strict every protection is and where the state lives.

One function, three ways in

from wap.server import WAPServer

wap = WAPServer(name="Golden Crust Bakery", domain="bakery.example", private_key=KEY, require_pow=True)


@wap.action(description="Units of a pastry available right now.", effects="read")
async def check_pastry_stock(item: str) -> StockLevel: ...


wap.mount(app)  # your FastAPI app

That single decorator publishes:

How it relates to MCP and A2A

WAP adds what an open-web setting needs and an installed-server setting can assume:

• Replies you can prove. Every reply is Ed25519-signed and bound to the domain.
• Admission control. Anyone can call without registering, but abuse costs the caller more than it costs the business.
• Bounded dialogues. Conversations between agents are guaranteed to end.

The full proposal, written as an MCP Specification Enhancement Proposal, is in docs/mcp_extension.md.

Built for real deployments

Everything is configurable, and you bring your own infrastructure:

See docs/configuration.md for every setting.

Quickstart

Install

pip install webagent-protocol               # client + CLI
pip install "webagent-protocol[server]"     # business side: FastAPI + /mcp endpoint
pip install "webagent-protocol[mcp]"        # wap-mcp bridge for Claude, Cursor, Codex

To work from source: git clone https://github.com/varadganjoo/WebAgent-Protocol && pip install -e ".[dev]". The import name is wap.

Run the demo

python examples/bakery_server.py      # a bakery agent on http://localhost:8000
python examples/shopper_agent.py      # discovers it, negotiates, reserves (screenshot above)
wap inspect localhost:8000            # the verified manifest and tool schemas
wap ask localhost:8000 "hold 2 almond croissants for Ada"

To watch a language model do the shopping instead, run examples/llm_agent.py. It needs pip install "webagent-protocol[mcp]" openai python-dotenv and OPENAI_API_KEY (optionally OPENAI_LLM) in a .env file. The model discovers the bakery, gets its capabilities as tools, negotiates, and asks you before it reserves anything:

python examples/llm_agent.py "Buy 12 sourdough croissants for Ada at the best price you can get"

Use it from Claude, Cursor, or Codex

Option A: the bridge (any WAP site, discovered on demand). Add wap-mcp as an MCP server. When the model calls wap_discover("bakery.example"), the site's tools appear in its tool list as bakery_example__check_pastry_stock, bakery_example__reserve_item, and so on. Before a tool that changes something runs (bakery_example__reserve_item), the host shows the user a confirmation prompt.

{
  "mcpServers": {
    "webagent": { "command": "wap-mcp", "env": { "WAP_CONFIRM": "write" } }
  }
}

That is the config for Claude Desktop (claude_desktop_config.json) and Cursor (.cursor/mcp.json). For the other hosts:

• Claude Code: claude mcp add webagent -- wap-mcp
• Codex (~/.codex/config.toml): [mcp_servers.webagent] with command = "wap-mcp"
• Pre-loading sites: use wap-mcp bakery.example other.example or WAP_DOMAINS=..., which is useful for hosts that don't refresh tool lists.

Option B: connect straight to one site's /mcp. This is plain remote MCP, for example claude mcp add --transport http bakery https://bakery.example/mcp.

The bridge's safety settings all have safe defaults and can be changed through environment variables:

• which actions need the user's approval (WAP_CONFIRM), and whether new sites need approval (WAP_APPROVE_SITES);
• domain allow and block lists (WAP_ALLOWED_DOMAINS, WAP_BLOCKED_DOMAINS);
• private-network blocking;
• how instruction-like site text is handled;
• key pinning and auth tokens.

The full list is in docs/configuration.md.

Use it from Python

from wap import WAPClient


async def ask_user(request) -> bool:  # your UI: called before any write/financial action
    return input(f"Allow {request.summary()}? [y/N] ").lower() == "y"


async with WAPClient(confirm=ask_user, trust_on_first_use=True) as client:
    manifest = await client.discover("bakery.example")  # verified signature, domain, expiry

    stock = await client.invoke("bakery.example", "check_pastry_stock", {"item": "Sourdough Croissant"})
    print(stock.structured_data, stock.verified)  # {'available': 24, ...} True

    session = client.session("bakery.example")  # multi-turn, state kept server-side
    offer = await session.send(
        capability_id="negotiate_bulk_price",
        payload={"item": "Sourdough Croissant", "quantity": 12, "offered_unit_price": 3.6},
    )

    async for event in client.query("bakery.example", "Any croissants left?"):  # SSE streaming
        print(event.text or "", end="")

Already have an MCP server? Put it on the open web

from mcp.server.mcpserver import MCPServer
from wap.server import WAPServer

tools = MCPServer("inventory")  # your existing MCP server


@tools.tool()
def check_stock(sku: str) -> dict: ...


wap = WAPServer(name="Acme", domain="acme.example", private_key=KEY)
wap.include_mcp(tools)  # its tools become signed, discoverable, abuse-protected
app = wap.create_app()  # serves wap.json, /wap/v1/interact and /mcp

Loop protection: no infinite loops between agents

When your assistant negotiates with a business's assistant, both are language models and neither is sure when to stop. WAP bounds every conversation on both sides:

How each side enforces it:

• Fingerprints ignore cosmetic changes, so "Any croissants??" and "any croissants" count as the same request. A repeated question that gets a changing answer, such as polling stock, counts as progress.
• The business refuses to continue a loop before running any tool, returning loop_detected (409) or conversation_limit (429).
• The user's side stops itself before sending, and counts error replies as replies.
• In Claude or Cursor, the model receives a tool error telling it to stop, summarize, and report back to the user. In our evaluation, a model told to keep repeating a lowball offer was stopped on its 6th call in 5 of 5 runs, and the business never received more than five of its requests, even when the model ignored the stop instruction and kept trying.

All limits can be tuned with ConversationPolicy. The algorithm is in spec §12.2.

Architecture

sequenceDiagram
    autonumber
    participant H as MCP host<br/>(Claude / Cursor / Codex)
    participant Br as wap-mcp bridge
    participant B as Business agent<br/>(WAPServer)
    participant T as Business tools / LLM

    H->>Br: wap_discover("bakery.example")
    Br->>B: GET /.well-known/wap.json
    B-->>Br: signed manifest
    Note over Br: verify signature, domain & origin binding, expiry, pins
    Br-->>H: tools/list_changed → bakery_example__reserve_item, …
    H->>Br: bakery_example__reserve_item({...})
    Note over Br: loop guard · JSON Schema validation
    opt proof-of-work required
        Br->>B: GET /wap/v1/challenge
        Note over Br: solve SHA-256 puzzle
    end
    Br->>B: POST /wap/v1/interact (signed request)
    Note over B: rate limit → signature → replay → PoW → auth → loop guard
    B->>T: validated call (only now)
    B-->>Br: SSE tokens + signed reply
    Note over Br: verify reply against manifest key
    Br-->>H: structured result + verification metadata

wap/
├── spec/       models · crypto (Ed25519, canonical JSON) · pow (Hashcash) · conversation (loop guard)
├── server/     WAPServer + @action · router (WAP endpoints, SSE) · mcp_endpoint (/mcp) · mcp_import · rate_limiter
├── client/     resolver (discovery + verification) · session (WAPClient, WAPSession) · exceptions
├── mcp/        bridge (wap-mcp: built-in tools + dynamic per-site tools)
└── cli/        wap ask · inspect · verify · keygen · serve

Security at a glance

• Domain authenticity. Manifests are signed and bound to the exact domain they were fetched from. Endpoints must stay on that origin, discovery never follows redirects, and keys can be pinned.
• Reply integrity. Replies are verified against the manifest key and bound to the request. The test suite includes a man-in-the-middle that rewrites prices; the client catches it.
• Replay and session hijacking. Requests are signed and time-bound, with a replay cache. Sessions belong to the key that opened them, and negotiated quotes can only be redeemed in their own session.
• Economic defence. Challenges are stateless and single-use, and their difficulty can't be downgraded. Requests are limited per IP and per agent key. Rejected traffic never reaches your code.
• Side effects need consent. Write and financial actions are confirmed with the user and carry idempotency keys. Free-text requests are read-only unless confirmed.
• Tool poisoning. Site-written text is sanitised, truncated and labelled before any model sees it.
• The /mcp endpoint enables the MCP SDK's DNS-rebinding protection for the manifest's domain.
• Signed means attributable, not safe. Treat reply text as data, never as instructions.

Documentation

What we measured

We ran a real model (gpt-6-luna) against a live bakery server in Docker, with nothing mocked (results, method):

Tokens are not WAP's main argument: on a small page a text scraper is cheaper for a read-only question. The difference is that the WAP agent can act, safely. The whitepaper has the details and limitations; docker build -f evals/Dockerfile -t wap-eval . reproduces everything.

Development

pip install -e ".[dev]"
pytest -q                                   # full suite; Redis and Node.js tests run when installed
ruff check . && ruff format --check .

The suite covers:

• the official MCP client talking to /mcp over streamable HTTP;
• two server instances sharing a real Redis;
• property-based fuzzing, and canonical JSON cross-checked against Node.js;
• adversarial cases: forged or re-keyed manifests, tampered replies, replays, session hijacking, poisoned tool descriptions, lost responses and double-booking, and looping agents.

python examples/load_test.py --workers 4 --redis-url redis://... runs a real multi-process load test. Contributions are welcome; see CONTRIBUTING.md.

License

MIT © Varad Ganjoo. Free to use, modify, and ship.