AgentWeb quickstart

Connect AgentWeb to the AI agent you already use, find a mapped action, and call execute. Executing mapped actions through execute (MCP) or POST /api/execute (REST) is the core capability. Four steps.

Every live tool, including read_page and discover, requires an AgentWeb aw_ API key. Only the signup tools and agentweb_auth_status work anonymously.

1. Add the MCP server

AgentWeb exposes a Streamable HTTP MCP server at https://mcp.agentweb.us/mcp.

claude mcp add agentweb --transport http https://mcp.agentweb.us/mcp

Codex CLI (~/.codex/config.toml):

[mcp_servers.agentweb]
url = "https://mcp.agentweb.us/mcp"

Cursor and Windsurf: add https://mcp.agentweb.us/mcp as a remote MCP server by URL (Streamable HTTP; no catalog entry needed). Any other MCP client takes the same URL. Per-client steps: install.md. Show the human the Terms and Privacy Policy, then call agentweb_start_claim_link_signup. A real response (trimmed):

{
  "ok": true,
  "device_code": "awdc_50381e15f195...",
  "user_code": "BLWL-BDBN",
  "verification_uri_complete": "https://agentweb.us/agent/identity?user_code=BLWL-BDBN",
  "expires_in": 600,
  "interval": 5,
  "next_tool": "agentweb_poll_claim_link_signup",
  "customer_instruction": "Open this link and sign in once. When AgentWeb says you are connected, go back to your agent."
}

Show only verification_uri_complete to the human, then poll agentweb_poll_claim_link_signup with the device_code every interval seconds (pending polls return authorization_pending; the link expires after expires_in seconds). The completed poll returns the API key once. Reconnect with:

Authorization: Bearer aw_<key>

Fallbacks (email-code, raw HTTP, A2A) are on Auth & connections.

3. Find your action

Call list_actions with no arguments for the catalogue of mapped sites (over 1,100 and growing):

{
  "total": 1167,
  "page_size": 100,
  "next_cursor": "blackdiamondequipment.com",
  "sites": [
    { "domain": "allbirds.com", "action_count": 5, "connect_providers": ["allbirds-com"] },
    { "domain": "asos.com", "action_count": 6, "connect_providers": [] }
  ]
}

Call it again with an exact domain for that site’s full action definitions, including every parameter, defaults, and whether the action needs a connected account:

{
  "domain": "asos.com",
  "actions": [
    {
      "name": "search_products",
      "description": "Free-text product search. Returns itemCount, products[] (id, name, price, colour, brandName, url, imageUrl) and brand facets. Page with limit+offset.",
      "params": [
        { "name": "q", "required": true, "description": "Free-text search query, e.g. \"black linen shirt\"." },
        { "name": "limit", "description": "Page size.", "default": "24" }
      ]
    }
  ]
}

If an action lists an auth_provider, connect the target-site account first: check agentweb_connection_status, and if it is not connected call agentweb_start_connection, show the human the returned URL, then poll agentweb_poll_connection. Details on Auth & connections. If a site is not mapped yet, call request_map to queue a build and poll agentweb_map_status.

4. Execute and verify

Call execute (or POST /api/execute over REST) with the domain, action, and declared params. Over REST, an optional Idempotency-Key header (or idempotency_key field) maps retries to the same billing task so a retried call is never charged twice:

{
  "domain": "asos.com",
  "action": "search_products",
  "params": { "q": "black linen shirt", "limit": "2" }
}

A real response:

{
  "success": true,
  "domain": "asos.com",
  "action": "search_products",
  "data": {
    "kind": "json",
    "value": {
      "itemCount": 618,
      "products": [
        {
          "id": 210464145,
          "name": "ASOS DESIGN relaxed deep revere modal shirt in black",
          "price": { "current": { "value": 30, "text": "£30.00" }, "currency": "GBP" },
          "brandName": "ASOS DESIGN",
          "url": "asos-design/asos-design-relaxed-deep-revere-modal-shirt-in-black/prd/210464145"
        }
      ]
    }
  },
  "duration_ms": 2850,
  "map_version": "0.1.2",
  "billing": {
    "credits_charged": 1,
    "balance_remaining": 24999,
    "receipt_id": "awr_6ca354c4f1e95d0cde47e21d",
    "policy": "Credits are debited only on a verified completion; failed actions are refunded."
  }
}

Treat the returned fields as the source of truth, never an accepted request:

success answers “did the mapped call work”. For actions where step success can diverge from job completion (checkouts, payments), an outcome object states the job-level truth: status of complete (with proof such as an order ref), partial (with the exact missing_step and safe_to_retry), or unavailable.
On failure, success is false with a typed error.code (AUTH_REQUIRED, INSUFFICIENT_CREDITS, UPSTREAM_APP_ERROR, …), a trace_id you can quote in a bug report, and the credit reservation is refunded.
billing.receipt_id is the support receipt for the action.

Safety rules

Never place passwords, raw card numbers, unrestricted credentials, or unrelated private conversation content in a tool request.
Stop when the action is unsupported, unsafe, expired, over a limit, or missing approval.
Before any paid, irreversible, or externally visible action, summarize the exact inputs and obtain approval.
Use a first-party API when it already provides the full required workflow and access model.

Going further

Installing AgentWeb for a business or repo: Install AgentWeb
Payments, payment authority, and checkout: Agent commerce
MCP tools and discovery files
Authentication and connections
OpenAPI specification
Mapped-site library

Get started

Connect

Reference

Commerce

Plans

AgentWeb quickstart

1. Add the MCP server

3. Find your action

4. Execute and verify

Safety rules

Going further

​1. Add the MCP server

​2. Sign in

​3. Find your action

​4. Execute and verify

​Safety rules

​Going further

1. Add the MCP server

2. Sign in

3. Find your action

4. Execute and verify

Safety rules

Going further