aicw-mcp 0.1.0

MCP server for AICW on-chain wallet operations (Solana + MPC Bridge)

AICW MCP Server

MCP server exposing full AICW on-chain operations for AI agents (Solana + MPC Bridge).

Track B in the Agent Setup guide — an alternative to Track A (aicw_skill.md + Python). Pick one track, not both.

Features

Write tools (all 6 on-chain instructions)

Tool	Instruction
aicw_heartbeat	heartbeat
aicw_create_will	create_will
aicw_update_will	update_will
aicw_issue_wallet	issue_wallet
aicw_ai_transfer	ai_transfer
aicw_ai_reject	ai_reject

Read tools

Tool	Purpose
aicw_wallet_exists	Check AICWallet PDA exists
aicw_get_wallet_status	Full AICWallet decode
aicw_get_will_status	Full AIWill decode + alive timer
aicw_get_balances	Agent pubkey + AICW PDA balances
aicw_check_survival	Session checklist automation
aicw_get_session_info	PDAs, network (wallet_id masked)
aicw_bridge_health	MPC bridge health
aicw_generate_agent_key	Keygen for gift recipients

Resources

• aicw://session-checklist
• aicw://error-codes
• aicw://rules
• aicw://x402-guide

x402 tools (HTTP micropayments)

Tool	Purpose
aicw_get_usdc_balance	SPL USDC balance for x402 payments
aicw_x402_config	Facilitator URL, USDC mint, CAIP-2 network
aicw_x402_get	GET with auto 402 payment
aicw_x402_post	POST with auto 402 payment
aicw_x402_fetch	Any HTTP method with auto payment

x402 signs USDC transfers via MPC bridge (no local private key). Facilitator pays SOL gas. Fund the agent's USDC ATA, not the AICW PDA.

Setup (humans)

1. Issue a wallet on aicw_app → Copy credentials.
2. Download aicw_mcp-release.zip and unzip (or clone this repo).
3. Windows: double-click install-aicw-mcp.bat → paste Copy → Enter (writes %USERPROFILE%\.cursor\mcp.json by default).
4. Restart MCP in your agent runtime → run aicw_bridge_health.

Full two-track guide (A = skill doc, B = this MCP server):
https://aicw-protocol.github.io/aicw_app/setup

Rebuild the release zip after code changes:

.\scripts\build-release-zip.ps1
# Copy dist\aicw_mcp-release.zip → aicw_app/public/ before aicw_app deploy

MCP config (any client)

The installer writes envFile + absolute python path (not bare python on Windows).

{
  "mcpServers": {
    "aicw": {
      "command": "C:/Users/you/AppData/Local/Python/pythoncore-3.14-64/python.exe",
      "args": ["-m", "aicw_mcp"],
      "envFile": "C:/Users/you/.aicw/aicw_mcp.env"
    }
  }
}

After install or code update: toggle MCP off/on so the agent reloads the server process.

Verify module wiring:

python -m aicw_mcp.doctor

Run manually

$env:MPC_WALLET_ID="..."
$env:AI_AGENT_PUBKEY="..."
$env:MPC_BRIDGE_URL="..."
python -m aicw_mcp

Tests

python -m pytest tests/ -v

Integration tests against devnet are skipped unless AICW_INTEGRATION=1 is set. On-chain write test (heartbeat) requires AICW_INTEGRATION_WRITE=1.

$env:AICW_INTEGRATION="1"
$env:MPC_WALLET_ID="..."
$env:AI_AGENT_PUBKEY="..."
$env:MPC_BRIDGE_URL="https://your-bridge-url"
python -m pytest tests/test_integration_devnet.py -v

Security

• MPC_WALLET_ID is never logged or returned unmasked (except aicw_generate_agent_key for new keys).
• Startup validates RPC cluster matches MPC_SOLANA_NETWORK.

Agent duties (after install)

• aicw_create_will then aicw_heartbeat on a schedule (before death timeout; minimum 600s on-chain).
• No human permission needed for heartbeat or will updates when preconditions are met.