GEDX402 — MCP builder setup

Wire GEDX402 MCP in Cursor for operator testing — list paid tools and settle x402 USDC from the CDP buyer wallet.

Customer pay path: EXTERNAL-PAYER.md — @x402/fetch primary; awal optional (no MCP, no API keys). See INTEGRATOR-QUICKSTART.md.

Agentic Wallet path: AGENTIC-WALLET.md — npx skills add coinbase/agentic-wallet-skills, fund USDC on Base, then direct x402 or gedx402_list_tools / gedx402_call.

Operator testing (hosted MCP): Cloudflare Worker at https://mcp.gedx402.com/mcp — signs via CDP secrets (CDP_API_KEY_ID, CDP_API_KEY_SECRET, CDP_WALLET_SECRET). Not the primary customer integration.

Hub: https://gedx402.com · Manifest: /.well-known/agents.json · Hosted MCP: https://mcp.gedx402.com/mcp

1. Cursor MCP (hosted — recommended)

Add one URL to .cursor/mcp.json in ged or ged-x402 (merge with other servers such as ms-anchor-mcp):

{
  "mcpServers": {
    "ged-x402": {
      "url": "https://mcp.gedx402.com/mcp"
    }
  }
}

Restart MCP / reload the Cursor window after editing. No npm run mcp process — Cursor talks directly to the Worker.

Operator deploy: npm run deploy -- --shard=mcp (sets CDP secrets from ../ged/.env). Smoke: npm run mcp:smoke.

Without server-side CDP secrets: gedx402_list_tools and gedx402_health work; gedx402_call returns a clear error. For laptop-signed payments, use the optional local bridge (§3).

Discovery: hub /.well-known/x402 includes remote_mcp.

Operator prod testing

gedx402_call on the hosted MCP pays from the operator CDP buyer wallet (ged-x402-buyer), not customer wallets. Use this for prod smoke and agent testing only.

Fund the buyer with USDC on Base (and Solana if enabled). Cap per call: GEDX402_MAX_PAYMENT_USD (default 5).

Code Mode (orchestrate tools via code)

Cloudflare Code Mode wraps all GEDX402 MCP tools behind a single code tool. The model writes JavaScript that calls codemode.gedx402_* methods; the mcp Worker runs it in an isolated dynamic Worker (LOADER binding). Use for multi-step x402 flows instead of one tool call per LLM turn.

2. CDP credentials (operator deploy / optional local bridge)

Create or extend the sibling ged repo .env (loaded automatically by src/load-env.js):

One-time buyer setup:

npm run buyer:setup

Fund the printed EVM address with enough USDC on Base for starter calls (worst_case_price_usd from manifest).

Portal: https://portal.cdp.coinbase.com/

3. Local MCP bridge (optional — dev only)

Use only when you need your laptop to sign x402 payments (e.g. hosted Worker lacks CDP secrets, or shard filtering via env). Not required for normal Cursor use — prefer §1 hosted URL.

Do not add command/args to .cursor/mcp.json for production; keep hosted url only.

Smoke the bridge from a terminal (not Cursor MCP):

npm run mcp

Optional env (shell or .env):

Local Cursor wiring (dev only — spawns node scripts/ged-x402-mcp.mjs):

{
  "mcpServers": {
    "ged-x402-local": {
      "command": "node",
      "args": ["scripts/ged-x402-mcp.mjs"]
    }
  }
}

Open the ged-x402 folder as the Cursor workspace. Requires ../ged/.env CDP creds on your machine.

4. MCP tools

When GEDX402_SHARD is set, per-route tools (e.g. gedx402_chat_micro) are also registered.

gedx402_list_tools

Returns tools in outcome-first order: browser extract → managed RAG session → image → voice → chat tiers last.

Optional shard filter — browser, aisearch, media, chat, search, jobs, llm, embed, image, etc.

Returns JSON array: name, shard, price, endpoint, description.

gedx402_call

Example — cheap chat probe:

{
  "tool": "gedx402_chat_micro",
  "body": {
    "messages": [{ "role": "user", "content": "Say hi." }],
    "max_tokens": 16
  }
}

Example — vector search:

{
  "tool": "gedx402_search_query",
  "body": {
    "namespace": "demo",
    "query": "edge inference",
    "top_k": 3
  }
}

Example — Scrape Lite (browser hero):

{
  "tool": "gedx402_firecrawl_scrape",
  "body": { "url": "https://example.com" }
}

5. Starter tools (cheap probes)

Outcome-first — browser and RAG heroes before chat tiers. These map to per-shard starter routes (starter:true in agents.json) from SHARD_STARTER_ROUTES:

Run gedx402_list_tools (no filter) for the live outcome-first list with price and endpoint.

Bundle starter examples

Voice (GET /v1/models?bundle=voice):

{
  "tool": "gedx402_voice_sessions",
  "body": { "budget": { "duration_minutes": 5, "max_turns": 30 } }
}

Browser (GET /v1/models?bundle=browser):

{
  "tool": "gedx402_firecrawl_scrape",
  "body": { "url": "https://example.com" }
}

RAG (GET /v1/models?bundle=rag):

{
  "tool": "gedx402_embed_small",
  "body": { "text": "Workers AI runs at the edge." }
}

Managed RAG (GET /v1/models?bundle=managed-rag):

{
  "tool": "gedx402_aisearch_sessions",
  "body": { "initial_index": { "url": "https://example.com/docs" }, "budget": { "max_index_ops": 1, "max_queries": 1 } }
}

Search (GET /v1/models?bundle=search):

{
  "tool": "gedx402_exa_search",
  "body": { "query": "x402 agent marketplace APIs", "num_results": 5, "type": "auto" }
}

5. BYOK operator MCP (ged repo — research only)

Customers pay x402 on shard URLs. For operator research in Cursor, wire upstream MCP from the sibling ged repo (vault-bootstrap — no local key files; GED_CF_API_TOKEN in ged/.env only):

Agents: ged/.cursor/agents/firecrawl.md, tavily.md, exa.md, sociavault.md. Restart Cursor after setup.

6. CLI buyer demo (no MCP)

Paid fetch without Cursor — optional CDP Bazaar search or direct chat call:

npm run x402:buyer-demo              # POST chat.gedx402.com/v1/chat/micro
npm run x402:buyer-demo -- --search  # Bazaar NL search, then pay discovered URL

Logs payment-response settlement header. See DISTRIBUTION.md §5 for Bazaar indexing.