# Mcp Server Sandbox

> A sample implementation of an MCP server that interacts with Nium APIs in the sandbox environment

- **Type:** MCP server
- **Install:** `agentstack add mcp-nium-global-mcp-server-sandbox`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [nium-global](https://agentstack.voostack.com/s/nium-global)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [nium-global](https://github.com/nium-global)
- **Source:** https://github.com/nium-global/mcp-server-sandbox

## Install

```sh
agentstack add mcp-nium-global-mcp-server-sandbox
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Nium MCP Server (Sandbox)

A sample Model Context Protocol (MCP) server implementation that demonstrates integration with key Nium APIs in the sandbox environment for financial services, money transfers, and beneficiary management.

## 📋 Features

### Beneficiary Management

- **List Beneficiaries**: Retrieve existing beneficiaries with search and pagination
- **Create Beneficiaries**: Automatically generate beneficiary data using validation schemas
- **Update Beneficiaries**: Modify existing beneficiary information with comprehensive field support
- **Smart Search**: Find beneficiaries by name or ID with fuzzy matching

### Money Transfers

- **Send Money**: Transfer funds with automatic beneficiary verification and confirmation workflow
- **Smart Confirmation**: Two-step confirmation process for both new and existing beneficiaries
- **Transaction History**: Retrieve wallet transaction history with filtering options

### Validation & Schemas

- **Beneficiary Schemas**: Get validation schemas for different countries, currencies, and payout methods
- **Sample Data Generation**: Automatically generate sample payloads based on API schemas

## 📦 Installation

1. **Clone the repository:**

   ```bash
   git clone git@github.com:nium-global/mcp-server-sandbox.git
   cd mcp-server-sandbox
   ```

2. **Install dependencies:**

   install uv

   ```bash
   brew install uv
   uv sync
   ```
   Or using pip:
  
  ```bash
   pip install -r requirements.txt   
   ```

3. **Set up environment variables:**

   Create a `.env` file in the project root with your Nium API credentials:

   ```env
   API_KEY=your_nium_api_key
   CLIENT_ID=your_client_id
   CUSTOMER_ID=your_customer_id
   WALLET_ID=your_wallet_id
   ```

4. **Congfigure Claude Desktop:**

   Add the following configuration to your Claude Desktop config file:

   **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

   **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

   ```json
   {
   "mcpServers": {
      "nium": {
         "command": "/path/to/your/uv",
         "args": [
         "--directory",
         "/path/to/your/mcp-server-sandbox",
         "run",
         "nium_mcp.py"
         ]
      }
   }
   }
   ```

   Go to the settings menu. Under Developer, select Edit Config.
   

5. **Launch Claude**

   You will now be able to see Nium in the prompt options menue
   

   You can also see what tools are enabled within the Nium MCP connection
   

   Try prompting Claude for Nium specific use cases.

   Use case examples:

   1. Querying Beneficiaries
   2. Sending Money
   3. List transactions
   4. Update Beneficiaries

## Environment Configuration

### Required Environment Variables

All environment variables should be added to a `.env` file in the project root directory. This file is automatically loaded when the MCP server starts.

#### **API_KEY** (Required)

Your Nium API authentication key.

- **Where to find**: Nium Portal → API Keys section
- **Format**: String (e.g., `41b2PYr9KV92kvBq8GUqY6LTppOsg812334HAjd3`)
- **Used for**: Authenticating all API requests to Nium

#### **CLIENT_ID** (Required) 

Your Nium client identifier, also referred to as `clientHashId` in API documentation.

- **Where to find**: Nium Portal → API Keys section
- **Format**: UUID (e.g., `3bb47cf1-ec41-4159-8b12-ad5bf246d04d`)
- **Used for**: Identifying your client in API endpoints

#### **CUSTOMER_ID** (Required)

Your Nium customer identifier, also referred to as `customerHashId` in API documentation.

- **Where to find**: Nium Portal → Customer Balances
- **Format**: UUID (e.g., `0ad3e0e3-d30d-4c49-ac95-72d563ba5e37`)
- **Used for**: Beneficiary management and transaction operations

#### **WALLET_ID** (Required)

Your Nium wallet identifier, also referred to as `walletHashId` in API documentation.

- **Where to find**: Nium Portal → Customer Balances
- **Format**: UUID (e.g., `eac1c866-f12c-47ee-8344-a1365b043d47`)
- **Used for**: Money transfers and transaction history

### Sample .env File

```env
# Nium API Configuration
API_KEY=41b2PYr9KV92kvBq8GUqY6LTppOsg812334HAjd3
CLIENT_ID=3bb47cf1-ec41-4159-8b12-ad5bf246d04d
CUSTOMER_ID=0ad3e0e3-d30d-4c49-ac95-72d563ba5e37
WALLET_ID=eac1c866-f12c-47ee-8344-a1365b043d47
```

### Environment Setup Steps

1. **Create the `.env` file:**

   ```bash
   touch .env
   ```

2. **Add your credentials:**
   Open the `.env` file in a text editor and add your actual Nium credentials:

   ```bash
   nano .env
   # or
   code .env
   ```

3. **Verify the configuration:**
   The MCP server will validate all required environment variables on startup and provide clear error messages if any are missing.

### Security Notes

- **Never commit your `.env` file** to version control
- The `.env` file should be added to your `.gitignore`
- **Keep your API credentials secure** and rotate them regularly
- **Use different credentials** for development, staging, and production environments

### Environment Variable Validation

The MCP server includes built-in validation that will:

- ✅ Check for all required environment variables on startup
- ✅ Provide clear error messages for missing variables
- ✅ Mask sensitive information (API keys) in debug output
- ✅ Validate credential format before making API calls

If any required environment variables are missing, you'll see an error like:

```bash
Missing required environment variables: CLIENT_ID, WALLET_ID
```

## MCP Client Integration

### Claude Desktop

Add the following configuration to your Claude Desktop config file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "nium": {
      "command": "/path/to/your/uv",
      "args": [
        "--directory",
        "/path/to/your/mcp-server-sandbox",
        "run",
        "nium_mcp.py"
      ]
    }
  }
}

```

### Generic MCP Client

For any MCP-compatible client:

```bash
python nium_mcp.py
```

Or using uv:

```bash
uv run nium_mcp.py
```

## 📋 Available Tools

### 1. `get_beneficiary_schema`

Retrieve validation schemas for creating beneficiaries.

**Parameters:**

- `currencyCode` (string): Currency code (e.g., "USD")
- `destinationCountry` (string): Destination country code (e.g., "US")
- `payoutMethod` (string): Payout method (e.g., "BANK_TRANSFER")

**Example:**

```python
get_beneficiary_schema(
    currencyCode="EUR",
    destinationCountry="DE", 
    payoutMethod="SWIFT"
)
```

### 2. `list_beneficiaries`

Retrieve existing beneficiaries with optional filtering.

**Parameters:**

- `page` (int, optional): Page number (default: 0)
- `size` (int, optional): Results per page (default: 20, max: 100)
- `search` (string, optional): Search term
- `status` (string, optional): Filter by status

**Example:**

```python
list_beneficiaries(page=0, size=10, search="John")
```

### 3. `create_beneficiary`

Create a new beneficiary with automatic schema validation.

**Parameters:**

- `beneficiary_name` (string): Beneficiary name
- `currency_code` (string): Currency code
- `country_code` (string): Country code
- `payout_method` (string): Payout method
- `beneficiary_data` (dict, optional): Custom beneficiary data

**Example:**

```python
create_beneficiary(
    beneficiary_name="John Doe",
    currency_code="USD",
    country_code="US",
    payout_method="BANK_TRANSFER"
)
```

### 4. `update_beneficiary`

Update existing beneficiary information.

**Parameters:**

- `beneficiary_hash_id` (string): Beneficiary ID to update
- `beneficiary_data` (dict, optional): Complete update data
- Plus 40+ individual field parameters for specific updates

**Example:**

```python
update_beneficiary(
    beneficiary_hash_id="68bfc6e715e69a63f748d684",
    beneficiary_name="John Smith Updated",
    beneficiary_email="john.updated@example.com"
)
```

### 5. `send_money`

Send money with automatic beneficiary verification and confirmation.

**Parameters:**

- `beneficiary_name_or_id` (string): Beneficiary name or ID
- `source_amount` (float): Amount to send
- `source_currency` (string): Source currency
- `country_code` (string, optional): Country for new beneficiaries
- `payout_method` (string, optional): Payout method for new beneficiaries
- `purpose_code` (string, optional): Transaction purpose
- `source_of_funds` (string, optional): Source of funds
- `exemption_code` (string, optional): Exemption code
- `own_payment` (bool, optional): Own payment flag
- `confirm_send` (bool): Confirm money transfer
- `confirm_create` (bool): Confirm beneficiary creation

**Example Workflow:**

1. **Initial call:**

   ```python
   send_money(
       beneficiary_name_or_id="John Doe",
       source_amount=100.0,
       source_currency="USD"
   )
   ```

2. **If beneficiary exists, confirm transfer:**

   ```python
   send_money(
       beneficiary_name_or_id="John Doe",
       source_amount=100.0,
       source_currency="USD",
       confirm_send=True
   )
   ```

3. **If new beneficiary, confirm creation then transfer:**

   ```python
   # Step 1: Confirm creation
   send_money(
       beneficiary_name_or_id="Jane Doe",
       source_amount=100.0,
       source_currency="USD",
       confirm_create=True
   )
   
   # Step 2: Confirm transfer
   send_money(
       beneficiary_name_or_id="Jane Doe",
       source_amount=100.0,
       source_currency="USD",
       confirm_create=True,
       confirm_send=True
   )
   ```

### 6. `get_wallet_transactions`

Retrieve wallet transaction history.

**Parameters:**

- `page` (int, optional): Page number
- `size` (int, optional): Results per page
- `start_date` (string, optional): Start date (YYYY-MM-DD)
- `end_date` (string, optional): End date (YYYY-MM-DD)
- `transaction_type` (string, optional): Transaction type
- `status` (string, optional): Transaction status
- `currency_code` (string, optional): Currency filter
- `system_reference_number` (string, optional): System reference
- `customer_reference_number` (string, optional): Customer reference

**Example:**

```python
get_wallet_transactions(
    page=0,
    size=20,
    start_date="2024-01-01",
    end_date="2024-12-31",
    status="COMPLETED"
)
```

## Safety Features

### Confirmation Workflow

- **Double Confirmation**: All money transfers require explicit confirmation
- **New Beneficiary Safety**: Two-step process for new beneficiaries (create � confirm transfer)
- **Transfer Details**: Shows amount, currency, and recipient before confirmation
- **Beneficiary Verification**: Automatically searches for existing beneficiaries to prevent duplicates

## API Coverage

This MCP server covers the following Nium API endpoints:

| Method | Endpoint                                                                                             | Description                               |
| :--- | :--------------------------------------------------------------------------------------------------- | :---------------------------------------- |
| `GET`  | `/api/v2/client/{clientHashId}/customer/{customerHashId}/currency/{currencyCode}/validationSchemas` | Get beneficiary validation schemas        |
| `GET`  | `/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries`                             | List beneficiaries                        |
| `POST` | `/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries`                             | Create a beneficiary                      |
| `PUT`  | `/api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries/{beneficiaryHashId}`         | Update a beneficiary                      |
| `POST` | `/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance`          | Send money                                |
| `GET`  | `/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/transactions`        | Get wallet transactions                   |

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nium-global](https://github.com/nium-global)
- **Source:** [nium-global/mcp-server-sandbox](https://github.com/nium-global/mcp-server-sandbox)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-nium-global-mcp-server-sandbox
- Seller: https://agentstack.voostack.com/s/nium-global
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.