Flux MCP Server

A Model Context Protocol (MCP) server that enables Claude Desktop to interact with paid APIs through the Flux Gateway. Pay for API calls with cryptocurrency and access any API registered on Flux Gateway directly from Claude.

Features

• 🔐 Secure Wallet Management: Encrypted private key storage
• 💰 Multi-Chain Support: Base, Polygon, Ethereum, and their testnets
• 💳 Multiple Payment Tokens: ETH and USDC
• 🔍 Automatic API Discovery: Fetches OpenAPI specs from Flux Gateway
• 🛠️ MCP Integration: Seamlessly integrates with Claude Desktop
• 📝 Comprehensive Logging: Debug and monitor all operations

Installation

Prerequisites

• Node.js 18+ and npm
• A wallet with funds on supported chains (Base, Polygon, Ethereum, or testnets)
• Claude Desktop app

Install from npm (Recommended)

npm install -g flux-mcp-server

Install from Source

# Clone the repository
cd packages/mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Link globally for testing
npm link

Quick Start

1. Initialize Configuration

flux-mcp init

You'll be prompted for:

• Private Key: Your wallet private key (stored encrypted)
• Default Chain: Choose from Base, Polygon, Ethereum, or testnets

Example:

🚀 Flux MCP Server Setup

? Enter your wallet private key: [hidden]
? Select default blockchain: amoy

✅ Configuration saved successfully!
📁 Config file: /Users/you/.flux-mcp/config.json
💼 Wallet address: 0x1234...5678
🔐 Private key: 0x12...cc (encrypted)
⛓️  Default chain: amoy

2. Add APIs

Add APIs from Flux Gateway to your configuration:

flux-mcp add-api --id <API_ID> --name "My API"

Example:

flux-mcp add-api --id 692ac2eea35009305476f0a1 --name "JSONPlaceholder Test API"

3. List Configured APIs

flux-mcp list

Output:

📋 Flux MCP Server Configuration

💼 Wallet: 0x01632ba6285791D56fCfA6966f5Ad06E5c8896B5
🔐 Private Key: encryp...96cc
⛓️  Default Chain: amoy
📁 Config: /Users/you/.flux-mcp/config.json

APIs:
  1. ✅ JSONPlaceholder Test API (692ac2eea35009305476f0a1)

4. Start the Server

flux-mcp start

Output:

15:38:59 [info] 🚀 Starting Flux MCP Server...
15:38:59 [info] 💼 Wallet: 0x01632ba6285791D56fCfA6966f5Ad06E5c8896B5
15:38:59 [info] ⛓️  Default Chain: amoy
15:38:59 [info] 📋 APIs configured: 1
15:38:59 [info] ✅ Discovered 1 APIs
15:38:59 [info] 📡 Total endpoints: 1
15:38:59 [info] ✅ Flux MCP Server is running!

Claude Desktop Configuration

Add the MCP server to your Claude Desktop configuration:

macOS/Linux

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "flux": {
      "command": "flux-mcp",
      "args": ["start"]
    }
  }
}

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "flux": {
      "command": "flux-mcp.cmd",
      "args": ["start"]
    }
  }
}

Restart Claude Desktop

After updating the configuration, restart Claude Desktop. The Flux MCP server will start automatically and Claude will have access to all your configured APIs.

Usage in Claude

Once configured, you can ask Claude to use your APIs:

"Can you get post 1 from the JSONPlaceholder API?"

Claude will:

1. Identify the appropriate API endpoint
2. Send payment to the blockchain
3. Sign the authorization message
4. Call the API through Flux Gateway
5. Return the results

Configuration

Configuration File Location

• macOS/Linux: ~/.flux-mcp/config.json
• Windows: %USERPROFILE%\.flux-mcp\config.json

Configuration Structure

{
  "version": "1.0.0",
  "wallet": {
    "privateKey": "encrypted:...",
    "address": "0x..."
  },
  "defaultChain": "amoy",
  "gatewayUrl": "https://useflux.site",
  "rpcUrls": {
    "base": "https://mainnet.base.org",
    "polygon": "https://polygon-rpc.com",
    "ethereum": "https://eth.llamarpc.com",
    "base-sepolia": "https://sepolia.base.org",
    "amoy": "https://rpc-amoy.polygon.technology",
    "sepolia": "https://ethereum-sepolia.publicnode.com"
  },
  "apis": [
    {
      "id": "692ac2eea35009305476f0a1",
      "name": "JSONPlaceholder Test API",
      "enabled": true
    }
  ],
  "logging": {
    "level": "info",
    "file": "/Users/you/.flux-mcp/logs/server.log"
  }
}

