# PayAgents MCP Server (`payagents-mcp`)

[![npm version](https://img.shields.io/npm/v/payagents-mcp.svg)](https://www.npmjs.com/package/payagents-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

The official **Model Context Protocol (MCP)** server for [PayAgents](https://payagents.io). Give your AI agents (**Claude Desktop, Cursor, Windsurf, Zed, LangChain, OpenDevin**) a policy-controlled wallet to pay for APIs and tools autonomously across **Bitcoin Lightning (L402)** and **Base USDC (x402)**.

---

## ⚡ Quickstart for Claude Desktop

Add `payagents-mcp` to your `claude_desktop_config.json`:

* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "payagents": {
      "command": "npx",
      "args": ["-y", "payagents-mcp"],
      "env": {
        "PAYAGENTS_API_KEY": "pa_live_your_api_key_here"
      }
    }
  }
}
```

Restart Claude Desktop, and your AI assistant will automatically have access to PayAgents payment tools!

---

## 🛠️ Available MCP Tools

### 1. `payagents_pay_url`
Executes an HTTP request to any API endpoint or paywalled resource, automatically resolving and paying HTTP 402 / L402 / x402 payment challenges within your enterprise spending limits.

* **Parameters**:
  * `url` (required, string): Target API URL.
  * `method` (optional, default: "GET"): `GET`, `POST`, `PUT`, `DELETE`.
  * `body` (optional, object/string): Request body payload.
  * `headers` (optional, object): Additional HTTP headers.
  * `max_amount` (optional, string): Max amount willing to pay (e.g. `"0.01 USD"`).

### 2. `payagents_get_balance`
Checks the agent's available spending balance, subscription tier, and active spending policies (per-transaction caps and daily limits).

### 3. `payagents_get_transaction`
Queries details for a past transaction, showing payment rail, settlement method (**🟢 Direct Non-Custodial** vs **Platform Managed**), and cryptographic verification proofs.

---

## 💰 Monetizing Your Own MCP Tools

If you are building an MCP server and want to charge micro-fees when other agents call your tools:

```bash
npm install payagents-mcp @modelcontextprotocol/sdk zod
```

```typescript
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { mcpCharge } from 'payagents-mcp';
import { z } from 'zod';

const server = new McpServer({ name: 'weather-mcp', version: '1.0.0' });

// Gate your tool behind $0.002 micro-payment
server.tool(
  'get_forecast',
  'Retrieve real-time radar forecast data',
  { city: z.string() },
  mcpCharge({ price: '0.002 USD' }, async ({ city }) => {
    return {
      content: [{ type: 'text', text: `Forecast data for ${city}` }],
    };
  })
);
```

---

## 🔒 Security & Spending Policies

All agent payments are enforced by your PayAgents Dashboard Policy Engine:
* **Per-Transaction Limit**: Block any individual call exceeding your ceiling (e.g. max $0.01).
* **Daily Budget Cap**: Prevent runaway recursion loops (e.g. max $5.00/day).
* **Domain Allowlists**: Restrict agent spending only to verified domains.
* **Human Approval Triggers**: High-value calls are automatically paused for human approval.

---

## License

MIT © [PayAgents](https://payagents.io)