Which integrations are available for this server?

Provides support for EVM-compatible networks such as Base to facilitate automated USDC payments and secure transaction signing for accessing paid AI tool endpoints. Enables automated USDC payments and wallet management on the Stellar network, allowing AI agents to discover, pay for, and execute external skills through the x402 protocol.

How do I use @402md/mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@@402md/mcp run the image generation skill from the 402.md marketplace" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

@402md/mcp

by 402md

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

@402md/mcp

npm version License: MIT Node.js TypeScript 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.

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

Network	ID	Use Case	USDC Contract
Stellar Mainnet	`stellar`	Production payments with real USDC	Native Stellar USDC (Centre)
Stellar Testnet	`stellar-testnet`	Development & testing with free testnet USDC	Testnet USDC

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)

Network	ID	Use Case	USDC Contract
Base Mainnet	`base`	Production payments on Base L2	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
Base Sepolia	`base-sepolia`	Development & testing on Base testnet	Sepolia USDC

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

Variable	Default	Description
`STELLAR_SECRET`	—	Stellar secret key (starts with `S`). Enables Stellar payments.
`EVM_PRIVATE_KEY`	—	EVM private key (hex, starts with `0x`). Enables Base payments.
`NETWORK`	`stellar`	Default network: `stellar`, `stellar-testnet`, `base`, `base-sepolia`
`MAX_PER_CALL`	`0.10`	Maximum USDC allowed per individual skill call
`MAX_PER_DAY`	`20.00`	Maximum USDC allowed per calendar day
`REGISTRY_URL`	`https://api.402.md`	402.md marketplace API base URL

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:

Limit	Default	Env Variable	Description
Per-call	`0.10 USDC`	`MAX_PER_CALL`	Maximum for a single skill invocation
Per-day	`20.00 USDC`	`MAX_PER_DAY`	Maximum total across all calls in a calendar day

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.

Parameter	Type	Required	Description
`skill`	`string`	Yes	Skill source: URL, local file path, or marketplace name
`endpoint`	`string`	No	Endpoint path (defaults to first endpoint in manifest)
`method`	`string`	No	HTTP method: `GET`, `POST`, `PUT`, `DELETE`, `PATCH` (defaults to spec)
`body`	`string`	No	Request body as JSON string
`headers`	`object`	No	Additional request headers

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).

Parameter	Type	Required	Description
`skill`	`string`	Yes	Skill source: URL, local file path, or marketplace name

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.

Parameter	Type	Required	Description
`network`	`string`	Yes	`stellar`, `stellar-testnet`, `base`, or `base-sepolia`

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.

Parameter	Type	Required	Description
`query`	`string`	Yes	Search keywords
`maxPrice`	`string`	No	Max price per call in USDC (e.g., `"0.50"`)
`category`	`string`	No	Filter by category

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:

Mode	Condition	Available Tools
`READ_ONLY`	No keys configured	`read_skill`, `search_skills`, `create_wallet`
`STELLAR_ONLY`	`STELLAR_SECRET` set	All tools — pays via Stellar
`EVM_ONLY`	`EVM_PRIVATE_KEY` set	All tools — pays via Base
`FULL`	Both keys set	All tools — pays via best available network

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:

Format	Example	How It Resolves
URL	`https://example.com/SKILL.md`	Fetches directly via HTTP
Local file	`./skills/my-skill/SKILL.md`	Reads from filesystem
Marketplace name	`image-gen`	Queries `{REGISTRY_URL}/api/v1/discovery/skills/{name}/skill-md`

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

Command	Description
`npm run build`	Build with tsup (ESM, shebang included)
`npm run dev`	Build in watch mode
`npm run typecheck`	Run TypeScript type checking (`tsc --noEmit`)
`npm run lint`	Lint source files with ESLint
`npm run lint:fix`	Lint and auto-fix
`npm run format`	Format with Prettier
`npm run format:check`	Check formatting without writing
`npm test`	Run tests with Vitest
`npm run test:watch`	Run tests in watch mode

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

Create or edit a file in src/tools/
Export a register*Tools(server, config, spending, clientCache) function
Call it from src/server.ts
Add tests in __tests__/
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

Available Tools

6 tools

check_balanceA

Check the USDC balance and address for the configured wallet.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Mentions 'configured wallet' indicating stateful dependency, but lacks disclosure of error behavior (what happens if unconfigured?), safety profile (read-only), or external dependencies.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with zero waste. Front-loaded with action verb and resource. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Appropriately complete for a simple read operation with no output schema. Specifies currency (USDC) and that address is returned alongside balance. Could improve by noting error conditions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters present (baseline 4). Description compensates adequately by explaining the implicit operand ('the configured wallet'), clarifying why no arguments are required.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear specific verb ('Check') and resource ('USDC balance and address'). States scope ('configured wallet'). Distinguishes implicitly from create_wallet but does not explicitly differentiate from spending_summary sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides no explicit when-to-use guidance, prerequisites, or alternatives. While 'configured wallet' implies a dependency on prior wallet creation, it does not state this as a requirement or indicate when to use this versus spending_summary.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_walletA

