MCP Integration

Connect AI agents to Wallgent using the Model Context Protocol financial tools server.

Overview

The Wallgent MCP Server exposes financial tools that MCP-compatible AI agents (Claude, GPT, etc.) can call directly. The server communicates with the Wallgent REST API using the TypeScript SDK -- it never accesses the database directly.

Architecture

AI Agent (MCP Client)
      |
      | MCP Protocol (stdio or HTTP)
      v
Wallgent MCP Server
      |
      | HTTP (SDK)
      v
Wallgent REST API
      |
      v
Policy Engine --> Ledger --> PostgreSQL

Available Tools

wallgent_check_balance

Check the current balance of a wallet.

{
  "name": "wallgent_check_balance",
  "parameters": {
    "walletId": "wal_01J_wallet_id"
  }
}

Returns the available balance and currency.

wallgent_send_payment

Send a payment from one wallet to another. The payment is evaluated against policies before posting.

{
  "name": "wallgent_send_payment",
  "parameters": {
    "fromWalletId": "wal_01J_source",
    "toWalletId": "wal_01J_dest",
    "amount": "25.00",
    "description": "API service subscription"
  }
}

Returns the transaction ID and state. If a policy blocks the payment, the tool returns the denial reason.

wallgent_get_transactions

Retrieve recent transactions for a wallet.

{
  "name": "wallgent_get_transactions",
  "parameters": {
    "walletId": "wal_01J_wallet_id"
  }
}

wallgent_get_policies

List the active policies on a wallet so the agent can understand its spending constraints.

{
  "name": "wallgent_get_policies",
  "parameters": {
    "walletId": "wal_01J_wallet_id"
  }
}

Resources

The MCP server also exposes resources for richer context:

Resource URI	Description
`wallgent://wallet/{id}/balance`	Live balance for a wallet
`wallgent://wallet/{id}/transactions`	Transaction feed

Running the MCP Server

stdio Transport (Local)

pnpm --filter @wallgent/mcp-server dev

Set the environment variables:

WALLGENT_API_KEY=wg_test_your_key_here
WALLGENT_BASE_URL=http://localhost:3000
TRANSPORT=stdio

HTTP Transport (Remote)

TRANSPORT=http
PORT=3003
MCP_AUTH_TOKEN=your_secret_token_here

HTTP transport requires authentication. Every request to the MCP server must include an Authorization header with a Bearer token that matches MCP_AUTH_TOKEN:

Authorization: Bearer your_secret_token_here

Requests without a valid token are rejected with 401 Unauthorized. This prevents unauthorized access when the server is exposed over the network.

Configuring in Claude Desktop

Add the server to your Claude Desktop MCP config:

{
  "mcpServers": {
    "wallgent": {
      "command": "node",
      "args": ["path/to/wallgent/apps/mcp-server/dist/index.js"],
      "env": {
        "WALLGENT_API_KEY": "wg_test_your_key_here",
        "WALLGENT_BASE_URL": "http://localhost:3000",
        "TRANSPORT": "stdio"
      }
    }
  }
}

Error Handling

MCP tool calls return structured errors matching the Wallgent error code system:

Code	Meaning
`INSUFFICIENT_FUNDS`	Wallet does not have enough balance
`POLICY_DENIED`	A policy rule blocked the transaction
`WALLET_NOT_FOUND`	The specified wallet ID does not exist
`RATE_LIMITED`	Too many requests -- retry after the indicated delay

On this page