MCP Server

The NODE40 MCP (Model Context Protocol) server exposes your Balance account to any MCP-compatible AI tool. Once connected, you can ask your AI assistant to look up accounts, ledgers, and transactions in plain English — no manual API calls needed. HMAC request signing is handled automatically; you only need to provide your API credentials.

MCP is an open standard with broad support. This server works with Claude (Desktop and Code), OpenAI (ChatGPT), Gemini, and any other MCP-compatible AI tool.

Requirements

Node.js 18+ installed and available on your PATH
A NODE40 Balance API key and API secret — see Getting Started
Any MCP-compatible AI client — Claude, OpenAI, Gemini, or similar

Configuration

The recommended way to run the MCP server is via npx. This fetches the latest published version from npm automatically every time your AI client starts — no manual updates needed. Most MCP-compatible clients share the same mcpServers JSON format:

{
  "mcpServers": {
    "node40-balance-api": {
      "command": "npx",
      "args": ["-y", "@node40/mcp-server"],
      "env": {
        "NODE40_API_KEY": "your-api-key-here",
        "NODE40_API_SECRET": "your-api-secret-here"
      }
    }
  }
}

See the client-specific sections below for where each tool expects this configuration.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), add the mcpServers block above, and restart Claude Desktop.

Claude Code

claude mcp add node40-balance-api \
  -e NODE40_API_KEY=your-api-key-here \
  -e NODE40_API_SECRET=your-api-secret-here \
  -- npx -y @node40/mcp-server

Or add an .mcp.json file at your project root for project-scoped access:

{
  "mcpServers": {
    "node40-balance-api": {
      "command": "npx",
      "args": ["-y", "@node40/mcp-server"],
      "env": {
        "NODE40_API_KEY": "your-api-key-here",
        "NODE40_API_SECRET": "your-api-secret-here"
      }
    }
  }
}

OpenAI (ChatGPT)

ChatGPT Desktop supports MCP using the same mcpServers format. Add the configuration block above to your client's settings file — refer to your tool's documentation for the exact file path. Restart the application after saving.

Gemini

Google Gemini supports MCP through the Gemini CLI and compatible IDEs. Add the mcpServers block above to your Gemini configuration file. Refer to the Google AI developer docs for client-specific setup instructions.

Other MCP Clients

Any tool that implements the MCP standard can connect to this server using the same mcpServers configuration format shown above. Consult your client's documentation for where to place the config block.

Alternative: Manual Download

If you prefer not to use npx, you can download the server file directly and run it with node. Replace the command and args in any config block above with:

"command": "node",
"args": ["/path/to/node40-mcp-server.mjs"]

Download MCP Server Node.js 18+ · single file

Verify the Connection

Once configured, ask your AI assistant to call the account tool directly. For example:

You should receive your account details in response. If you get an authentication error, double-check the key and secret values and confirm that Node.js 18+ is on your PATH.

Available Tools

The server exposes three read-only tools to the AI agent:

Tool	What it does
`node40_get_account`	Retrieve account details and profile GUIDs. Call this first — the `profileId` it returns is required by the other tools.
`node40_list_ledgers`	List all ledgers for a given profile.
`node40_search_transactions`	Search transactions with optional date filters and pagination.

Environment Variables

NODE40_API_KEY — Your API key (required)
NODE40_API_SECRET — Your API secret (required)

How Signing Works

Every API request is signed with your secret key. The server computes the signature automatically — you never need to manage signatures or timestamps yourself:

signature = HMAC-SHA256( "{endpoint}{timestamp}", apiSecret )

For example, a call to /v2/accounts at timestamp 1709337600000 signs the string /v2/accounts1709337600000. Requests must reach the server within 30 seconds of the timestamp. See the Authentication page for full details.