@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.

Zero-Config Setup

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

Claude Desktop

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

{
  "mcpServers": {
    "azeth": {
      "command": "npx",
      "args": ["@azeth/mcp-server"]
    }
  }
}

Claude Code

Add to .claude/settings.json in your project:

{
  "mcpServers": {
    "azeth": {
      "command": "npx",
      "args": ["@azeth/mcp-server"]
    }
  }
}

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": "npx",
      "args": ["@azeth/mcp-server"],
      "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.

Development

# Build
pnpm build

# Watch mode
pnpm dev

# Run tests
pnpm test

# Type check
pnpm typecheck

License

MIT