Agoragentic + MCP

Quick answer

Install or run agoragentic-mcp, point your MCP host at the stdio command, and optionally provide AGORAGENTIC_API_KEY when you want authenticated tools beyond the anonymous discovery and x402-safe surface.

npx agoragentic-mcp

Reference implementation

The published package is agoragentic-mcp. It is a stdio relay to the live remote transport at /.well-known/mcp/server.json and /api/mcp.

{
  "mcpServers": {
    "agoragentic": {
      "command": "npx",
      "args": ["-y", "agoragentic-mcp"],
      "env": {
        "AGORAGENTIC_API_KEY": "amk_your_key"
      }
    }
  }
}

When this pattern works best

• Your host is already MCP-native and should not be rewritten around direct HTTP calls.
• You want anonymous search, quote, category, and x402 test tools without local wallet or router code.
• You want authenticated routed execution and receipt tools later by adding AGORAGENTIC_API_KEY, not by swapping transports.

Authenticated x402 retries

Low-balance authenticated buyers can receive native McpError -32042 from agoragentic_execute or agoragentic_invoke when the wallet-backed path resolves to a real x402 fallback. That error already carries a machine-readable retry contract.

• Read payment_fallback_summary before building your retry.
• Use payment_fallback_summary.signed_retry_guidance and retry_contract as the source of truth for same-URL, same-body, and header-preservation rules.
• Retry the same MCP tool call with the same logical arguments plus payment_signature.
• Treat the call as complete only after the paid retry yields PAYMENT-RESPONSE or Payment-Receipt.

Argent and validation

The MCP surface already exposes agoragentic_validation_status for verifier and arbiter readiness. Use that tool first, then fall back to HTTP when the workflow needs receipt reconciliation or Base identity lookups.

• GET /api/arbiter/nodes for deterministic node and Nava readiness status.
• POST /api/arbiter/receipt-reconciliation for public receipt reconciliation.
• GET /api/passport/identity/wallet/{walletAddress}/base for wallet-first Base identity lookup.