npx @402md/mcp

npm install -g @402md/mcp
402md-mcp

# Stellar
export STELLAR_SECRET="SCZANGBA5YHTNYVVV3C7CAZMCLXPILHSE6PGYV2FHHUQ5DGQJWRZ4GXT"
export NETWORK="stellar-testnet"

# EVM (Base)
export EVM_PRIVATE_KEY="0x4c0883a69102937d6231471b5dbb6204fe512961708279f23efb3c0c90..."
export NETWORK="base-sepolia"

# Both (FULL mode)
export STELLAR_SECRET="S..."
export EVM_PRIVATE_KEY="0x..."
export NETWORK="stellar"  # default network when both are available

"Create a new wallet on stellar-testnet"

{
  "stellarSecret": "SCZANGBA5YHTNYVVV3C7CAZMCLXPILHSE6PGYV2FHHUQ5DGQJWRZ4GXT",
  "evmPrivateKey": "0x4c0883a69102937d6231471b5dbb6204fe512961708279f23efb3c0c90...",
  "network": "stellar-testnet",
  "createdAt": "2026-01-15T10:30:00.000Z"
}

# Using stellar-sdk in Node.js
node -e "const { Keypair } = require('@stellar/stellar-sdk'); const kp = Keypair.random(); console.log('Secret:', kp.secret()); console.log('Public:', kp.publicKey())"

# Using viem in Node.js
node -e "const { generatePrivateKey, privateKeyToAccount } = require('viem/accounts'); const pk = generatePrivateKey(); const acc = privateKeyToAccount(pk); console.log('Private Key:', pk); console.log('Address:', acc.address)"

# Or using openssl
openssl rand -hex 32 | sed 's/^/0x/'

Agent calls use_skill("my-skill", "/api/generate")
  │
  ├─ 1. Resolve skill → parse SKILL.md manifest
  ├─ 2. Validate manifest (schema, required fields)
  ├─ 3. Check budget limits (per-call & daily)
  ├─ 4. Select compatible network (skill networks ∩ wallet networks)
  ├─ 5. Create PaymentClient for that network
  ├─ 6. client.fetch(url) → x402 auto-payment:
  │     a. First request returns 402 Payment Required
  │     b. Client signs USDC payment (on-chain)
  │     c. Retries request with payment proof header
  │     d. Server verifies payment, returns response
  ├─ 7. Record spending (amount, skill, endpoint, network)
  └─ 8. Return response to agent

Endpoint returned 500. Payment was sent but the request failed.

{"error": "Internal server error"}

{
  "mcpServers": {
    "402md": {
      "command": "npx",
      "args": ["-y", "@402md/mcp"],
      "env": {
        "STELLAR_SECRET": "SCZANGBA5YHTNYVVV3C7CAZMCLXPILHSE6PGYV2FHHUQ5DGQJWRZ4GXT",
        "NETWORK": "stellar-testnet",
        "MAX_PER_CALL": "0.10",
        "MAX_PER_DAY": "5.00"
      }
    }
  }
}

{
  "mcpServers": {
    "402md": {
      "command": "npx",
      "args": ["-y", "@402md/mcp"],
      "env": {
        "EVM_PRIVATE_KEY": "0x4c0883a69102937d623147...",
        "NETWORK": "base-sepolia",
        "MAX_PER_CALL": "0.10",
        "MAX_PER_DAY": "5.00"
      }
    }
  }
}

{
  "mcpServers": {
    "402md": {
      "command": "npx",
      "args": ["-y", "@402md/mcp"],
      "env": {
        "STELLAR_SECRET": "S...",
        "EVM_PRIVATE_KEY": "0x...",
        "NETWORK": "stellar",
        "MAX_PER_CALL": "1.00",
        "MAX_PER_DAY": "50.00"
      }
    }
  }
}

{
  "mcpServers": {
    "402md": {
      "command": "npx",
      "args": ["-y", "@402md/mcp"]
    }
  }
}

{
  "stellarSecret": "S...",
  "evmPrivateKey": "0x...",
  "network": "stellar-testnet",
  "createdAt": "2026-01-15T10:30:00.000Z"
}

{
  "spentToday": "1.2500",
  "spentSession": "0.3000",
  "limits": {
    "maxPerCall": "1.00",
    "maxPerDay": "50.00"
  },
  "recentPayments": [
    {
      "skillName": "image-gen",
      "endpoint": "/api/generate",
      "amount": "0.15",
      "network": "stellar-testnet",
      "timestamp": "2026-01-15T14:30:00.000Z"
    }
  ]
}

# By marketplace name
use_skill({ skill: "image-gen", body: '{"prompt": "a sunset"}' })

# By URL
use_skill({ skill: "https://example.com/SKILL.md", endpoint: "/api/v2/generate" })

# By local file
use_skill({ skill: "./skills/my-skill/SKILL.md", method: "POST", body: '{"input": "hello"}' })

# With custom headers
use_skill({ skill: "translate", headers: { "X-Target-Lang": "pt-BR" }, body: '{"text": "hello"}' })