Generate a new wallet keypair and save it to ~/.402md/wallet.json. Supports Stellar or EVM networks.

ParametersJSON Schema

Name	Required	Description	Default
`network`	Yes	Network for the new wallet

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It successfully discloses the filesystem side effect (saving to ~/.402md/wallet.json) and persistence behavior. However, it omits critical behavioral details: whether it overwrites existing wallets, what data is returned (public key, address), and any security or permission requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with zero waste. The first sentence front-loads the core action and critical side effect (file location). The second sentence clarifies supported network types. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema and destructive filesystem side effects, the description covers the basics (action, location, network options) but leaves gaps regarding return values, idempotency (overwrite behavior), and error conditions. It meets minimum viability but doesn't fully compensate for missing structured metadata.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

While the schema has 100% description coverage (baseline 3), the description adds semantic value by categorizing the enum values into 'Stellar or EVM networks,' helping the agent understand that base/base-sepolia are EVM variants and stellar/stellar-testnet are Stellar variants.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verbs ('Generate', 'save') and identifies the exact resource being created ('wallet keypair'). It clearly distinguishes from siblings like check_balance or use_skill by specifying the creation action and persistence to ~/.402md/wallet.json.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage through the side effect (saving to specific path) and supported networks, but lacks explicit when-to-use guidance or named alternatives. It doesn't clarify, for example, whether to use this before check_balance or if wallets can be imported rather than generated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_skillA

Read and parse a SKILL.md file without executing it. Returns manifest details, endpoints, pricing, and validation.

ParametersJSON Schema

Name	Required	Description	Default
`skill`	Yes	Skill source: URL, local file path, or marketplace name

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully communicates the non-destructive nature ('without executing it') and enumerates the return fields (manifest, endpoints, pricing, validation), but omits auth requirements, error handling behavior, rate limits, or file size constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficiently structured sentence that front-loads the action ('Read and parse') and immediately qualifies the scope ('without executing it'). The second clause enumerates return values. Zero wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (single string parameter, no nested objects) and lack of output schema, the description adequately compensates by listing the specific return fields. It covers the critical safety aspect (non-execution) but could be improved by noting error cases or authentication requirements.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the 'skill' parameter fully documented as accepting 'URL, local file path, or marketplace name'. The description provides no additional parameter semantics, which is appropriate given the schema already comprehensively defines the input format and accepted values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Read and parse') and resource ('SKILL.md file'). Crucially, it distinguishes from the sibling tool 'use_skill' via 'without executing it', establishing this as an inspection/introspection tool rather than an execution tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'without executing it' provides clear contextual guidance that this tool is for inspection purposes only, implicitly contrasting with 'use_skill'. However, it stops short of explicitly naming sibling alternatives or stating explicit 'when to use' conditions (e.g., 'use this to validate before running').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_skillsB

Search the 402.md marketplace for available skills by keyword.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Search query
`maxPrice`	No	Max price per call in USDC (e.g. "0.50"). Filters results.
`category`	No	Filter by category

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. While it identifies the external domain ('402.md marketplace'), it fails to specify return format (list of skills?), pagination behavior, rate limits, or explicitly confirm the read-only nature of the operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of a single, efficient sentence that is front-loaded with the action verb. There is no redundant or wasteful text; every word contributes to defining the tool's function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (3 primitive parameters) and high schema coverage, the description is minimally adequate. However, the absence of an output schema creates a gap—the description should ideally indicate what the search returns (e.g., a list of skill metadata) to be complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, establishing a baseline score of 3. The description adds the context that searching is done 'by keyword', which aligns with the 'query' parameter, but does not elaborate on parameter syntax or interdependencies beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Search'), identifies the exact resource ('402.md marketplace'), and clarifies the method ('by keyword'). This effectively distinguishes it from sibling 'read_skill' (which implies fetching by ID) and establishes the tool's scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool versus alternatives like 'read_skill' or 'use_skill'. It does not indicate that this is a discovery tool to be used before invoking skills, nor does it mention prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

spending_summaryB

View spending summary: amounts spent today/session and recent payment history.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses what data is returned (amounts spent today/session, payment history), but fails to mention safety characteristics (read-only status), rate limits, or the specific format/structure of the returned summary.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Excellent single-sentence structure with zero waste. The colon effectively separates the action from the content details, and every phrase ('today/session', 'recent payment history') adds specific semantic value about the data scope.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Without an output schema, the description partially compensates by listing what data is returned, but lacks structural details (is it a list? aggregated totals? JSON format?). For a parameterless tool, it is minimally viable but could be more explicit about the return value structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema contains zero parameters, which per guidelines establishes a baseline score of 4. The description correctly implies no user input is required by focusing entirely on the output data.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('View') and resource ('spending summary') and clarifies scope with 'today/session' and 'recent payment history'. It implicitly distinguishes from sibling 'check_balance' (current state vs. history), though it doesn't explicitly state this differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance provided on when to use this versus 'check_balance' or other financial tools. The description lacks explicit 'when-to-use' or 'when-not-to-use' instructions, forcing the agent to infer appropriateness from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

