AgentX — Claude + MCP + x402 + LangGraph + Facinet (Avalanche Fuji)

A complete local demo showing how Claude Desktop can call MCP tools that:

1. Use Facinet for gasless USDC payment flows
2. List active facilitators on Avalanche Fuji
3. Execute contract calls through Facinet

This README is written as a judge runbook: clone, configure, run, and test in minutes.

---

1) What this project demonstrates

• MCP integration with Claude Desktop via stdio (mcp/index.ts)
• Paid tool execution with x402 (src/index.ts)
• AI agent backend with LangGraph (agents/langgraph/app)
• Gasless payment utilities with Facinet SDK (mcp/index.ts, mcp/scripts/facinet_bridge.js)
• Avalanche Fuji network configuration end-to-end

---

2) Repo architecture

• src/index.ts
  x402-protected resource/proxy server (port 5000)

• mcp/index.ts
  MCP server launched by Claude Desktop (stdio). Exposes tools:

  • facinet-list-facilitators
  • facinet-pay-usdc
  • facinet-execute-contract

• agents/langgraph/app/__main__.py
  Python LangGraph agent (port 10000)

• mcp/scripts/facinet_bridge.js
  Node bridge used by Python agent for Facinet actions

---

3) Wallet roles (important)

Use different wallets for payer and admin/payee.

• Payer wallet (customer side):

  • PRIVATE_KEY in Claude MCP config (claude_desktop_config.json)
  • Used by MCP/x402 client signing

• Admin/payee wallet (merchant side):

  • PUBLIC_KEY in root .env
  • Used by x402 server as recipient/verification identity

If payer and payee are the same, payment behavior may be rejected or confusing.

---

4) Prerequisites

• Node.js 20+
• Python 3.12
• uv package manager
• Claude Desktop
• Avalanche Fuji test funds (AVAX + USDC for payer wallet)

Windows note: if PowerShell blocks npm, use npm.cmd.

---

5) Environment setup

5.1 Root environment (.env)

Create/verify root .env using .env.example:

• PUBLIC_KEY → admin/payee wallet address
• X402_NETWORK=avalanche-fuji
• PRIVATE_KEY (used by some local scripts/bridge)
• BASE_URL=http://localhost:5000
• FACINET_NETWORK=avalanche-fuji
• GOOGLE_API_KEY for LangGraph model

5.2 MCP environment

mcp/.env.example exists for local MCP script runs.
For Claude Desktop, MCP env is usually passed in claude_desktop_config.json.

---

6) Claude Desktop MCP config

Edit:

%AppData%\Claude\claude_desktop_config.json

Use:

{
  "mcpServers": {
    "mcpay": {
      "command": "C:\\Program Files\\nodejs\\npm.cmd",
      "args": [
        "--silent",
        "--prefix",
        "d:\\project\\agentX\\mcp",
        "run",
        "dev"
      ],
      "env": {
        "PRIVATE_KEY": "0xYOUR_PAYER_PRIVATE_KEY",
        "BASE_URL": "http://localhost:5000",
        "FACINET_NETWORK": "avalanche-fuji"
      }
    }
  },
  "preferences": {
    "coworkScheduledTasksEnabled": false,
    "ccdScheduledTasksEnabled": false,
    "coworkWebSearchEnabled": true,
    "sidebarMode": "chat"
  }
}

Then fully restart Claude Desktop.

---

7) Install dependencies

From repo root:

npm.cmd install
npm.cmd --prefix d:\project\agentX\mcp install
cd d:\project\agentX\agents\langgraph
uv sync

---

8) Start services (correct order)

Terminal A — LangGraph agent

cd d:\project\agentX\agents\langgraph
uv run app --host localhost --port 10000

Terminal B — x402 server

cd d:\project\agentX
npm.cmd run dev

Terminal C — MCP (optional manual run)

Claude Desktop usually starts MCP automatically.
For debugging only:

cd d:\project\agentX\mcp
$env:PRIVATE_KEY="0xYOUR_PAYER_PRIVATE_KEY"
$env:BASE_URL="http://localhost:5000"
$env:FACINET_NETWORK="avalanche-fuji"
npm.cmd run dev

---

9) Judge test flow (copy/paste prompts)

In Claude Desktop chat:

1. Facilitator discovery (Facinet path)

   • List facilitators on avalanche-fuji using Facinet.

2. Payment action (Facinet path)

   • Pay 1 USDC to 0xRecipientAddress on avalanche-fuji via Facinet.

3. Contract call action (Facinet path)

• Execute contract function register on 0xYourContractAddress with ABI [...] and args [...] on avalanche-fuji via Facinet.

---

10) Request flow diagrams

10.1 Facinet tool flow

Claude → MCP tool (facinet-list-facilitators / facinet-pay-usdc / facinet-execute-contract) → Facinet SDK → facilitator network execution on Avalanche Fuji

---

11) Troubleshooting

A) Unexpected token ... is not valid JSON in MCP

Cause: non-protocol logs written to stdout in stdio mode.
Status: fixed in mcp/index.ts by redirecting debug/info logs to stderr.
Action: restart MCP and Claude Desktop.

B) Python imports unresolved in VS Code

Select interpreter:

d:\project\agentX\agents\langgraph\.venv\Scripts\python.exe

Then reload VS Code window.

C) npm.ps1 cannot be loaded

Use npm.cmd instead of npm in PowerShell.

D) Facinet tool call fails

Check:

• FACINET_NETWORK=avalanche-fuji in Claude MCP config
• payer wallet has required Fuji funds
• payer and payee wallets are different
• contract address / ABI / args are valid for target chain

---

12) Security notes

• Never commit real private keys.
• Rotate any exposed test keys immediately.
• Use low-value test funds for demos.

---

13) Quick reset commands

Stop listeners on key ports:

Get-NetTCPConnection -LocalPort 5000,10000 -State Listen |
  Select-Object -ExpandProperty OwningProcess -Unique |
  ForEach-Object { Stop-Process -Id $_ -Force }

Restart core services:

cd d:\project\agentX\agents\langgraph
uv run app --host localhost --port 10000

# new terminal
cd d:\project\agentX
npm.cmd run dev

---

14) What judges should evaluate

• MCP tool availability in Claude Desktop
• Facinet network/tool usability on Avalanche Fuji
• Clear wallet-role separation (payer vs admin/payee)