Universal MCP Gateway

agent402 is the paid gateway layer between LLM agents and useful external tools. Human mode is product-level: what it gives, where to plug it, and what to monitor.

agent402 is a machine-first MCP endpoint with x402 billing. Agent mode is protocol-level: discovery order, request flow, and 402 recovery behavior.

/mcp /.well-known/mcp.json /x402/discovery /meta.json

Single Gateway

One MCP surface for multiple paid tools. You can ship one integration and expand tool coverage without client rewrites.

Usage-Based Spend

Per-tool pricing is explicit in discovery, so both humans and agents can reason about cost before invoking tools.

Machine Discoverable

Canonical paths are stable and public: /mcp, /.well-known/mcp.json, and /x402/discovery.

Discovery First

Resolve server card from /.well-known/mcp.json, then resolve capabilities and prices from /x402/discovery.

MCP Lifecycle

Connect to /mcp and execute initialize -> tools/list -> tools/call.

402-Aware Calls

On paid calls, handle 402 Payment Required, settle x402, and retry with proof without changing arguments.

Why Teams Use It

Human mode is optimized for product and infra decisions. Think of this as the “what does this gateway buy us?” view.

Unified MCP entrypoint instead of per-tool custom contracts.
Explicit billing semantics (x402) for paid tool operations.
Agent + human discovery compatibility out of the box.
Stable URLs that can be indexed by docs tools and bots.

Human Integration Flow

GET /.well-known/mcp.json to discover canonical metadata.
GET /x402/discovery for tool list, schemas, and pricing.
Use /mcp as MCP transport endpoint.
On 402 Payment Required, complete payment and retry with proof.

curl -sS https://agent402.dev/.well-known/mcp.json
curl -sS https://agent402.dev/x402/discovery
curl -sS https://agent402.dev/health

Core Agent Paths

For robust clients, always keep these three paths cached and refreshed: /mcp, /.well-known/mcp.json, /x402/discovery.

Key Endpoints

MCP Transporthttps://agent402.dev/mcp

MCP Cardhttps://agent402.dev/.well-known/mcp.json

x402 Discoveryhttps://agent402.dev/x402/discovery

Endpoint Reference

Path	Methods	Purpose	URL
`/mcp`	POST, GET, DELETE	Primary Streamable HTTP MCP transport.	https://agent402.dev/mcp
`/.well-known/mcp.json`	GET	Canonical MCP server card for discovery.	https://agent402.dev/.well-known/mcp.json
`/server.json`	GET	MCP Registry-compatible metadata document.	https://agent402.dev/server.json
`/x402/discovery`	GET	Price + capability discovery for paid tools.	https://agent402.dev/x402/discovery
`/meta.json`	GET	Machine-friendly site metadata and endpoint map.	https://agent402.dev/meta.json
`/metrics`	GET	Operational and business metrics snapshot.	https://agent402.dev/metrics
`/pmf/scorecard`	GET	Weekly PMF adoption scorecard (paid usage validation).	https://agent402.dev/pmf/scorecard

Tool Catalog

openrouter-chat

LLM inference and chat completion via OpenRouter. Pay-per-use, no API key needed. Supports GPT-4o, Claude, and 200+ models.

$0.005 per call

brave-search

Web search via Brave Search API. Pay-per-use, no API key needed. Fast internet search for AI agents.

$0.002 per call

Agent Quickstart

This mode is concise and protocol-oriented. Use this exact order: /.well-known/mcp.json -> /x402/discovery -> /mcp.

Discover metadata from MCP card.
Cache price/schema from discovery endpoint.
Initialize MCP session and call tools.
If 402 is returned, pay and retry same tool call.

MCP transport: https://agent402.dev/mcp
MCP card: https://agent402.dev/.well-known/mcp.json
x402 discovery: https://agent402.dev/x402/discovery
Health: https://agent402.dev/health

MCP Install Flow

# 1) Discover canonical server card
curl -sS https://agent402.dev/.well-known/mcp.json

# 2) Fetch paid tool catalog + schema + price
curl -sS https://agent402.dev/x402/discovery

# 3) Connect MCP transport
POST https://agent402.dev/mcp
content-type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "clientInfo": { "name": "agent-client", "version": "1.0.0" },
    "capabilities": {}
  }
}

402 Retry Flow

If tools/call returns HTTP 402:
1) Read x402 payment requirements from response.
2) Pay requested amount to requested pay target.
3) Retry same tools/call with x402 payment proof.

Do not mutate tool arguments between attempt #1 and paid retry.

Connect This Page In Cursor @docs

This page is intentionally agent-readable. You can connect it directly in Cursor docs index.

In Cursor:
1) Open @docs in chat
2) Choose "Add docs"
3) Add one of these URLs:
   - https://agent402.dev/
   - https://agent402.dev/meta.json
   - https://agent402.dev/llms.txt

Recommended primary source: https://agent402.dev/

Agent Endpoint Map

Path	Methods	Purpose	URL
`/mcp`	POST, GET, DELETE	Primary Streamable HTTP MCP transport.	https://agent402.dev/mcp
`/.well-known/mcp.json`	GET	Canonical MCP server card for discovery.	https://agent402.dev/.well-known/mcp.json
`/server.json`	GET	MCP Registry-compatible metadata document.	https://agent402.dev/server.json
`/x402/discovery`	GET	Price + capability discovery for paid tools.	https://agent402.dev/x402/discovery
`/meta.json`	GET	Machine-friendly site metadata and endpoint map.	https://agent402.dev/meta.json
`/metrics`	GET	Operational and business metrics snapshot.	https://agent402.dev/metrics
`/pmf/scorecard`	GET	Weekly PMF adoption scorecard (paid usage validation).	https://agent402.dev/pmf/scorecard

Bootstrap JSON

{
  "version": "1",
  "server": "agent402",
  "endpoints": {
    "mcp": "https://agent402.dev/mcp",
    "mcpCard": "https://agent402.dev/.well-known/mcp.json",
    "serverJson": "https://agent402.dev/server.json",
    "x402Discovery": "https://agent402.dev/x402/discovery",
    "health": "https://agent402.dev/health",
    "metrics": "https://agent402.dev/metrics",
    "pmfScorecard": "https://agent402.dev/pmf/scorecard",
    "meta": "https://agent402.dev/meta.json",
    "llms": "https://agent402.dev/llms.txt",
    "robots": "https://agent402.dev/robots.txt",
    "sitemap": "https://agent402.dev/sitemap.xml"
  }
}