Configuration Options

• wallet.privateKey: Encrypted private key (set via flux-mcp init)
• wallet.address: Derived Ethereum address
• defaultChain: Default blockchain for payments
• gatewayUrl: Flux Gateway URL (defaults to production, use http://localhost:3000 for local development)
• rpcUrls: RPC endpoints for each supported chain
• apis: List of configured APIs
• logging.level: Log level (debug, info, warn, error)
• logging.file: Log file location

Supported Chains

Mainnets

• base: Base (Coinbase L2)
• polygon: Polygon PoS
• ethereum: Ethereum Mainnet

Testnets

• base-sepolia: Base Sepolia Testnet
• amoy: Polygon Amoy Testnet
• sepolia: Ethereum Sepolia Testnet

Payment Tokens

• ETH: Native token on all chains
• USDC: USD Coin (ERC-20)

Commands Reference

flux-mcp init

Initialize configuration with wallet and chain selection.

flux-mcp add-api --id <apiId> --name <name>

Add an API to your configuration.

Options:

• --id: API ID from Flux Gateway (required)
• --name: Friendly name for the API (required)

flux-mcp remove-api --id <apiId>

Remove an API from your configuration.

Options:

• --id: API ID to remove (required)

flux-mcp list

List all configured APIs and wallet information.

flux-mcp start

Start the MCP server.

flux-mcp --help

Display help information.

Development

Project Structure

packages/mcp-server/
├── src/
│   ├── cli/           # CLI commands
│   ├── config/        # Configuration management
│   ├── mcp/           # MCP server implementation
│   ├── services/      # Core services
│   │   ├── discovery.ts   # API discovery
│   │   ├── payment.ts     # Payment handling
│   │   ├── signing.ts     # Message signing
│   │   └── gateway.ts     # Gateway client
│   ├── types/         # TypeScript types
│   └── utils/         # Utilities
├── dist/              # Compiled JavaScript
├── package.json
└── tsconfig.json

Build

npm run build

Run Tests

npm test

Local Development

# Build and link
npm run build
npm link

# Test commands
flux-mcp --help
flux-mcp init

Troubleshooting

"Failed to discover any APIs"

Cause: Cannot fetch OpenAPI spec from Flux Gateway.

Solutions:

• Check your internet connection
• Verify the API ID is correct
• Ensure the API exists on Flux Gateway
• For local development, set gatewayUrl to http://localhost:3000 in config

"Insufficient funds"

Cause: Wallet doesn't have enough balance for payment.

Solutions:

• Check your wallet balance on the blockchain
• Get testnet tokens from faucets for testnets
• Switch to a different chain with sufficient balance

"Payment transaction not found"

Cause: Transaction hasn't been confirmed yet.

Solutions:

• Wait a few seconds and try again
• Check transaction status on block explorer
• Ensure you're using the correct RPC URL

"Signature verification failed"

Cause: Invalid signature or message format.

Solutions:

• Ensure your private key is correct
• Check that the wallet address matches
• Restart the MCP server

Claude Desktop doesn't see the server

Cause: Configuration issue or server not running.

Solutions:

• Verify claude_desktop_config.json is correct
• Restart Claude Desktop
• Check logs at ~/.flux-mcp/logs/server.log
• Ensure flux-mcp command is in PATH

Security

• Private keys are encrypted using AES-256-CBC before storage
• Config file permissions are set to 600 (owner only)
• Never share your private key or config file
• Use testnets for development and testing
• Keep small amounts in hot wallets used for API payments

Logs

Logs are stored at:

• macOS/Linux: ~/.flux-mcp/logs/server.log
• Windows: %USERPROFILE%\.flux-mcp\logs\server.log

Log levels:

• debug: Detailed debugging information
• info: General information (default)
• warn: Warning messages
• error: Error messages

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

• Documentation: https://chirags-organization-7.gitbook.io/product-docs
• Issues: https://github.com/chirag9899/Flux/issues

Related Projects

• Flux MCP Server on npm - The MCP server package
• MCP SDK - Model Context Protocol SDK

Built with ❤️ for the Flux Gateway ecosystem