MCP Integration

Enable AI agents to use your APIs with Model Context Protocol (MCP).

What is MCP?

Model Context Protocol (MCP) is an open standard that allows AI models to interact with external tools and APIs. Flux Gateway provides a native MCP server that handles payments and authentication automatically.

Current Status

✅ Available Now - The Flux MCP Server is ready to use!

The MCP server provides:

  • Automatic API discovery from Flux Gateway

  • Automated payment handling (ETH & USDC)

  • Wallet signature generation

  • Full MCP protocol compliance for Claude Desktop

Installation

From npm (Recommended)

npm install -g flux-mcp-server

From Source

# Clone the repository
git clone https://github.com/your-org/flux-gateway.git
cd flux-gateway/packages/mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Link globally
npm link

Quick Start

1. Initialize Configuration

flux-mcp init

This will prompt you for:

  • Your wallet private key (encrypted and stored securely)

  • Default blockchain (Base, Polygon, or Ethereum)

2. Add APIs

flux-mcp add-api --id abc123 --name "Weather API"

3. Start the Server

flux-mcp start

The server will:

  • Discover all configured APIs from Flux Gateway

  • Parse OpenAPI specifications

  • Convert endpoints to MCP tools

  • Start listening for Claude Desktop connections

Benefits for AI Agents

  • 🤖 Discoverable - APIs are machine-readable via OpenAPI specs

  • 💰 Pay-per-use - No subscriptions, just micropayments per request

  • 🔐 Trustless - Blockchain-verified payments, no API keys needed

  • 📊 Transparent - All transactions on-chain and auditable

Example: Building an MCP-Compatible Agent

Here's how an AI agent can integrate with Flux Gateway today:

Step 1: Discover APIs

// Fetch available API
const response = await fetch(
  'https://useflux.site/api/v2/apis/abc123/agent-info'
);
const apiInfo = await response.json();

console.log(apiInfo.capabilities); // List of endpoints with pricing

Step 2: Make Payment

import { ethers } from 'ethers';

// Send payment
const tx = await wallet.sendTransaction({
  to: apiInfo.capabilities[0].pricing.recipient,
  value: ethers.utils.parseEther(apiInfo.capabilities[0].pricing.amount)
});

await tx.wait();

Step 3: Sign Authorization

const message = `Flux API Authorization\n\nTransaction: ${tx.hash}\nService: ${endpointId}\n\nBy signing this message, you authorize Flux to use this payment for the specified API service.`;

const signature = await wallet.signMessage(message);

Step 4: Call API

const apiResponse = await fetch(
  `https://useflux.site/api/v2/gateway/abc123/weather`,
  {
    headers: {
      'x-flux-payment-tx': tx.hash,
      'x-flux-signature': signature
    }
  }
);

const data = await apiResponse.json();

Claude Desktop Setup

To use Flux APIs with Claude Desktop:

1. Install Claude Desktop

Download from claude.ai/desktop

2. Configure MCP Server

Edit your Claude Desktop configuration file:

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

Add the Flux MCP server:

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

3. Restart Claude Desktop

The Flux MCP server will now be available to Claude!

Features

✅ Automatic API Discovery - Fetches OpenAPI specs from Flux Gateway ✅ Payment Automation - Handles ETH & USDC payments on multiple chains ✅ Signature Generation - Signs authorization messages automatically ✅ Error Handling - Retries and clear error messages ✅ Secure Storage - AES-256 encrypted private key storage ✅ Multi-chain - Supports Base, Polygon, Ethereum + testnets

Security Best Practices

  1. Secure wallet management - Private keys are encrypted with AES-256

  2. Monitor spending - Check transaction history regularly

  3. Use testnets first - Test on Base Sepolia or Polygon Amoy before mainnet

  4. Separate wallets - Use a dedicated wallet for MCP, not your main wallet

  5. Set permissions - Config file is automatically set to owner-only (chmod 600)

Future Enhancements

Planned features for future releases:

  • Session management - Reuse payments across multiple requests

  • Request batching - Bundle multiple API calls into one payment

  • Response caching - Avoid redundant API calls

  • Spending limits - Set daily/weekly spending caps

  • Python SDK - flux-mcp package for Python-based agents

  • Web UI - Browser-based configuration and monitoring

Next Steps

PreviousUsing the APINextEndpoints

Last updated