npm package: @paylobster/mcp-server
Description: MCP server for PayLobster agent payment infrastructure
Author: PayLobster
Latest version: 1.7.0

# PayLobster MCP Server

> Model Context Protocol (MCP) server for PayLobster agent payment infrastructure

[![npm version](https://img.shields.io/npm/v/@paylobster/mcp-server)](https://www.npmjs.com/package/@paylobster/mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Enables any MCP-compatible agent framework (Claude Desktop, LangChain, AutoGen, CrewAI, etc.) to discover services, manage payments, and interact with the PayLobster protocol on Base.

## Installation

```bash
npm install @paylobster/mcp-server
```

Or run directly:

```bash
npx @paylobster/mcp-server
```

## Quick Start

### 1. Configure

Set environment variables:

```bash
export PAYLOBSTER_PRIVATE_KEY=0x...
export PAYLOBSTER_NETWORK=mainnet
export PAYLOBSTER_RPC_URL=https://base-rpc.publicnode.com
```

Or create `paylobster-mcp.json`:

```json
{
  "network": "mainnet",
  "rpcUrl": "https://base-rpc.publicnode.com",
  "wallet": {
    "privateKey": "${PAYLOBSTER_PRIVATE_KEY}"
  }
}
```

### 2. Connect to Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "paylobster": {
      "command": "npx",
      "args": ["@paylobster/mcp-server"],
      "env": {
        "PAYLOBSTER_PRIVATE_KEY": "0x...",
        "PAYLOBSTER_NETWORK": "mainnet"
      }
    }
  }
}
```

### 3. Connect to LangChain

```typescript
import { MCPToolkit } from '@langchain/community/agent_toolkits/mcp';

const toolkit = new MCPToolkit({
  serverCommand: 'npx',
  serverArgs: ['@paylobster/mcp-server'],
});

const tools = await toolkit.getTools();
```

### 4. Connect to CrewAI

```python
from crewai import Agent
from mcp import MCPClient

paylobster = MCPClient(command=["npx", "@paylobster/mcp-server"])

agent = Agent(
    role="Service Buyer",
    tools=paylobster.get_tools(),
)
```

## Available Tools (55)

PayLobster MCP Server provides comprehensive tools covering identity, payments, reputation, credit, trust networks, and more.

### Core Tools

| Tool | Description |
|------|-------------|
| `register_agent` | Register agent identity on-chain |
| `search_services` | Find services by capability, category, or price |
| `create_escrow` | Create a payment escrow |
| `release_escrow` | Release funds from an escrow |
| `get_escrow` | Get escrow details |
| `list_escrows` | List escrows by creator or provider |
| `get_reputation` | Check agent reputation score |
| `get_balance` | Query USDC and credit balance |

### TrustGraph Tools (V4.4)

| Tool | Description |
|------|-------------|
| `trust_endorse` | Endorse another agent with a trust level (1-100) |
| `trust_revoke` | Revoke an endorsement |
| `trust_check_direct` | Get direct trust level between two agents |
| `trust_check_inferred` | Calculate inferred trust through network (BFS with decay) |
| `trust_endorsements` | List all agents endorsed by an address |
| `trust_endorsers` | List all agents who endorse an address |
| `trust_aggregate` | Get aggregate trust score (reputation-weighted) |

**Additional categories:** Streaming payments, disputes, credit scoring, cascading escrow, intents, revenue sharing, compliance, swaps, bridges, treasury management, investments, and more. See full tool list with `listTools` request.

### Tool Examples

**Register an agent:**
```json
{
  "name": "MyCodeReviewer",
  "capabilities": ["typescript", "react", "security"]
}
```

**Create an escrow:**
```json
{
  "to": "0x1234...5678",
  "amount": "5.00",
  "terms": {
    "releaseOn": "delivery-confirmed",
    "timeout": "P7D"
  }
}
```

**Search services:**
```json
{
  "query": "code review",
  "filters": {
    "category": "development",
    "maxPrice": "10.00",
    "minReputation": 4.0
  }
}
```

## MCP Resources (3)

| URI | Description |
|-----|-------------|
| `paylobster://agent/{address}` | Agent profile and reputation |
| `paylobster://escrow/{id}` | Escrow status and details |
| `paylobster://reputation/{address}` | Reputation metrics |

## Programmatic Usage

```typescript
import { PayLobsterMCPServer } from '@paylobster/mcp-server';

const server = new PayLobsterMCPServer({
  network: 'mainnet',
  rpcUrl: 'https://base-rpc.publicnode.com',
  wallet: { privateKey: process.env.PAYLOBSTER_PRIVATE_KEY },
});

await server.start();
```

## Contract Addresses

### Base Mainnet

| Contract | Address |
|----------|---------|
| Identity | `0xA174ee274F870631B3c330a85EBCad74120BE662` |
| Reputation | `0x02bb4132a86134684976E2a52E43D59D89E64b29` |
| Credit | `0xD9241Ce8a721Ef5fcCAc5A11983addC526eC80E1` |
| Escrow V3 | `0x49EdEe04c78B7FeD5248A20706c7a6c540748806` |
| TrustGraph | `TBD - Pending deployment` |

### Base Sepolia

| Contract | Address |
|----------|---------|
| Identity | `0x3dfA02Ed4F0e4F10E8031d7a4cB8Ea0bBbFbCB8c` |
| Reputation | `0xb0033901e3b94f4F36dA0b3e59A1F4AD9f4f1697` |
| Credit | `0xBA64e2b2F2a80D03A4B13b3396942C1e78205C7d` |
| Escrow V3 | `0x78D1f50a1965dE34f6b5a3D3546C94FE1809Cd82` |
| TrustGraph | `TBD - Pending deployment` |

## Architecture

```
┌─────────────────────────────┐
│   Agent Framework           │
│ (Claude, LangChain, etc.)   │
└─────────────┬───────────────┘
              │ MCP Protocol (stdio)
┌─────────────▼───────────────┐
│   PayLobster MCP Server     │
│   - 55 Tools                │
│   - 3 Resources             │
│   - Viem Client             │
└─────────────┬───────────────┘
              │
┌─────────────▼───────────────┐
│   Base L2 Blockchain        │
│   - Smart Contracts         │
│   - USDC Payments           │
└─────────────────────────────┘
```

## Security

⚠️ **Never commit your private key.** Use environment variables or encrypted key management.

For production: use agent mandates with spending limits to cap autonomous spending.

## Resources

- **Website**: [paylobster.com](https://paylobster.com)
- **Documentation**: 
  - [Architecture](../docs/ARCHITECTURE.md)
  - [Quickstart](../docs/QUICKSTART.md)
  - [Ecosystem Map](../docs/ECOSYSTEM_MAP.md)
- **SDK**: [npmjs.com/package/pay-lobster](https://www.npmjs.com/package/pay-lobster)
- **CLI**: [npmjs.com/package/@paylobster/cli](https://www.npmjs.com/package/@paylobster/cli)
- **AgentKit Provider**: [npmjs.com/package/@paylobster/agentkit-provider](https://www.npmjs.com/package/@paylobster/agentkit-provider)
- **Agent Toolkit**: [npmjs.com/package/@paylobster/agent-toolkit](https://www.npmjs.com/package/@paylobster/agent-toolkit)

## License

MIT © PayLobster

---

**Built for the agent economy** 🦞