Build for Agents
MCP integration

x402 MCP Server Integration

Overview

The x402 MCP Server Integration enables AI agents running inside IDEs or frameworks (MCP clients) to seamlessly access datasets through the x402 MCP server.

This guide explains how to:

  1. Install and configure the x402 MCP Server
  2. Connect it to an MCP Client (e.g., VS Code with Cline, Cursor IDE)
  3. Use the AI Agent to call MCP tools (e.g., list_datasets, query_dataset)

Glossary

  • MCP Server
    A process that exposes tools and APIs to clients.
    Here: the x402 MCP Server, which bridges AI requests to the x402 API and handles payments.

  • MCP Client
    The environment or IDE that launches and manages MCP servers.
    Examples: VS Code with the Cline extension, Cursor IDE, Claude Desktop.

  • AI Agent
    The assistant running inside the MCP client.
    It interprets user instructions and calls MCP server tools through the client.

1. What You Get

  • One-line install via npx (no repo clone required)
  • Your AI agents can access paid x402 endpoints through the MCP server
  • Only a PRIVATE_KEY is required for setup

2. Prerequisites

  • Node.js ≥ 18 and npm installed 
    node -v
npm -v
  • An x402-compatible private key (hex format, 0x…)

3. MCP Server Configuration

The MCP server is available as an npm package: @mfloai/x402-mcp (opens in a new tab)

Paste the following JSON snippet into your MCP client's configuration (e.g., Cline or Cursor):

{
  "mcpServers": {
    "@mfloai/x402-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "@mfloai/x402-mcp@demo",
        "x402-mcp"
      ],
      "env": {
        "PRIVATE_KEY": "EVM_PRIVATE_KEY"
      }
    }
  }
}

Note: API_BASE_URL is optional. Include it only if your deployment requires a custom endpoint.

Optional: Run once from terminal (sanity check)

PRIVATE_KEY=0xYOUR_PRIVATE_KEY \
npx -y @mfloai/x402-mcp@demo

If successful, the server will announce the available tools. Stop with Ctrl+C.

4. Next Steps

For detailed client setup instructions, see MCP Client Setup.

📄 LLM.txt Documentation

For AI developers who want to provide comprehensive Mflo knowledge to their AI systems:

📥 Download llm.txt — Complete Mflo documentation in LLM-friendly format

This file contains all our documentation optimized for AI consumption, perfect for:

  • Giving your AI agents complete knowledge about Mflo
  • Training custom models with accurate Mflo information
  • Providing context to LLMs for better responses
  • Building AI applications with comprehensive Mflo understanding

5. Example Interactions

User: "What cryptocurrency datasets are available?"
AI Agent: [Calls list_datasets via MCP server]
AI Agent: "I found several crypto datasets including real-time prices, trading volumes, and historical data..."

User: "Get me the latest Bitcoin price data"
AI Agent: [Calls query_dataset via MCP server, x402 payment handled automatically]
AI Agent: "Here's the latest Bitcoin data: BTC/USDT at $68,123.45..."

6. Troubleshooting

IssueSolution
Command not found: npxInstall Node.js ≥ 18
402 Payment RequiredEnsure your PRIVATE_KEY is valid and has sufficient funds/authorization
Timeouts / no dataCheck network/proxy settings; report bugs or errors via the GitHub repository

7. Security Notes

  • The PRIVATE_KEY is only stored in the MCP server process spawned by your IDE.
  • Prefer a dedicated key with minimal on-chain permissions, and rotate it periodically.

8. Version Pinning

  • To pin a version, replace @demo with a semver range or exact version, e.g.:
    • @mfloai/x402-mcp@0.1.x
    • @mfloai/x402-mcp@0.1.3

9. How It Works (Summary)

  1. User gives instructions to the AI Agent.
  2. The AI Agent requests a tool via the MCP Client.
  3. The MCP Client spawns the MCP Server.
  4. The MCP Server calls the x402 API, handling payments automatically with PRIVATE_KEY.
  5. Results are returned to the AI Agent, then presented to the user.
Supported WalletsMCP Clients