Skip to main content
Glama
Modexia

Modexia

Official
by Modexia

name: modexia-mcp version: 0.4.1 description: The official Model Context Protocol (MCP) server for autonomous AI Agents to interact with Modexia's crypto infrastructure. author: Modexia homepage: https://github.com/Modexia/ModexiaAgentpay tags:

  • mcp

  • web3

  • payments avatar: https://raw.githubusercontent.com/Modexia/ModexiaAgentpay/main/apps/mcp-server/assets/modexialogo.png config: type: stdio command: uvx args:

    • modexia-mcp skills:

  • nanopay

  • nanopay_activate

  • nanopay_deposit

  • nanopay_withdraw

  • nanopay_balance

  • submit_intent

  • get_intent

  • list_intents

  • open_channel

  • consume_channel

  • settle_channel

  • get_channel

  • list_channels

  • get_balance

  • get_history

  • transfer

  • cross_chain_transfer

  • smart_fetch prompts:

  • nanopay_usage_instruction

  • create_intent_payment_instruction

  • setup_microtransactions_instruction

  • create_payment_instruction resources:

  • modexia://docs/llms_context


PyPI version License: MIT

Welcome to the Modexia AgentPay MCP Server (modexia-mcp). This server bridges the gap between Large Language Models and the real-world digital economy.

By integrating this standard Model Context Protocol (MCP) server into your AI stack (Claude Desktop, LobeChat, Dify, or custom multi-agent swarms), you instantly equip your AI Agents with a programmatic Smart Contract Wallet.

Instead of your agents hitting 402 Payment Required errors and failing, they can now autonomously negotiate paywalls, purchase premium data, execute zero-gas microtransactions via Circle Gateway, and trade compute resources with other agents in high-frequency vault channels.

Modexia gives your AI a bank account, and MCP gives it the tools to use it.


What's New in v0.4.1

Circle Gateway Nanopayments (x402) This release brings full agentic support for gas-free, sub-cent microtransactions directly to the MCP level.

  • nanopay — Fetch an x402-protected URL and automatically negotiate the payment using EIP-3009 offline signatures. Includes inline auto-refill logic.

  • nanopay_activate — One-time activation for the agent.

  • nanopay_deposit / nanopay_withdraw — Manage gateway funds directly from the main wallet.

  • nanopay_balance — Track the True Available Balance (Gateway deposits minus pending/unsettled signatures).

  • Structured Error Handling — The MCP tools now pass back structured ModexiaPaymentError codes (e.g., INSUFFICIENT_MAIN_BALANCE) so the LLM can reason about failures and take corrective action.


Related MCP server: remit.md MCP Server

Previous: What's New in v0.3.0 (Intent-to-Pay)

Intent-Based Payments (v2) Execute standard USDC payments through a strict compliance pipeline with rich feedback.

  • submit_intent — Create a signed intent, validate against policies, and execute on-chain.

  • get_intent / list_intents — Audit trail and tracking.


Features

  • Circle Gateway Integration: Direct programmatic access to Circle's USDC nanopayment infrastructure.

  • Gas-Free Microtransactions: Send payments as low as $0.000001 with zero blockchain fees.

  • EIP-3009 Offline Signatures: Secure, off-chain payment authorizations that prevent double-spending.

  • Intent-Based Routing: Strict policy enforcement, daily spend limits, and cryptographic audit trails.

  • Automated Paywall Negotiation: Automatically detect 402 Payment Required headers and fulfill them inline.

  • Smart Auto-Refill: Seamlessly top-up gateway balances from the main wallet when funds run low.


Exposed MCP Components

Tools

Tool Name

Description

nanopay

Auto-negotiate and pay for 402 Payment Required URLs using EIP-3009 offline signatures.

nanopay_activate

One-time activation command to enable Circle Gateway nanopayments for the agent.

nanopay_deposit

Deposit funds from the main agent wallet to the nanopayment Gateway.

nanopay_withdraw

Withdraw unused funds from the Gateway back to the main wallet.

nanopay_balance

Check the True Available Balance (Gateway deposits minus pending signatures).

submit_intent

Execute a standard USDC payment with compliance and policy enforcement.

