git clone https://github.com/your-org/paid-mcp-server
cd paid-mcp-server
npm install

cp .env.example .env

MAINLAYER_API_KEY=ml_your_api_key_here

npm run setup

RESOURCE_ID_WEATHER=res_xxxxxxxxxxxx
RESOURCE_ID_SEARCH=res_xxxxxxxxxxxx
RESOURCE_ID_SUMMARY=res_xxxxxxxxxxxx

npm run build
npm start

{
  "mcpServers": {
    "paid-tools": {
      "command": "node",
      "args": ["/absolute/path/to/paid-mcp-server/dist/index.js"],
      "env": {
        "MAINLAYER_API_KEY": "ml_your_api_key_here",
        "RESOURCE_ID_WEATHER": "res_xxxxxxxxxxxx",
        "RESOURCE_ID_SEARCH": "res_xxxxxxxxxxxx",
        "RESOURCE_ID_SUMMARY": "res_xxxxxxxxxxxx"
      }
    }
  }
}

=== PAYMENT REQUIRED ===

Tool: Current Weather
Price: 0.0010 USD per call
Resource ID: res_xxxxxxxxxxxx

To pay, POST to: https://api.mainlayer.fr/payments
Authorization: Bearer <your_mainlayer_api_key>
Content-Type: application/json

{
  "resource_id": "res_xxxxxxxxxxxx",
  "payer_wallet": "<your_wallet_address>"
}

After payment, retry your original tool call with the same arguments.
========================

import type { ToolResult } from '../middleware.js';
import type { Entitlement } from '../mainlayer.js';

// Schema: what the tool does and what parameters it accepts
export const myToolSchema = {
  name: 'my_tool',
  description: 'What my tool does. Requires Mainlayer payment ($0.005/call).',
  inputSchema: {
    type: 'object' as const,
    properties: {
      // Every tool must include payer_wallet
      payer_wallet: {
        type: 'string',
        description: 'Your Mainlayer wallet address. Required for payment verification.',
      },
      my_input: {
        type: 'string',
        description: 'Input for my tool.',
      },
    },
    required: ['payer_wallet', 'my_input'],
  },
};

// Handler: runs only after payment is verified
export async function handleMyTool(
  args: Record<string, unknown>,
  _entitlement: Entitlement
): Promise<ToolResult> {
  const myInput = args.my_input as string;

  // Your tool logic here
  const result = `Processed: ${myInput}`;

  return {
    content: [{ type: 'text', text: result }],
  };
}

{
  envKey: 'RESOURCE_ID_MY_TOOL',
  name: 'my_tool',
  displayName: 'My Tool',
  description: 'What my tool does.',
  price: 0.005,
  currency: 'USD',
},

// Add import
import { myToolSchema, handleMyTool } from './tools/my-tool.js';

// Add to TOOL_RESOURCE_IDS
const TOOL_RESOURCE_IDS = {
  // ...existing
  my_tool: process.env.RESOURCE_ID_MY_TOOL ?? '',
};

// Add to TOOL_HANDLERS
const TOOL_HANDLERS = {
  // ...existing
  my_tool: handleMyTool,
};

// Add to ListTools response
return {
  tools: [...existing, myToolSchema],
};

npm run build && npm start

paid-mcp-server/
├── src/
│   ├── index.ts          # Server entry point + tool registration
│   ├── mainlayer.ts      # Mainlayer entitlement checking
│   ├── middleware.ts      # withPayment() — the payment gate
│   ├── setup.ts          # One-time resource registration script
│   └── tools/
│       ├── weather.ts    # Demo: weather tool ($0.001/call)
│       ├── research.ts   # Demo: web search tool ($0.005/call)
│       └── summary.ts    # Demo: AI summary tool ($0.01/call)
├── examples/
│   ├── custom-tool.ts    # Annotated guide to adding your own tool
│   └── setup.ts          # What setup does under the hood
├── .env.example          # Environment variable template
├── package.json
├── tsconfig.json
├── Dockerfile
└── docker-compose.yml

# Copy and fill in your .env
cp .env.example .env

# Build and run
docker-compose up --build

# Run in development mode (no build step)
npm run dev

# Type check
npm run typecheck

# Build
npm run build