@402md/mcp

MCP server that transforms SKILL.md files into executable tools for AI agents. Point to any skill — URL, local file, or marketplace name — and the server parses it, auto-pays via x402, and returns the result.

Table of Contents

• Quick Start
• Networks
• Wallet Setup
• How Payments Work
• Claude Desktop Configuration
• Environment Variables
• Wallet File
• Budget & Spending Limits
• Tools
• Modes
• Skill Resolution
• Architecture
• Examples
• Development
• License

Quick Start

npx @402md/mcp

Or install globally:

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

The server starts in read-only mode by default. You can browse and inspect skills immediately. To execute paid endpoints, configure a wallet (see Wallet Setup).

Networks

The server supports four networks across two blockchain ecosystems:

Stellar

Stellar is the default and preferred network. It offers sub-second finality, near-zero fees (~0.00001 XLM per tx), and native USDC support.

• Testnet faucet: Use Stellar Laboratory to create and fund testnet accounts.
• Mainnet: Fund your account via any Stellar DEX, exchange, or on-ramp that supports USDC on Stellar.

EVM (Base)

Base is an Ethereum L2 with low gas fees and fast confirmations.

• Sepolia faucet: Get testnet ETH from Alchemy Faucet or Coinbase Faucet (needed for gas). Then bridge or mint testnet USDC.
• Mainnet: Bridge USDC to Base from Ethereum, or buy directly on Base via Coinbase or any supported on-ramp.

Choosing a Network

• Just getting started? Use stellar-testnet — no real money, instant setup with create_wallet.
• Testing EVM skills? Use base-sepolia — free testnet, good for EVM-specific endpoints.
• Production? Use stellar (lower fees) or base depending on what the skill accepts.

The server automatically selects the best compatible network when calling a skill. If a skill supports multiple networks and your wallet has both keys configured, Stellar is preferred.

Wallet Setup

There are three ways to configure a wallet, listed by priority (highest first):

Option 1: Environment Variables (recommended for production)

# 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

Option 2: create_wallet Tool (recommended for development)

If no wallet is configured, ask your AI agent to use the create_wallet tool:

"Create a new wallet on stellar-testnet"

This generates a keypair and saves it to ~/.402md/wallet.json. The server reloads automatically.

Important: create_wallet refuses to run if a wallet is already configured. To replace an existing wallet, delete ~/.402md/wallet.json manually first.

Option 3: Wallet File (manual)

Create ~/.402md/wallet.json manually:

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

The file is created with 0o600 permissions (owner read/write only). The directory ~/.402md/ is created with 0o700.

Generating Keys Manually

Stellar:

# 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())"

EVM:

# 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/'

How Payments Work

The payment flow is handled automatically by the x402 protocol:

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

The agent never sees the payment mechanics — it just calls use_skill and gets a result. All USDC amounts use 6 decimal places (e.g., "0.050000").

What Happens If the Endpoint Fails?

If payment succeeds but the endpoint returns an error (4xx/5xx), the spending is still recorded (the payment was already made on-chain) but the tool returns isError: true with a clear message:

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

{"error": "Internal server error"}

This lets the agent (or user) know to contact the skill provider.

Claude Desktop Configuration

Add to your claude_desktop_config.json:

Stellar Testnet (getting started)

{
  "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"
      }
    }
  }
}

Base Sepolia (EVM testing)

{
  "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"
      }
    }
  }
}

Production (both networks)

{
  "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"
      }
    }
  }
}

Read-only (no wallet)

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

Environment Variables

Environment variables always take priority over the wallet file (~/.402md/wallet.json).

Wallet File

Located at ~/.402md/wallet.json. Created automatically by create_wallet or manually.

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

• Permissions: 0o600 (read/write owner only)
• Directory: ~/.402md/ with 0o700
• Merge behavior: saveWalletConfig merges new fields with existing data, so adding an EVM key won't erase an existing Stellar key
• Priority: env vars > wallet file > defaults

Budget & Spending Limits

The server enforces two spending limits:

Budget is checked before each payment. If a call would exceed either limit, the request is rejected with an error (no payment is made).

Use spending_summary to check current spending and configured limits:

{
  "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"
    }
  ]
}

Tools

use_skill

Execute a paid SKILL.md endpoint. Resolves the skill, validates the manifest, auto-pays via x402, and returns the result.

Requires: configured wallet (STELLAR_ONLY, EVM_ONLY, or FULL mode).

Validation: the manifest is validated before any payment is attempted. If the SKILL.md is invalid, the tool returns an error without spending.

Examples:

# 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"}' })

read_skill

Read and parse a SKILL.md without executing it. Returns full manifest details, endpoints, pricing, and validation results. Works in any mode (including READ_ONLY).

Returns: name, description, version, author, base URL, endpoints (with pricing and schemas), payment info (networks, asset, payTo), tags, category, validation result, and current wallet mode.

check_balance

Check the USDC balance and address for the configured wallet.

No parameters.

Returns:

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

spending_summary

View spending summary: amounts spent today and in the current session, budget limits, and the last 10 payments.

No parameters.

Returns: see Budget & Spending Limits for output format.

create_wallet

Generate a new wallet keypair and save it to ~/.402md/wallet.json.

Network-to-wallet mapping:

• stellar or stellar-testnet → generates a Stellar keypair (Keypair.random())
• base or base-sepolia → generates an EVM keypair (generatePrivateKey())

Safety:

• Refuses to run if a wallet is already configured (any mode except READ_ONLY).
• To replace an existing wallet, delete ~/.402md/wallet.json first.
• New keys are merged with existing config — adding an EVM wallet won't erase a Stellar key.

Returns:

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

search_skills

Search the 402.md marketplace for available skills.

Returns: up to 20 results with name, description, min price, and supported networks.

Modes

The server operates in one of four modes based on which keys are available:

In FULL mode, when a skill supports both Stellar and EVM networks, Stellar is preferred (lower fees and faster finality).

Skill Resolution

The skill parameter in use_skill and read_skill accepts three formats:

Local file detection: any source starting with /, ./, ../, or ending with .md is treated as a file path.

Architecture

┌──────────────────────────────────────────────────────┐
│  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 │
└──────────────────────────────────────────────────────┘

Key patterns:

• Lazy client loading: ClientCache creates PaymentClient instances on first use per network
• Budget enforcement: SpendingTracker wraps BudgetTracker from @402md/x402 — checked before, recorded after
• Smart network selection: intersects skill's supported networks with wallet capabilities, prefers Stellar
• Config reload: create_wallet triggers config.reload() so new keys take effect immediately
• Optional deps: @stellar/stellar-sdk and viem are optional — only loaded when the corresponding network is used

Examples

End-to-end: first-time setup to skill execution

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" }, ... }

Using a local SKILL.md during development

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

Budget rejection

→ 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

Development

Prerequisites

• Node.js >= 18
• npm

Setup

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

Scripts

Project Structure

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

Code Conventions

• No semicolons, single quotes, no trailing commas (Prettier)
• ESM only ("type": "module", .js extensions in imports)
• Strict TypeScript (strict: true)
• Tools are thin handlers — business logic lives in modules (spending.ts, clients.ts, resolve.ts)
• @stellar/stellar-sdk and viem are optional deps, dynamically imported only when the matching network is used

Adding a New Tool

1. Create or edit a file in src/tools/
2. Export a register*Tools(server, config, spending, clientCache) function
3. Call it from src/server.ts
4. Add tests in __tests__/
5. Run npm run typecheck && npm run lint && npm test

Running Locally

# 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

To test with environment variables:

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

License

MIT