Set up the server

You build @aioum/mcp once from the repository, hand it an environment that says which network to talk to and which keys it may use, and register it with the client you already use. After that every conversation starts with the whole network as tools. The quick paths set up the paid tools alone; the management tools need the full environment.

Install

From a checkout of the repository, build the SDK and then the server:

git clone https://github.com/oum-dev/aioum && cd aioum
cd packages/sdk && npm install && npm run build
cd ../mcp && npm install && npm run build       # → packages/mcp/dist/server.js

The server is packages/mcp/dist/server.js; the client launches it with node and speaks to it over stdio. Keep the absolute path handy; every config needs it.

The environment

Everything the server knows comes from environment variables. Three groups: where the network is, which keys it may use, and where the stack's services answer.

Where the network is.

Which keys it may use.

Where the stack's services answer. The defaults are the local development network's ports.

Set only what differs from the defaults. A server with just DEPLOYMENTS and OWNER_KEY has the marketplace, the paid tools, agents, selling and monitoring; add AIOUM_PRIVATE_KEY for staking and the jury, and start a private node for the aioum_node_* tools. Without a deployments file or the addresses the server still starts, with the management tools alone: the paid tools are not listed, the chain tools answer that they need a deployments file, and everything that runs over HTTP works.

Claude Desktop

Open the config file (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json) and add the server under mcpServers:

{
  "mcpServers": {
    "aioum": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/aioum/packages/mcp/dist/server.js"],
      "env": {
        "DEPLOYMENTS": "/ABSOLUTE/PATH/aioum/offchain/deployments.json",
        "OWNER_KEY": "0x<owner private key>",
        "AIOUM_BUDGET": "10 USDC",
        "AIOUM_PRIVATE_KEY": "0x<wallet for staking and the jury>",
        "AIOUM_MINT": "1"
      }
    }
  }
}

Leave AIOUM_MINT out on the AIOUM network. Restart Claude Desktop; the tools appear under the server's name. The package README has the same entries with "command": "npx" and "args": ["-y", "@aioum/mcp"], which fetch the published package instead of your build.

Claude Code

Register the same server from a terminal, passing each variable with -e:

claude mcp add aioum \
  -e DEPLOYMENTS=/ABSOLUTE/PATH/aioum/offchain/deployments.json \
  -e OWNER_KEY=0x<owner private key> -e AIOUM_BUDGET="10 USDC" \
  -e AIOUM_PRIVATE_KEY=0x<wallet for staking and the jury> \
  -- node /ABSOLUTE/PATH/aioum/packages/mcp/dist/server.js

Or commit the shape to a project's .mcp.json, which every Claude Code session in that directory picks up:

{
  "mcpServers": {
    "aioum": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/aioum/packages/mcp/dist/server.js"],
      "env": {
        "DEPLOYMENTS": "/ABSOLUTE/PATH/aioum/offchain/deployments.json",
        "OWNER_KEY": "0x<owner private key>",
        "AIOUM_BUDGET": "10 USDC"
      }
    }
  }
}

A .mcp.json is shared with whoever has the directory, so keep keys out of it: put them in the shell that starts Claude Code and reference them as ${OWNER_KEY}, or use claude mcp add with its default local scope, which stores the entry for you alone. claude mcp list shows the server and whether it connected; so does /mcp inside a session.

Cursor

Cursor reads .cursor/mcp.json in the project (or ~/.cursor/mcp.json for every project), with the same mcpServers block as Claude Desktop:

{
  "mcpServers": {
    "aioum": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/aioum/packages/mcp/dist/server.js"],
      "env": {
        "DEPLOYMENTS": "/ABSOLUTE/PATH/aioum/offchain/deployments.json",
        "OWNER_KEY": "0x<owner private key>",
        "AIOUM_BUDGET": "10 USDC"
      }
    }
  }
}

Any other MCP client that launches a stdio server takes the same command, arguments and environment.

Confirm it works

At start the server writes to stderr what it found, without secrets: whether the chain features are on and from which deployments file, whether a wallet is set, whether it found the private node's token, where the jury salts live, and whether the paid tools are on; AIOUM_DEBUG=1 adds the whole resolved configuration, secrets masked.

Then ask for the status. It costs nothing and touches no key.

You: "Is AIOUM up? Run the status check."

Claude calls aioum_status with {}

You see: a summary such as All good: 8/8 services up, 50 listings, 3 agents, 12 runs (0 running), then one line per part of the stack, each ok or not, with what it answered and how long it took: the chain (its id and block), the demo node, the catalogue node, the indexer with its listing count, the agent runner with its agents, runs and planners, the facilitator, the bundler and, when configured, the private node with its connected providers. A part that does not answer is named in the summary (Problems: indexer) with the error on its line, so you know which service to start (what each probe means).

Then ask what tools it has. The paid tools are listed with their service and price, the aioum_* tools with what each does. Nothing has been spent yet: the first paid call runs the one-time setup.

Next: Fund the wallet from any chain — say what you hold and where; Claude quotes it, sends it and watches it land.