use_skillA

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

ParametersJSON Schema

Name	Required	Description
`skill`	Yes	Skill source: URL, local file path, or marketplace name
`endpoint`	No	Endpoint path to call (defaults to first endpoint in manifest)
`method`	No	HTTP method (defaults to endpoint spec method)
`body`	No	Request body as JSON string
`headers`	No	Additional request headers

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries the full burden and discloses the critical payment behavior (auto-pays via x402) and resolution step. However, it omits error handling (what happens with insufficient funds), idempotency guarantees, or side effects beyond payment for a financially-sensitive operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The single sentence is densely packed with zero waste: execution intent, cost model, resolution behavior, payment mechanism, and return value. Information is front-loaded with 'paid' appearing early to signal financial implications.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool involving financial transactions and external API calls, the description covers the basic operation but lacks critical context about prerequisites (wallet creation required), failure modes, or output structure (no output schema exists). The 100% schema coverage mitigates this somewhat, but gaps remain for a mutation tool with side effects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the structured fields adequately document all 5 parameters. The description adds minimal semantic value beyond the schema, though 'SKILL.md endpoint' provides context for the endpoint parameter. Baseline 3 is appropriate when schema coverage is comprehensive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action (Execute), resource type (paid SKILL.md endpoint), and mechanism (auto-pays via x402). The 'paid' qualifier effectively distinguishes this from siblings like read_skill and search_skills, while 'Execute' differentiates it from wallet management tools (check_balance, create_wallet).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context through the word 'paid' (suggesting it requires funds), but provides no explicit when-to-use guidance versus read_skill or prerequisites like requiring a created wallet. It does not mention checking balance first or handling insufficient funds.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

6 tool updatesv0.1.1Mar 29, 2026
- First observedcheck_balance
- First observedcreate_wallet
- First observedread_skill
- First observedsearch_skills
- First observedspending_summary
- First observeduse_skill

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored 2026-04-13 01:55 across 6 tools

Disambiguation5/5

Each tool has a clearly distinct purpose with no overlap: wallet management (check_balance, create_wallet), skill discovery (read_skill, search_skills), and skill execution/payment tracking (use_skill, spending_summary). The descriptions clearly differentiate between checking balances, creating wallets, reading skill metadata, searching for skills, executing skills with payment, and viewing spending summaries.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with snake_case: check_balance, create_wallet, read_skill, search_skills, spending_summary, use_skill. The naming is predictable and readable throughout, with no deviations in style or convention.

Tool Count5/5

Six tools is well-scoped for a wallet and skill marketplace server, covering key operations like wallet setup, balance checking, skill discovery, skill execution, and payment tracking. Each tool earns its place without feeling excessive or insufficient for the domain.

Completeness4/5

The toolset provides strong coverage for core workflows: wallet lifecycle (create/check), skill lifecycle (search/read/use), and payment tracking (spending_summary). A minor gap exists in lacking explicit update or delete operations for wallets or skills, but agents can likely work around this given the server's focus on discovery and execution rather than management.

Resources

Need Help?

Related Servers

Related MCP Connectors

UnifAPIOAuth
com.unifapi
Hosted MCP server for live public-data APIs and Skills for AI agents.
Open Data Search AI & Machine Learning
2
PayGate MCP — Monetization Gateway for AI Agents A
io.github.geoacpfilho
Monetize any MCP server: x402 paywall, pay-per-call billing in USDC on Base, agent marketplace.
Payments & Billing Cryptocurrency Blockchain
61
mcp-serverOAuth
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2
mcprush.com - Catalogue MCP
com.mcprush
Marketplace of MCP servers and agent skills, free and paid, where developers publish and monetise.
Developer Tools AI & Machine Learning
1

@402md/mcp

Table of Contents

Quick Start

Networks

Stellar

EVM (Base)

Choosing a Network

Wallet Setup

Option 1: Environment Variables (recommended for production)

Option 2: create_wallet Tool (recommended for development)

Option 3: Wallet File (manual)

Generating Keys Manually

How Payments Work

What Happens If the Endpoint Fails?

Claude Desktop Configuration

Stellar Testnet (getting started)

Base Sepolia (EVM testing)

Production (both networks)

Read-only (no wallet)

Environment Variables

Wallet File

Budget & Spending Limits

Tools

use_skill

read_skill

check_balance

spending_summary

create_wallet

search_skills

Modes

Skill Resolution

Architecture

Examples

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

Using a local SKILL.md during development

Budget rejection

Development

Prerequisites

Setup

Scripts

Project Structure

Code Conventions

Adding a New Tool

Running Locally

License

Available Tools

TDQS

TDQS

TDQS

TDQS

TDQS

TDQS

Tool Schema Changelog

TDQS

Resources

Related MCP Connectors

Option 2: `create_wallet` Tool (recommended for development)

`use_skill`

`read_skill`

`check_balance`

`spending_summary`

`create_wallet`

`search_skills`