Callx402 MCP server

What callx402 MCP server MCP server does

The callx402 MCP server MCP server connects an MCP client to the diagnostic side of Veyline's x402 infrastructure through the Payload rail. It is designed for investigating payment and settlement problems rather than moving funds. The included MCP implementation exposes six read-only x402_* tools.

The available diagnostic coverage includes subsystem status, x402 or MCP failure diagnosis, evidence handling, explanation of payment state, transaction recovery analysis, and settlement resolution. The repository's broader command-line interface also describes routing, execution, and rescue workflows, but those actions are not performed by the MCP server described here.

This makes the server suitable for an agent that needs to answer questions such as whether a subsystem is reachable, where an x402 request failed, or whether available evidence supports a settlement conclusion. It does not provide a payment authorization path.

How it works

The MCP server runs as a Node.js process using standard input and standard output. An MCP-compatible client starts mcp/index.js, exchanges the normal MCP handshake, and then discovers the six diagnostic tools. No package installation is needed specifically for the MCP server because it uses Node.js built-ins only.

x402_status works with zero setup and reports subsystem reachability. The other five tools dispatch into the v2.0.0 subsystem tree. Until that tree is available through the configured runtime and the corresponding feature flag is enabled, those tools report subsystem_unreachable.

The server is read-only in the documented MCP mode. It does not charge a user, execute a paid action, retry a request, or repay a transaction. The wider callx402 package can use hosted or local subsystem runtimes, but those modes do not change the MCP server's documented diagnostic behavior.

Setup and configuration

Clone the repository, then add a server entry to the MCP client's configuration. The command should be node, and the argument should be the absolute path to mcp/index.js:

{
  "mcpServers": {
    "callx402": {
      "command": "node",
      "args": ["/absolute/path/to/callx402/mcp/index.js"]
    }
  }
}

The README gives configuration locations for Claude Desktop, Cursor, and Windsurf. Restart the client and ask it to list available MCP tools. A Node.js version of 18 or newer is required by the package metadata.

For the basic status check, no environment variables, account, API key, or npm installation is required. Full subsystem access requires CALLX402_V2_ROOT to point to the v2.0.0 subsystem tree and requires the relevant subsystem flag to be enabled. The README also documents CALLX402_LOCAL=1 for local execution and a separate remote mode for the command-line and HTTP interfaces; these settings are not needed for the basic stdio server.

Limitations and notes

The callx402 MCP server MCP server is intentionally limited to diagnostics. It should not be selected when an agent must execute a paid x402 action, authorize a wallet transaction, retry a settlement, or perform repayment. Those behaviors are outside the read-only MCP implementation.

Most tools will not return live subsystem results on a bare checkout because the v2.0.0 tree and matching flags are not configured. In that state, x402_status remains usable, while the other diagnostic tools report that their subsystem is unreachable. The repository describes the hosted Payload rail and local subsystem tree separately, so deploying this MCP process alone does not imply that every backend diagnostic is available.

The MCP transport is stdio rather than HTTP. The repository includes a separate HTTP server and JavaScript and Python interfaces, but those are distinct access paths. Use the MCP configuration when the consumer is an MCP client; use the other interfaces only when an application specifically needs them.