{
  "address": "GCXZ...",
  "balance": "45.250000 USDC",
  "network": "stellar-testnet",
  "mode": "STELLAR_ONLY"
}

{
  "type": "stellar",
  "publicKey": "GCXZ...",
  "network": "stellar-testnet",
  "savedTo": "/Users/you/.402md/wallet.json",
  "note": "Fund this address on the Stellar testnet faucet before use."
}

┌──────────────────────────────────────────────────────┐
│  AI Agent (Claude, etc.)                             │
│  Calls MCP tools: use_skill, check_balance, etc.     │
└──────────────┬───────────────────────────────────────┘
               │ stdio (MCP protocol)
┌──────────────▼───────────────────────────────────────┐
│  @402md/mcp Server                                   │
│                                                      │
│  ┌─────────────┐  ┌────────────┐  ┌───────────────┐ │
│  │ Use Tools   │  │ Wallet     │  │ Registry      │ │
│  │ use_skill   │  │ check_bal  │  │ search_skills │ │
│  │ read_skill  │  │ spending   │  │               │ │
│  │             │  │ create_wal │  │               │ │
│  └──────┬──────┘  └─────┬──────┘  └───────┬───────┘ │
│         │               │                 │          │
│  ┌──────▼──────┐  ┌─────▼──────┐  ┌───────▼───────┐ │
│  │ resolveSkill│  │ Spending   │  │ fetch()       │ │
│  │ validateSkil│  │ Tracker    │  │ → Registry API│ │
│  │ selectNetwrk│  │ (budget)   │  │               │ │
│  └──────┬──────┘  └────────────┘  └───────────────┘ │
│         │                                            │
│  ┌──────▼──────────────────────────────────────────┐ │
│  │ ClientCache → PaymentClient (@402md/x402)       │ │
│  │   ├─ StellarClient (@stellar/stellar-sdk)       │ │
│  │   └─ EvmClient (viem)                           │ │
│  └──────┬──────────────────────────────────────────┘ │
└─────────┼────────────────────────────────────────────┘
          │ x402 payment protocol
┌─────────▼────────────────────────────────────────────┐
│  Skill Provider (HTTP server)                        │
│  Returns 402 → receives payment proof → returns data │
└──────────────────────────────────────────────────────┘

User: "Search for image generation skills"
→ Agent calls search_skills({ query: "image generation" })
→ Returns list of skills with pricing

User: "Create a wallet so we can use one"
→ Agent calls create_wallet({ network: "stellar-testnet" })
→ Returns public key + "fund on testnet faucet"

User: "Use the image-gen skill to create a sunset"
→ Agent calls use_skill({ skill: "image-gen", body: '{"prompt":"a sunset over mountains"}' })
→ Server resolves skill → validates → checks budget → pays → returns image URL

User: "How much have we spent?"
→ Agent calls spending_summary()
→ Returns { spentToday: "0.0500", spentSession: "0.0500", limits: { maxPerCall: "0.10", maxPerDay: "20.00" }, ... }

User: "Test my local skill"
→ Agent calls read_skill({ skill: "./my-skill/SKILL.md" })
→ Returns parsed manifest with validation errors/warnings

→ Agent calls use_skill({ skill: "./my-skill/SKILL.md", endpoint: "/api/test" })
→ Executes against your local server

→ Agent calls use_skill for a skill priced at 5.00 USDC
→ MAX_PER_CALL is 0.10
→ Error: "Exceeds per-call limit (0.10 USDC)"
→ No payment is made

git clone https://github.com/402md/mcp.git
cd mcp
npm install

mcp/
├── src/
│   ├── index.ts          # CLI entry point (stdio transport)
│   ├── server.ts         # MCP server setup, tool registration
│   ├── config.ts         # Env vars + wallet file → McpConfig
│   ├── types.ts          # McpConfig, SpendingRecord, WalletFileConfig
│   ├── clients.ts        # ClientCache + network selection logic
│   ├── resolve.ts        # Skill resolution (URL / file / registry)
│   ├── spending.ts       # SpendingTracker (budget enforcement)
│   ├── wallet-store.ts   # Read/write ~/.402md/wallet.json
│   └── tools/
│       ├── use.ts        # use_skill, read_skill
│       ├── wallet.ts     # check_balance, spending_summary, create_wallet
│       └── registry.ts   # search_skills
├── __tests__/
│   ├── config.test.ts
│   ├── spending.test.ts
│   ├── resolve.test.ts
│   └── wallet-store.test.ts
├── tsup.config.ts        # Build config (ESM, shebang, sourcemaps)
├── tsconfig.json
├── eslint.config.mjs
└── .prettierrc

# Build and run
npm run build
node dist/index.js

# Or in dev mode (rebuilds on change)
npm run dev

# In another terminal, test with MCP inspector
npx @modelcontextprotocol/inspector node dist/index.js

STELLAR_SECRET="S..." NETWORK="stellar-testnet" node dist/index.js