aicw-mcp

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)

Read tools

Resources

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

x402 tools (HTTP micropayments)

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.