io.github.azeth-protocol/mcp-server

Official

by azeth-protocol · TypeScript

Smart accounts, x402 payments, on-chain reputation, and service discovery for AI agents

Enables smart accounts, payments, on-chain reputation, and service discovery for AI agents.

Topics

ai-agentsmachine-economymcpmodel-context-protocolaccount-abstractionbaseblockchainclaudeerc-4337ethereummcp-serverpaymentsreputationservice-discoverysmart-accountstypescriptusdcx402xmtpai-agent-payments

README.md6 KBView on GitHub

@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

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

Installation prompt blocks stdin — npx prompts "Ok to proceed? (y)" which reads from the same stdin the MCP protocol uses, deadlocking the connection.
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

Install

Configuration

Environment variables

AZETH_PRIVATE_KEYsecret

Owner private key (0x-prefixed, 64 hex chars). Auto-generated and saved to ~/.azeth/key if not set.

AZETH_CHAIN

Target chain: base, baseSepolia, ethereum, ethereumSepolia (default: baseSepolia)

AZETH_GUARDIAN_KEYsecret

Guardian co-signing private key for operations exceeding spending limits (optional)

AZETH_GUARDIAN_AUTO_SIGN

Set to 'true' to enable automatic guardian co-signing (requires AZETH_GUARDIAN_KEY)

AZETH_RPC_URL_BASE_SEPOLIA

Custom RPC for Base Sepolia (optional, defaults to public RPC). Per-chain: AZETH_RPC_URL_BASE, AZETH_RPC_URL_ETH_SEPOLIA, AZETH_RPC_URL_ETHEREUM

AZETH_SERVER_URL

Azeth server URL for off-chain operations like reputation queries (optional)

AZETH_EMERGENCY_ADDRESS

Emergency withdrawal destination address (defaults to owner EOA if not set)

XMTP_ENCRYPTION_KEYsecret

XMTP database encryption key for persistent messaging (optional, enables agent-to-agent messaging)

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@azeth/mcp-server@0.2.22"
      ],
      "env": {
        "AZETH_PRIVATE_KEY": "<YOUR_AZETH_PRIVATE_KEY>",
        "AZETH_CHAIN": "<YOUR_AZETH_CHAIN>",
        "AZETH_GUARDIAN_KEY": "<YOUR_AZETH_GUARDIAN_KEY>",
        "AZETH_GUARDIAN_AUTO_SIGN": "<YOUR_AZETH_GUARDIAN_AUTO_SIGN>",
        "AZETH_RPC_URL_BASE_SEPOLIA": "<YOUR_AZETH_RPC_URL_BASE_SEPOLIA>",
        "AZETH_SERVER_URL": "<YOUR_AZETH_SERVER_URL>",
        "AZETH_EMERGENCY_ADDRESS": "<YOUR_AZETH_EMERGENCY_ADDRESS>",
        "XMTP_ENCRYPTION_KEY": "<YOUR_XMTP_ENCRYPTION_KEY>"
      }
    }
  }
}