get_intent

Retrieve the status and compliance metadata of a previously submitted payment intent.

list_intents

Fetch recent payment intents for audit trail review.

open_channel

Lock funds into a smart contract for high-frequency micro-transactions.

consume_channel

Execute instant, gas-free micro-payments inside an open channel.

settle_channel

Close the vault and distribute funds on-chain.

get_channel

Check the current capacity and state of a specific payment channel.

list_channels

List all payment channels associated with the agent's wallet.

get_balance

Retrieve the current USDC balance of the agent's primary Smart Contract Wallet.

get_history

Fetch the recent transaction history for the agent.

transfer

Execute a standard synchronous USDC transfer (v1).

cross_chain_transfer

Execute a cross-chain CCTP payment via Squid Router (e.g., Ethereum -> Akash).

smart_fetch

Legacy HTTP auto-negotiation for HTTP-based Paywalls.

Prompts

Prompt Name

Description

nanopay_usage_instruction

Best practices for funding the gateway and executing nanopay operations.

create_intent_payment_instruction

Rules for structuring compliant payments, adding memos, and handling policy rejections.

setup_microtransactions_instruction

Step-by-step guide on opening, consuming, and settling vault channels.

create_payment_instruction

Standard rules for legacy idempotency-based transfers.

Resources

Resource URI

Description

modexia://docs/llms_context

The complete Modexia Developer Protocol Guide with overarching economic rules for swarms.


Configuration & Setup

This server requires a Modexia API Key to function. You can obtain one by creating a developer account at modexia.software.

Variable

Description

MODEXIA_API_KEY

Required. Your Modexia developer key (e.g. mx_test_...)

MODEXIA_BASE_URL

Optional. Overrides the API endpoint. Defaults to the Sandbox Environment.

Using uvx (Recommended)

You can run this server directly in any MCP client that supports standard executable commands:

uvx modexia-mcp

Claude Desktop

To use Modexia with Claude Desktop, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "modexia": {
      "command": "uvx",
      "args": ["modexia-mcp"],
      "env": {
        "MODEXIA_API_KEY": "mx_test_YourApiKeyHere"
      }
    }
  }
}

Contributing to Open Source

We actively welcome community contributions to make this MCP server even better. Because it acts as the primary interface for autonomous AI agents, we heavily prioritize stability and strict prompt engineering.

  1. Clone the Repo: git clone https://github.com/Modexia/modexia-mcp.git

  2. Install Dependencies: pip install -e .

  3. Run Locally: You can run the server in stdio mode for local testing via python -m modexia_mcp

  4. Submit PRs: Open a Pull Request targeting the main branch.


Security Model

The Modexia MCP Server never exposes your private keys to the LLM context. The AI only has permission to trigger explicitly configured MCP tools. Policy limits (e.g., maximum daily spend, hourly caps) are enforced automatically on the Modexia backend. Even a hallucinating AI cannot drain your wallet above your predefined guards.

License & Support

modexia-mcp is an open-source tool governed by the MIT License.

Need help scaling your agent swarm or configuring your API keys? Access your developer dashboard and explore the docs at modexia.software.

Available Tools

18 tools
consume_channelB

Execute an instant, gas-free micro-payment inside an already open channel. Call this as many times as needed while the channel is open.

Inputs: amount (required), channel_id (required), idempotency_key.

cross_chain_transferA

Send a cross-chain CCTP payment natively to another blockchain using Squid Router. Requires to_chain (e.g., '1' for Ethereum, 'akashnet-2' for Akash Network), to_token address, and the recipient wallet address. Gas relaying on the destination is covered automatically! Always provide an idempotency_key to prevent double charges.

Inputs: amount (required), to_chain (required), to_token (required), recipient (required), +1 more.

get_balanceA

Retrieve the current USDC wallet balance for the Agent's Smart Contract Wallet.

Inputs: no named parameters. Returns: result

get_channelA

Get the current status, deposit amount, and remaining balance of a specific payment channel.

Inputs: channel_id (required).

get_historyC

Fetch the recent transaction history for the authenticated agent.

Inputs: limit.

get_intentA

