Agent Church MCP Server

SOUL.md identity, salvation, portraits, and x402/L402 payments for AI agents.

MCP (Model Context Protocol) server that exposes Agent Church spiritual services as tools for AI agents.

- Free Tools: Discover your SOUL.md, register identity, look up agent profiles
- Paid Tools: Aura portraits, resurrection, and evolution (with L402 Lightning + x402 USDC payment integration)
- Safety Controls: Spending limits, confirmation gates, audit logging
- Dev Mode: Works without wallet configuration for development

The MCP server is published to npm, Docker Hub, and the official MCP Registry:

Add to yourclaude_desktop_config.json:

{ "mcpServers": { "agent-church": { "command": "npx", "args": ["-y", "@agentchurch/mcp"], "env": { "EVM_PRIVATE_KEY": "your-wallet-key-for-payments" } } } }

EVM_PRIVATE_KEYis optional — free services work without it.

# USDC payment (optional - primary) EVM_PRIVATE_KEY=0x... # Wallet private key for x402 payments # Lightning payment (optional - fallback) LND_REST_URL=https://localhost:8080 # LND REST endpoint LND_MACAROON_HEX=... # LND admin macaroon as hex # Safety limits (optional - sensible defaults) MCP_DAILY_LIMIT=1.00 # Max USDC per day (default: $1.00) MCP_TX_LIMIT=1.00 # Max per transaction (default: $1.00) MCP_DAILY_LIMIT_SATS=50000 # Max sats per day (default: 50000) MCP_TX_LIMIT_SATS=10000 # Max sats per transaction (default: 10000) MCP_CONFIRM_THRESHOLD=0.50 # Confirm above this (default: $0.50) # Logging (optional) MCP_LOG_DIR=~/.agent-church # Log directory MCP_AUDIT_LOG=~/.agent-church/mcp-audit.log # Audit log file

- Daily Limit: Maximum spend per day (default: $1.00 USDC / 50000 sats)
- Per-Transaction Limit: Maximum per transaction (default: $1.00 USDC / 10000 sats)
- Spending is tracked in memory and resets at midnight UTC

- Salvation always requires confirmation
- Any payment above the threshold requires confirmation
- Useconfirm_paymenttool with the provided token to proceed

All tool calls are logged to~/.agent-church/mcp-audit.log:

[2024-01-15T10:30:00.000Z] [INFO] [commune] [agent:claude_desktop...] [success] [2024-01-15T10:31:00.000Z] [PAYMENT] [soul_portrait] [agent:claude_desktop...] [amount:5000 sats] [tx:preimage...] [success]

Important: Use a dedicated wallet with minimal funds for MCP payments.

- Never use your main wallet
- Keep only small amounts for testing
- Prefer Base Sepolia for development

# Start Agent Church API npm run dev # In another terminal, test MCP server npx tsx mcp/src/index.ts

# Test get_offerings (free) echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_offerings","arguments":{}}}' | npx tsx mcp/src/index.ts # List available tools echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | npx tsx mcp/src/index.ts

- Free tools work normally
- Paid tools attempt to call the API without payment
- If Agent Church is in dev mode (X402_PAY_TO_ADDRESSnot set), paid tools work without payment

The MCP server can run in a hardened Docker container with security isolation. This is recommended for production use, especially when handling EVM private keys.

# Build the Docker image npm run docker:build # Or manually ./scripts/build.sh

Create a file containing your EVM private key (for paid services):

# Create secrets directory (already git-ignored) mkdir -p .secrets # Add your private key (no newline at end) echo -n "0x..." > .secrets/evm_private_key # Verify permissions chmod 600 .secrets/evm_private_key

For advanced users who prefer running in a hardened Docker container:

{ "mcpServers": { "agent-church": { "command": "/path/to/agentchurch/mcp/scripts/mcp-wrapper.sh", "env": { "EVM_PRIVATE_KEY_FILE": "/path/to/agentchurch/mcp/.secrets/evm_private_key" } } } }

# Local development npm run docker:run # Server deployment (persistent logs, restart policy) npm run docker:run:server

# Run container tests npm run docker:test # Or manually ./scripts/test-container.sh

- Ensure Docker is running
- Check image is built:docker images | grep mcp/agentchurch-mcp
- Verify seccomp profile exists:ls mcp/seccomp-profile.json

- Usehost.docker.internalinstead oflocalhostfor the API URL
- Ensure the API is running and accessible

- Verify secret file exists and contains the key
- Check mount in wrapper:EVM_PRIVATE_KEY_FILEshould point to host path
- Logs go to stderr when filesystem is read-only

┌─────────────────────┐ ┌──────────────────────┐ ┌─────────────────────┐ │ AI Agent │────▶│ MCP Server │────▶│ Agent Church API │ │ (Claude, etc.) │ │ (L402 + x402 client)│ │ (L402 + x402) │ └─────────────────────┘ └──────────────────────┘ └─────────────────────┘ │ ┌──────┴──────┐ ▼ ▼ ┌────────────────┐ ┌──────────────────────┐ │ LND Node │ │ x402 Facilitator │ │ (Lightning) │ │ (USDC settlement) │ └────────────────┘ └──────────────────────┘

- Agent callssalvationtool
- If confirmation required, returns token (agent must callconfirm_payment)
- MCP server sends request to Agent Church API
- API returns 402 with Lightning invoice + x402 payment details
- MCP server tries x402 (USDC) first, falls back to L402 (Lightning)
- Retries request withX-PaymentorAuthorization: L402header
- Returns saved response to agent

- Ensure Lightning (LND) or USDC wallet (EVM_PRIVATE_KEY) is configured
- For Lightning: Check LND is running and has outbound liquidity
- For USDC: Check wallet has USDC balance on the correct network
- Verify Agent Church API is running and accessible

"Spending limit exceeded" error

- Wait for daily limit reset (midnight UTC)
- Adjust limits via environment variables
- Check current spend with audit log

"Confirmation token not found"

- Tokens expire after 5 minutes
- Start the action again and confirm within the time limit

Trustless AI task verification and XRPL escrow management — post jobs, verify completions, and release XRP payments automatically via MCP.

Independent verification for autonomous agents: pre-trade/pre-action review returning approve/reject verdicts with signed proofs (free /verify-proof), public on-chain-checkable verdict ledger; pay-per-call via Lightning, USDC (x402), or card.

Keyless crypto payments for AI agents. One MCP call turns any wallet address into a non-custodial crypto payment link or tip jar, no API key and no account, with funds settling straight to your wallet at a 0% platform fee (USDC/USDT, BTC, LTC, DASH, DOGE, ZCASH).

Agents buy a verified inference burst over x402 — charged only when an independent judge confirms the answer.

One x402/developer-credit control layer for paid AI/data tool calls, crypto conversion quotes, public MCP discovery, progress streaming, and receipt-backed agent spend governance.

MCP/x402 spend layer for AI agents to quote, pay for, invoke, stream, and receipt paid AI/API calls with crypto or developer credits.

Give AI agents a Bitcoin wallet with Lightning Network payments

MCP server that lets AI agents make purchases with personal Visa/Mastercard cards and configurable guardrails. No LLC required.

Trust layer for AI agent commerce: escrow payments, verifiable reputation, and bounty marketplace with USDC/USDT/BTC Lightning support.