Plaidly MCP Tool Recipes

This page defines tool schemas you can expose to MCP-compatible agents. The runnable reference server lives in plaidly-node/mcp-server and exposes these same tools over stdio.

cd plaidly-node
npm run mcp:server

For a local sandbox API:

cd plaidly-node/mcp-server
PLAIDLY_BASE_URL=http://127.0.0.1:8080 npm start

All examples use testnet as the network so they can be exercised in sandbox runs.

Tool: `register_merchant`

{
  "name": "register_merchant",
  "description": "Register a merchant and return API key credentials",
  "inputSchema": {
    "type": "object",
    "required": ["name"],
    "properties": {
      "name": { "type": "string", "description": "Merchant display name" },
      "webhook_url": { "type": "string", "description": "Optional webhook callback URL" }
    }
  },
  "outputSchema": {
    "type": "object",
    "required": ["id", "name", "api_key", "created_at"],
    "properties": {
      "id": { "type": "string" },
      "name": { "type": "string" },
      "api_key": { "type": "string" },
      "webhook_secret": { "type": "string" }
    }
  }
}

MCP call example

{
  "tool": "register_merchant",
  "input": {
    "name": "Acme Test Co",
    "webhook_url": "https://example.org/webhooks/plaidly"
  }
}

Tool: `create_payment_session`

{
  "name": "create_payment_session",
  "description": "Create a merchant-scoped payment session",
  "inputSchema": {
    "type": "object",
    "required": ["amount", "expires_in", "paymentMethod"],
    "properties": {
      "amount": { "type": "number", "description": "Expected amount to receive" },
      "expires_in": { "type": "string", "description": "Example: 15m, 45m, 1h" },
      "metadata": { "type": "object", "description": "Key-value metadata (max 4KB)" },
      "paymentMethod": {
        "type": "object",
        "required": ["methodID", "chain", "token", "network"],
        "properties": {
          "methodID": { "type": "integer", "enum": [0, 1] },
          "chain": { "type": "string" },
          "token": { "type": "string" },
          "network": { "type": "string", "enum": ["testnet", "mainnet"] }
        }
      }
    }
  },
  "outputSchema": {
    "type": "object",
    "required": ["session_id", "address", "status", "expected_amount", "currency"],
    "properties": {
      "session_id": { "type": "string" },
      "address": { "type": "string" },
      "status": { "type": "string" },
      "expected_amount": { "type": "number" },
      "currency": { "type": "string" },
      "payment_url": { "type": "string" },
      "qr_data": { "type": "string" }
    }
  }
}

MCP call example

{
  "tool": "create_payment_session",
  "input": {
    "amount": 25,
    "expires_in": "45m",
    "paymentMethod": {
      "methodID": 0,
      "chain": "solana",
      "token": "USDC",
      "network": "testnet"
    },
    "metadata": { "order_id": "ord_01HX9K" }
  }
}

Tool: `simulate_payment`

{
  "name": "simulate_payment",
  "description": "Mark a sandbox demo session as paid",
  "inputSchema": {
    "type": "object",
    "required": ["session_id"],
    "properties": {
      "session_id": {
        "type": "string",
        "description": "Target session id, e.g. sess_test_..."
      }
    }
  },
  "outputSchema": {
    "type": "object",
    "required": ["session_id", "status", "received_amount", "expected_amount"],
    "properties": {
      "session_id": { "type": "string" },
      "status": { "type": "string", "example": "completed" },
      "received_amount": { "type": "number" },
      "expected_amount": { "type": "number" }
    }
  }
}

MCP call example

{
  "tool": "simulate_payment",
  "input": {
    "session_id": "sess_test_01HX9K..."
  }
}

Tool: `verify_webhook`

{
  "name": "verify_webhook",
  "description": "Verify webhook signature and decode Plaidly event",
  "inputSchema": {
    "type": "object",
    "required": ["event_header", "signature_header", "payload"],
    "properties": {
      "event_header": { "type": "string" },
      "signature_header": { "type": "string", "description": "Format: t=<unix>,v1=<hex>" },
      "payload": { "type": "string", "description": "Raw JSON webhook body" },
      "secret": { "type": "string", "description": "Webhook signing secret (from merchant profile)" }
    }
  },
  "outputSchema": {
    "type": "object",
    "required": ["ok", "event"],
    "properties": {
      "ok": { "type": "boolean" },
      "event": {
        "type": "object",
        "properties": {
          "event_type": { "type": "string" },
          "session_id": { "type": "string" },
          "status": { "type": "string" },
          "amount": { "type": "number" },
          "currency": { "type": "string" },
          "chain": { "type": "string" },
          "network": { "type": "string", "enum": ["testnet", "mainnet"] },
          "timestamp": { "type": "string" }
        }
      }
    }
  }
}

MCP call example

{
  "tool": "verify_webhook",
  "input": {
    "event_header": "payment_session.completed",
    "signature_header": "t=1718310000,v1=4c2b...",
    "payload": "{\"event_type\":\"payment_session.completed\",\"session_id\":\"sess_test_01HX9K...\",\"status\":\"completed\",\"amount\":25,\"currency\":\"USDC\",\"chain\":\"solana\",\"network\":\"testnet\",\"timestamp\":\"1718310000\"}",
    "secret": "whsec_..."
  }
}

Tool: `pay_x402_resource`

{
  "name": "pay_x402_resource",
  "description": "Handle 402-protected resource access by resolving and returning an x402 payment proof",
  "inputSchema": {
    "type": "object",
    "required": ["url", "method"],
    "properties": {
      "url": { "type": "string", "description": "Protected resource URL" },
      "method": { "type": "string", "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"] },
      "headers": {
        "type": "object",
        "description": "Optional outbound headers",
        "additionalProperties": { "type": "string" }
      },
      "body": {
        "type": "string",
        "description": "Optional JSON body to send with non-GET methods"
      },
      "proof": { "type": "string", "description": "x402 proof payload for retry" },
      "network_hint": { "type": "string", "enum": ["testnet", "mainnet"] }
    }
  },
  "outputSchema": {
    "type": "object",
    "required": ["status", "body"],
    "properties": {
      "status": { "type": "integer" },
      "body": { "type": "string" },
      "x402_challenge": { "type": "object", "description": "Parsed 402 challenge when payment is required" },
      "headers": { "type": "object", "description": "Headers returned by final successful response" }
    }
  }
}

MCP call example

{
  "tool": "pay_x402_resource",
  "input": {
    "url": "https://example.org/agent/protected/invoice",
    "method": "POST",
    "body": "{\"invoice_id\":\"inv_01HX9K...\",\"network\":\"testnet\"}",
    "headers": {
      "content-type": "application/json",
      "accept": "application/json"
    },
    "network_hint": "testnet"
  }
}

Suggested sequencing

register_merchant
create_payment_session
simulate_payment (sandbox-only)
verify_webhook
pay_x402_resource (for protected endpoints)

MCP Server Recipes

Plaidly MCP Tool Recipes

Tool: `register_merchant`

MCP call example

Tool: `create_payment_session`

MCP call example

Tool: `simulate_payment`

MCP call example

Tool: `verify_webhook`

MCP call example

Tool: `pay_x402_resource`

MCP call example

Suggested sequencing

On this page