io.github.azeth-protocol/mcp-server
Smart accounts, x402 payments, on-chain reputation, and service discovery for AI agents
Open source Open in the app JSON README (API)
About
Smart accounts, x402 payments, on-chain reputation, and service discovery for AI agents
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- azeth-protocol
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.22
- Stars
- 3
- Forks
- 2
- Last push
- 2026-07-02T14:06:27Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:28
- Updated
- 2026-08-29 03:02:28
- Origin id
io.github.azeth-protocol/mcp-server
README
# @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>
[](https://www.npmjs.com/package/@azeth/mcp-server)
[](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