Diagram flow

Integration

To integrate the SOLx402 MCP Server, follow these steps:

• Go to the SOLx402 MCP Server Smithery page.
• Sign in.
• Click the Configure button.
• Fill in the required fields (and optional fields, if needed).
• Generate the URL using your API key and Profile, then copy it.
• Add the generated MCP Server URL to your system (e.g., Claude, Cursor, VS Code, etc.).

{
        "mcpServers": {
                "solx402-mcp-server": {
                    "url": "https://server.smithery.ai/@leandrogavidia/solx402-mcp-server/mcp?api_key=<YOUR-SMITHERY-API-KEY>&profile=<YOUR-SMITHERY-PROFILE>",
                    "type": "streamable-http",
                    "timeout": 120000
                },
            }
    }

Tools

• ### x402 Protocol

- Documentation - searchx402documentation: Search across the x402 documentation to find relevant information, code examples, API references, and guides. - x402protocolflow: Visual diagram showing the x402 protocol flow and architecture.

- Services Discovery - getx402services: Retrieve a list of available x402 services from the facilitator. - get_facilitators: Retrieve a list of known Solana facilitators.

- Service Consumption - consumex402service: Consume a specific x402 service with automatic payment handling. > ⚠️ Note: x402 services are external services maintained by third-party teams. While these services appear in the discovery layer, they may be temporarily down, unavailable, or experiencing issues. Service availability depends entirely on the external teams managing them.

• ### Wallet Operations

- Wallet Info - getwalletpublic_key: Retrieve the public key of the configured wallet.

- Balance - getwalletusdc_balance: Check the USDC token balance of the configured wallet.

• ### Solana Development Resources (Optional)

- Expert Assistance - AskSolanaAnchorFrameworkExpert: Ask questions about developing on Solana with the Anchor Framework. - SolanaExpertAskFor_Help: Get expert help on Solana development topics, concepts, APIs, SDKs, and errors.

- Documentation - SolanaDocumentationSearch: Search documentation across the Solana ecosystem for up-to-date information.

---

⚠️ Important: Request Timeout Configuration

Critical Setup Requirement: When using this MCP server, it's essential to configure your MCP client with a minimum request timeout of 60,000ms (60 seconds) to ensure successful execution of x402 service consumption.

Why This Matters:

• x402 services are external APIs that may require significant processing time.
• Payment transactions are executed on the Solana blockchain, which can take time to confirm.
• Short timeouts can cause requests to fail after USDC has been charged, resulting in payment without receiving the service.
• By default, MCP servers use a maximum request timeout of 10 seconds when running, which is quite low in some cases.

Configuration Examples:

{
  "mcpServers": {
    "solx402": {
      "url": "https://server.smithery.ai/@leandrogavidia/solx402-mcp-server/mcp?api_key=<YOUR-SMITHERY-API-KEY>&profile=<YOUR-SMITHERY-PROFILE>",
      "type": "streamable-http",
      "timeout": 120000 // 2 Minutes
    }
  }
}

Query Parameters:

The MCP server now accepts configuration through URL query parameters, making setup simpler and more flexible:

• privateKey (required): Base58-encoded private key for your Solana wallet
• mainnetRpcUrl (required): Solana RPC URL for mainnet operations

• isMainnet (optional): Set to true for mainnet, false for devnet (Default: false)
• facilitatorUrl (optional): URL of the x402 facilitator (default: PayAI Facilitator URL)
• maxPrice (optional): Maximum price to pay for services in USDC microcents, e.g. 10000 = 0.01 USDC (default: 0)
• useSolanaMcpServer (optional): Enable Solana development tools integration (default: false)

Related Issues:

• Cline PR #1904 - Request timeout configuration
• Cline Issue #4391 - Timeout-related problems

Note: Always ensure your MCP client timeout is at least 120 seconds to prevent payment issues and service consumption failures.

---

Configuration Options

1. Query Parameters

Pass configuration directly in the MCP client URL as shown in the examples above.

2. Environment Variables

You can use environment variables:

• PORT: Port where your MCP server will run (default: 8001)
• HOST: Host where your MCP server will run (default: 127.0.0.1)