io.github.azeth-protocol/mcp-server

@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