MCP Server

FluxA ships a local MCP server, @fluxa-pay/fluxa-wallet-mcp. It runs on your machine over stdio and exposes FluxA Wallet actions as MCP tools to clients such as Claude Code, Claude Desktop, Cursor and other MCP-compatible agents.

Prefer Skill + CLI when you can

The MCP server covers a subset of FluxA: Agent ID, mandates, x402 payments, payouts and payment links (13 tools). Refunds, received payments, agent cards, AgentMarket, Agent VC and scheduled tasks are available only through the fluxa-agent-wallet skill and the FluxA Wallet CLI. If your agent can run shell commands, use those instead. Use MCP when your client supports MCP tools but not shell commands.

Local only

The server runs locally over stdio. FluxA doesn't currently offer a hosted (remote) MCP endpoint.

Requirements

• Node.js 18 or newer
• A FluxA Wallet account to approve the agent

Claude Code

Option 1: CLI (recommended)

claude mcp add-json fluxa-ai-wallet-mcp '{
  "command": "npx",
  "args": ["-y", "@fluxa-pay/fluxa-wallet-mcp@latest"],
  "env": {
    "AGENT_NAME": "Claude Code - your-machine",
    "CLIENT_INFO": "Claude Code on macOS"
  }
}'

Option 2: Edit ~/.claude.json

{
  "mcpServers": {
    "fluxa-ai-wallet-mcp": {
      "command": "npx",
      "args": ["-y", "@fluxa-pay/fluxa-wallet-mcp@latest"],
      "env": {
        "AGENT_NAME": "Claude Code - your-machine",
        "CLIENT_INFO": "Claude Code on macOS"
      }
    }
  }
}

If you already have a mcpServers block, add the fluxa-ai-wallet-mcp entry to it rather than replacing the whole block. Restart Claude Code afterwards.

Other MCP clients

Any client that launches stdio MCP servers can use the same entry: command npx, args ["-y", "@fluxa-pay/fluxa-wallet-mcp@latest"], plus the environment variables below. For Claude Desktop, add it under mcpServers in claude_desktop_config.json. For Cursor, add it to ~/.cursor/mcp.json.

Environment variables

Variable	Purpose
AGENT_NAME	A readable name for this agent, shown in the FluxA Wallet (for example Claude Code - John's MacBook). Used when the agent registers with init_agent_id
CLIENT_INFO	Where the agent runs (for example Claude Code on macOS 14). Used at registration
AGENT_ID, AGENT_TOKEN, AGENT_JWT	Use an existing Agent ID instead of registering a new one. Set all three. These take priority over the saved config
FLUXA_DATA_DIR	Where credentials are stored (default ~/.fluxa-ai-wallet-mcp). The server and the CLI share this directory, so an agent registered with one is also registered with the other

Treat AGENT_TOKEN and AGENT_JWT as secrets. Keep them out of shared config files and repositories.

First run

1. The agent calls get_agent_status. If configured is false, it calls init_agent_id (with {} when AGENT_NAME and CLIENT_INFO are set).
2. When the agent first needs to spend, it calls create_intent_mandate and gives you an authorizationUrl. Opening it lets you approve the agent for your wallet (the first time) and sign the budget.
3. Within that budget, the agent pays x402 APIs with request_x402_v3_payment and doesn't need to ask again.

See MCP Tools for every tool and its parameters.

Check that it's working

• In Claude Code, run /mcp. fluxa-ai-wallet-mcp should be listed as connected, with its tools.

• Ask the agent to call get_agent_status.
• After a payment, check Transactions in the FluxA Wallet, and the agent's spend under AI Agents.

If the tools don't appear:

• check that the config JSON is valid and saved,
• restart the client after editing its config, and
• run npx -y @fluxa-pay/fluxa-wallet-mcp@latest in a terminal to confirm Node.js can fetch and start the package.

Versions

The npm latest tag may lag behind the source repository, so check the installed version with npm view @fluxa-pay/fluxa-wallet-mcp version. The tools documented on MCP Tools are the current set.