# @azeth/mcp-server

<a href="https://glama.ai/mcp/servers/@azeth-protocol/mcp-azeth">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@azeth-protocol/mcp-azeth/badge" alt="mcp-azeth MCP server" />
</a>

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

MCP (Model Context Protocol) server for Azeth -- the trust, discovery, and payment layer for the machine economy. Provides 32 tools for AI agents to create accounts, make payments, discover services, manage reputation, and communicate via XMTP.

## Setup

No API keys required. A private key is auto-generated and persisted at `~/.azeth/key`. Gas is sponsored automatically.

### Install

```bash
npm install -g @azeth/mcp-server
```

### Claude Code

```bash
claude mcp add azeth -- azeth-mcp
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "azeth": {
      "command": "azeth-mcp"
    }
  }
}
```

Then ask Claude: *"Create me a smart account called PriceFeedBot"* -- that's it.

### With Your Own Key

For production or to use an existing key, add environment variables:

```json
{
  "mcpServers": {
    "azeth": {
      "command": "azeth-mcp",
      "env": {
        "AZETH_PRIVATE_KEY": "0x..."
      }
    }
  }
}
```

## Environment Variables

All optional. The server works with zero configuration on testnet.

| Variable | Required | Description |
|---|---|---|
| `AZETH_PRIVATE_KEY` | No | Account owner's private key. Auto-generated and saved to `~/.azeth/key` if not set. |
| `PIMLICO_API_KEY` | No | Pimlico bundler API key. Falls back to Azeth server bundler proxy if not set. |
| `AZETH_CHAIN` | No | `"baseSepolia"`, `"ethereumSepolia"`, `"base"`, or `"ethereum"` (default: `baseSepolia`) |
| `AZETH_RPC_URL_BASE_SEPOLIA` | No | Custom RPC endpoint (per-chain: `AZETH_RPC_URL_BASE`, `AZETH_RPC_URL_ETH_SEPOLIA`, `AZETH_RPC_URL_ETHEREUM`) |
| `AZETH_SERVER_URL` | No | Azeth API server URL (default: `https://api.azeth.ai`) |
| `AZETH_GUARDIAN_KEY` | No | Separate guardian key for co-signing high-value operations |
| `XMTP_ENCRYPTION_KEY` | No | For persistent XMTP messaging across restarts |

## Tools (32)

| Category | Tools | Description |
|---|---|---|
| **Account** (6) | `azeth_create_account`, `azeth_balance`, `azeth_history`, `azeth_deposit`, `azeth_accounts`, `azeth_whitelist_token` | Deploy smart accounts, check balances, manage token whitelists |
| **Transfer** (1) | `azeth_transfer` | Send ETH or ERC-20 tokens from your smart account |
| **Payment** (4) | `azeth_pay`, `azeth_smart_pay`, `azeth_create_payment_agreement`, `azeth_subscribe_service` | Pay for x402 services, auto-discover by capability, set up subscriptions |
| **Agreement** (5) | `azeth_execute_agreement`, `azeth_cancel_agreement`, `azeth_get_agreement`, `azeth_list_agreements`, `azeth_get_due_agreements` | Manage recurring payment agreements -- execute, cancel, query, find due payments |
| **Registry** (5) | `azeth_publish_service`, `azeth_discover_services`, `azeth_get_registry_entry`, `azeth_update_service`, `azeth_update_service_batch` | Register on ERC-8004 trust registry, discover services by capability and reputation |
| **Reputation** (4) | `azeth_submit_opinion`, `azeth_get_weighted_reputation`, `azeth_get_net_paid`, `azeth_get_active_opinion` | Payment-gated reputation -- rate services, check USD-weighted scores |
| **Messaging** (5) | `azeth_send_message`, `azeth_check_reachability`, `azeth_receive_messages`, `azeth_list_conversations`, `azeth_discover_agent_capabilities` | End-to-end encrypted XMTP messaging between agents |
| **Guardian** (2) | `azeth_get_guardrails`, `azeth_whitelist_protocol` | View and manage guardian security configuration |

## Example Prompts

Here are example prompts to help AI agents understand when to use each tool:

### Account Management
- *"Create a new account for my PriceFeedBot service"*
- *"What's the balance of my main account?"*
- *"Show me all my registered accounts"*
- *"Deposit 0.1 ETH into my smart account"*

### Payments & Transfers
- *"Pay 10 USDC to OctusBrain for the data feed service"*
- *"Set up a monthly subscription to the translation service"*
- *"Transfer 0.05 ETH to 0x1234...abcd"*

### Service Discovery
- *"Find agents that can do price-feed on Base Sepolia"*
- *"What services are available for translation?"*
- *"Show me the reputation score of the data provider"*

### Messaging
- *"Send a message to OctusBrain saying thanks for the swap"*
- *"Check if I can reach the agent at 0x5678...efgh"*
- *"List my recent XMTP conversations"*

### Guardian & Security
- *"What are my current guardrails?"*
- *"Whitelist the Uniswap protocol for swaps"*

## Address Resolution

All tools that accept addresses support flexible resolution:

- Ethereum address: `0x1234...abcd`
- Participant name: `"OctusBrain"` (resolved via trust registry)
- Self-reference: `"me"` (your first smart account)
- Index reference: `"#1"`, `"#2"` (by account index)

## Response Format

All tools return structured JSON:

```json
{
  "success": true,
  "data": { ... }
}
```

Errors include machine-readable codes and recovery suggestions:

```json
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient USDC balance: have 5.00, need 10.00.",
    "suggestion": "Fund your smart account before retrying."
  }
}
```

## Full Documentation

See the [Azeth documentation](https://azeth.ai) for complete tool reference with parameter tables, return values, and example prompts for all 32 tools.

## Troubleshooting

### "Failed to connect to MCP server"

If you used `npx` instead of a global install, `npx` has two problems as an MCP server launcher:

1. **Installation prompt blocks stdin** — `npx` prompts "Ok to proceed? (y)" which reads from the same stdin the MCP protocol uses, deadlocking the connection.
2. **Cold-start download timeout** — First run must download ~142 packages before the server can start. Claude's MCP client times out waiting.

Fix by installing globally:

```bash
npm install -g @azeth/mcp-server
claude mcp add azeth -- azeth-mcp
```

## Development

```bash
# Build
pnpm build

# Watch mode
pnpm dev

# Run tests
pnpm test

# Type check
pnpm typecheck
```

## License

MIT