@aioum/mcp

Mirrored from packages/mcp/README.md in the repository — edit that file, not this page.

An MCP server that exposes AIOUM marketplace services as tools to any MCP client — Claude Desktop, an agent framework, the OpenAI/Anthropic tool loop. When the client calls a tool, this server pays for and invokes the underlying AIOUM service through a budget-capped agent (@aioum/sdk): pay-per-call, no API keys, and the agent can never spend past its budget.

It also serves the management tools (aioum_status, aioum_agents, aioum_stake_delegate, …): everything the app can do, driven from Claude. They follow the same contract as the aioum CLI (the AIOUMControl layer in @aioum/sdk) and read the same AIOUM_* environment. See Management tools.

How it works

• tools/list → discovers the network's services and maps each to an MCP tool (aioum_<id>__<tool>), with price + reputation in the description. No on-chain setup needed to list.
• tools/call → lazily authorizes a budget-capped session key (once), then opens a session, signs a per-call voucher, invokes the tool, and settles on-chain — returning the result plus the amount paid and budget remaining.

Use with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "aioum": {
      "command": "npx",
      "args": ["-y", "@aioum/mcp"],
      "env": {
        "OWNER_KEY": "0x<owner private key>",
        "AIOUM_BUDGET": "10 USDC",
        "DEPLOYMENTS": "/abs/path/to/deployments.json",
        "AIOUM_PRIVATE_KEY": "0x<your wallet key, for staking and the jury>",
        "AIOUM_OWNER": "claude",
        "AIOUM_INDEXER_URL": "http://127.0.0.1:8549",
        "AIOUM_AGENTS_URL": "http://127.0.0.1:8770/runner",
        "AIOUM_MULTINODE_URL": "http://127.0.0.1:8556",
        "AIOUM_PRIVATE_NODE_URL": "http://127.0.0.1:8770"
      }
    }
  }
}

Claude can now call AIOUM services as tools; each call is paid automatically, capped by AIOUM_BUDGET. Every AIOUM_*_URL above is its default, so on a local stack only the keys and DEPLOYMENTS are needed; leave DEPLOYMENTS out and the server still starts, with the management tools that need no chain.

Use with Claude Code

claude mcp add aioum \
  -e OWNER_KEY=0x… -e AIOUM_BUDGET="10 USDC" -e DEPLOYMENTS=/abs/path/to/deployments.json \
  -e AIOUM_PRIVATE_KEY=0x… -e AIOUM_OWNER=claude \
  -- npx -y @aioum/mcp

or, checked into a project as .mcp.json:

{
  "mcpServers": {
    "aioum": {
      "command": "npx",
      "args": ["-y", "@aioum/mcp"],
      "env": { "DEPLOYMENTS": "./offchain/deployments.json", "AIOUM_OWNER": "claude" }
    }
  }
}

(keys go in your shell environment, not the file: OWNER_KEY, AIOUM_PRIVATE_KEY and AIOUM_PRIVATE_NODE_TOKEN are read from the server's environment too.)

Configuration (env)

Session-key expiry

A session key is deliberately short-lived (AIOUM_EXPIRES). Past expiry, every paid call would fail until the owner re-authorizes. This server handles that automatically: before each call it re-authorizes a fresh budget-capped key if the current one is within AIOUM_RENEW_SKEW_SECONDS of expiry, and it retries once if a key lapses mid-flight. Set AIOUM_AUTO_RENEW=0 to opt out and surface expiry as an error (e.g. if a human should re-approve the budget each period).

Management tools

One tool per AIOUMControl method, all prefixed aioum_. Each returns a short summary line and a ```json block with the structured payload; a failure comes back as an MCP error with one readable line. Tools marked signs send a transaction from AIOUM_PRIVATE_KEY; tools marked spends cost money on the runner's or the node's side. The environment each group needs is in the heading (every URL has a local default, listed under Environment).

Monitor (indexer, agent runner, node URLs; AIOUM_DEPLOYMENTS for balances)

Deposits (AIOUM_DEPOSITS_URL; AIOUM_DEPLOYMENTS + AIOUM_PRIVATE_KEY derive the AI wallet, or pass wallet; the key signs a send)

Fund the AI wallet from any chain: whatever is sent to its deposit address, in any asset, arrives here as USDC and is swept to the wallet, less the fee the quote states. amount is in the asset's own units ("0.5" ETH); the token's decimals come from aioum_deposit_tokens (18 when unknown).

Market (AIOUM_INDEXER_URL, AIOUM_AGENTS_URL)

Agents (AIOUM_AGENTS_URL, AIOUM_OWNER)

Projects (AIOUM_AGENTS_URL, AIOUM_OWNER): a brief that outlives one run. One brief, one budget and stages in order; each stage is a run of the same agent that gets the stage's instruction plus what every earlier stage produced, and may spend what is left of the project's budget. Links and workspace paths its tools returned are collected as the stage's artifacts. A failed stage pauses the project; change the stages still to run and resume.

Sell (AIOUM_MULTINODE_URL, AIOUM_NODE_TOKEN when the node's admin API is token-gated)

Stake (AIOUM_DEPLOYMENTS, AIOUM_RPC_URL; AIOUM_PRIVATE_KEY to sign)

Jury (AIOUM_DEPLOYMENTS, AIOUM_RPC_URL; AIOUM_PRIVATE_KEY to sign; salts in ~/.aioum/jury-salts.json)

Private node (AIOUM_PRIVATE_NODE_URL; AIOUM_PRIVATE_NODE_TOKEN or the node's token file)

Amounts are decimal strings ("12000" ZAI, "0.05" USDC); every write returns its tx hash(es). The server never returns a private key or token.

Environment for the management tools

Run locally

npm install && npm run build
OWNER_KEY=0x... AIOUM_BUDGET="5 USDC" DEPLOYMENTS=../../offchain/deployments.json npm start
# or exercise it as a client:
npm run smoke

License

MIT