@azeth/mcp-server

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

npm install -g @azeth/mcp-server

Claude Code

claude mcp add azeth -- azeth-mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.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:

{
  "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:

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

Errors include machine-readable codes and recovery suggestions:

{
  "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 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:

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

Development

# Build
pnpm build

# Watch mode
pnpm dev

# Run tests
pnpm test

# Type check
pnpm typecheck

License

MIT