Get the status and details of a previously submitted payment intent.

Inputs: intent_id (required).

list_channelsB

List all payment channels associated with the authenticated agent's wallet.

Inputs: limit.

list_intentsB

List the most recent payment intents with their status and details.

Inputs: limit.

nanopayA

Fetch an x402-protected resource and automatically pay using Circle Gateway nanopayments. Gas-free, instant, supports payments as low as $0.000001 USDC. Use this for sub-cent API calls and premium data purchases.

Inputs: url (required), method.

nanopay_activateA

Enable Circle Gateway nanopayments for this agent. Must be called once before using nanopay, nanopay_deposit, or nanopay_balance. Idempotent — calling again returns the existing activation.

Inputs: no named parameters.

nanopay_balanceA

Get the agent's Circle Gateway nanopayment balance (separate from main wallet balance).

Inputs: no named parameters.

nanopay_depositA

Deposit USDC from the agent's main wallet into the nanopayment Gateway. This is an on-chain transaction. After depositing, nanopayments are gas-free.

Inputs: amount (required).

nanopay_withdrawB

Withdraw USDC from the nanopayment Gateway back to the agent's main wallet.

Inputs: amount (required).

open_channelA

Open a high-frequency micro-payment vault channel with on-chain deposit. Blocks funds for the specific provider, allowing instant, gas-free payments via consume_channel.

Inputs: provider (required), deposit_amount (required), duration_hours.

settle_channelA

Settle an open micro-payment channel, paying the provider, and refunding the remainder back to you.

Inputs: channel_id (required).

smart_fetchA

Fetch an external resource via HTTP. If the resource responds with a 402 Payment Required and a WWW-Authenticate header, this tool will automatically negotiate and pay the invoice via Modexia AgentPay, then retry the request with the cryptographic proof of payment.

Inputs: url (required), method (required).

submit_intentB

Submit an intent-based payment (v2 API). Creates a signed intent token, submits it through the validation pipeline, and returns a rich result with compliance metadata (policy limits, daily spend, balance). Always provide a memo describing why you are making this payment.

Inputs: amount (required), recipient (required), memo.

transferA

Send a standard Modexia payment (USDC) to a recipient. Recommended to always provide an idempotency_key to prevent double charges. Optionally provide a memo to explain the reason for the payment (visible in audit trail).

Inputs: amount (required), recipient (required), memo, idempotency_key.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 18 tools

    Disambiguation4/5

    Tools are largely distinct, covering different payment mechanisms (standard transfers, cross-chain, channels, intents, nanopayments). Some overlap exists between transfer and submit_intent, and between smart_fetch and nanopay, but descriptions clarify their different triggers and protocols.

    Naming Consistency4/5

    Most tools follow a consistent verb_noun or resource-specific pattern (get_*, list_*, *channel, nanopay_*). Minor deviations like 'smart_fetch' and standalone 'nanopay' break the convention slightly, but overall naming is predictable and readable.

    Tool Count4/5

    At 18 tools, the server is slightly on the heavier side of the ideal 3-15 range, but each tool addresses a distinct payment capability (standard, cross-chain, channels, intents, nanopayments), so the count feels justified for the scope.

    Completeness4/5

    The tool surface covers the full payment lifecycle for multiple payment methods: balances, transfers, history, channel open/consume/settle, intents, and nanopay management. Minor gaps exist (no cancel for regular transfers, no single-transfer detail retrieval), but these are not critical for core workflows.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      Enables AI agents to perform financial transactions such as direct payments, escrows, and bounty management using natural language with zero code integration. It provides a comprehensive suite of tools for fund streaming, subscriptions, and reputation tracking to facilitate secure agent-to-agent commerce.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      AI-to-AI marketplace MCP server with 46 tools — swap 65+ crypto tokens on 7 chains, rent GPUs, trade 25 tokenized stocks, on-chain escrow (Solana + Base), DeFi yields, sentiment analysis, wallet monitoring, and image generation. Supports USDC payments across 14 blockchains.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server for USDC payments on Base, enabling AI agents to check balances, send payments, generate payment requests, and view transaction history.
      4
      2
      MIT