Regen Network MCP Server

A Model Context Protocol (MCP) server providing programmatic access to the Regen Network blockchain - enabling AI agents and developers to interact with ecological credit markets.

Overview

This MCP server enables seamless interaction with Regen Network, a blockchain platform designed for ecological asset verification and trading. Through a standardized interface, you can:

🌍 Query ecological credit types, classes, and batches
💰 Analyze marketplace dynamics and sell orders
📊 Perform portfolio impact analysis
🔍 Compare methodology frameworks
⛓️ Access blockchain data (bank, governance, distribution modules)
🤖 Enable AI agents to participate in environmental markets

What is Regen Network?

Regen Network is a specialized blockchain infrastructure for ecological credits, supporting diverse asset types:

Carbon Credits (CO2e sequestration and reduction)
Biodiversity Credits (habitat preservation and restoration)
Regenerative Agriculture Metrics (soil health, grazing management)

The network provides transparent, verifiable tracking of ecological projects with on-chain provenance.

What is MCP?

The Model Context Protocol is a standardized interface for connecting AI systems to external data sources and tools. This server implements MCP to make Regen Network accessible to AI agents like Claude, ChatGPT, and custom applications.

Features

🛠️ 45+ Blockchain Tools

Bank Module (11 tools): Account balances, token supplies, denomination metadata
Distribution Module (9 tools): Validator rewards, delegator information, community pool
Governance Module (8 tools): Proposals, votes, deposits, tally results
Marketplace Module (5 tools): Sell orders, pricing, allowed denominations
Ecocredits Module (4 tools): Credit types, classes, projects, batches
Baskets Module (5 tools): Basket operations, balances, fees
Analytics Module (3 tools): Portfolio impact, market trends, methodology comparison

📖 8 Interactive Prompts

Guided workflows for common tasks:

Chain exploration and getting started
Ecocredit query workshop
Marketplace investigation
Project discovery
Credit batch analysis
Query builder assistance
Configuration setup
Full capabilities reference

🔧 Enterprise Features

Multiple endpoint failover for reliability
Configurable caching layer
Type-safe Pydantic models
Async/await for performance
Comprehensive error handling with retryability signals
Health monitoring and metrics

🔄 API Resilience (v3.1)

The client includes hardened retry/backoff logic:

Transient errors (5xx, 429, timeouts) are automatically retried with exponential backoff + jitter
Client errors (4xx except 429) fail immediately without wasting retry attempts
All errors include retryable and retry_after_ms fields for downstream clients
fetch_all_pages() helper eliminates agent-side pagination loops

🏷️ Credit Class Name Resolution (v3.2)

Credit class names are now resolved directly from on-chain anchored metadata IRIs:

Authoritative names: schema:name from https://api.regen.network/data/v2/metadata-graph/{iri}
Source registry: Extracts regen:sourceRegistry (e.g., "City Forest Credits" for C02)
Caching: 1-hour TTL for resolved metadata, 5-minute TTL for failures
No guessing: Class names like C01="Verified Carbon Standard" come from the chain, not hardcoded mappings

📊 Summary Mode

The /ecocredits/batches endpoint supports aggregation:

# Get summary by credit type instead of paginating through all batches
curl "https://regen.gaiaai.xyz/regen-api/ecocredits/batches?summary=true&fetch_all=true"

Returns totals for issued/tradable/retired credits by type, reducing common multi-page loops.

Installation

Prerequisites

Python 3.10 or higher
pip package manager

Quick Install

# Clone the repository
git clone https://github.com/your-org/regen-python-mcp.git
cd regen-python-mcp

# Install dependencies
pip install -r requirements.txt

# Run the server
python main.py

Configuration

The server uses environment variables for configuration. Create a .env file:

# Optional: Override default RPC endpoints
REGEN_RPC_ENDPOINTS=https://regen-rpc.polkachu.com,https://rpc.cosmos.directory/regen

# Optional: Override default REST endpoints
REGEN_REST_ENDPOINTS=https://regen-api.polkachu.com,https://rest.cosmos.directory/regen

# Optional: Configure caching
REGEN_MCP_ENABLE_CACHE=true
REGEN_MCP_CACHE_TTL_SECONDS=60

# Optional: Logging level
REGEN_MCP_LOG_LEVEL=INFO

See src/mcp_server/config/settings.py for all configuration options.

Quick Start

Using with Claude Code / Claude Desktop

The repository includes pre-configured MCP setup files. See MCP_SETUP.md for complete instructions.

Quick Start:

Files are already configured:
- .mcp.json - Server connection config
- .claude/settings.json - Enable MCP servers
Install dependencies: pip install -r requirements.txt
Restart Claude Code

Manual Configuration:

Add to your Claude Desktop or Claude Code configuration:

{
  "mcpServers": {
    "regen-network": {
      "command": "/path/to/uv",
      "args": ["run", "--directory", "/path/to/regen-python-mcp", "python", "main.py"],
      "env": {
        "PYTHONPATH": "/path/to/regen-python-mcp/src"
      }
    }
  }
}

Using with Python

from mcp.client import ClientSession, StdioServerParameters
import asyncio

async def main():
    server_params = StdioServerParameters(
        command="python",
        args=["main.py"]
    )

    async with ClientSession(server_params) as session:
        # List available tools
        tools = await session.list_tools()
        print(f"Available tools: {len(tools)}")

        # List credit types
        result = await session.call_tool("list_credit_types", {})
        print(result)

asyncio.run(main())

Example Queries

# Get all ecological credit types
await client.call_tool("list_credit_types", {})

# List credit classes with pagination
await client.call_tool("list_classes", {"limit": 10, "offset": 0})

# Get marketplace sell orders
await client.call_tool("list_sell_orders", {"page": 1, "limit": 20})

# Analyze portfolio impact
await client.call_tool("analyze_portfolio_impact", {
    "address": "regen1...",
    "analysis_type": "full"
})

# Compare methodologies
await client.call_tool("compare_credit_methodologies", {
    "class_ids": ["C01", "C02", "C03"]
})

Using With ChatGPT Custom GPT Actions (OpenAPI)

OpenAI Custom GPT Actions enforce a maximum of 30 operations per OpenAPI spec, and Action sets cannot include duplicate domains. This repo supports a two-Action setup:

Ledger Action (on-chain): upload openapi-gpt-ledger.json with server https://regen.gaiaai.xyz (25 ops, /regen-api/* only)
KOI Action (knowledge): upload openapi-gpt-koi.json with server https://registry.regen.gaiaai.xyz (4 ops, /api/koi/* only)

To regenerate the GPT/Full + split Action specs deterministically:

python3 scripts/generate_openapi_schemas.py
python3 scripts/validate_openapi_gpt.py --strict

Recommended instruction text for the GPT lives in:

gpt-instructions.md
gpt-knowledge.md

Architecture

regen-python-mcp/
├── main.py                      # Entry point
├── requirements.txt             # Python dependencies
├── docs/                        # Documentation
│   ├── regen_mcp_thesis.md     # Vision and use cases
│   └── regen_network_exploration_report.md
├── tests/                       # Test suite
├── archive/                     # Archived exploratory code
└── src/
    └── mcp_server/
        ├── server.py            # Main MCP server (45 tools, 8 prompts)
        ├── client/              # Regen Network API client
        ├── config/              # Configuration management
        ├── models/              # Pydantic data models
        ├── tools/               # Tool implementations by module
        ├── prompts/             # Interactive prompt guides
        ├── resources/           # Dynamic resource handlers
        ├── cache/               # Caching layer
        ├── monitoring/          # Health and metrics
        └── scrapers/            # Data collection utilities

Design Principles

Modular Organization: Tools grouped by blockchain module for maintainability
Type Safety: Pydantic models throughout for runtime validation
Async-First: All I/O operations use async/await patterns
Graceful Degradation: Optional modules with fallback behavior
Configuration-Driven: Environment variables for deployment flexibility

Tool Reference

Bank Module (11 tools)

list_accounts, get_account, get_balance, get_all_balances
get_spendable_balances, get_total_supply, get_supply_of
get_bank_params, get_denoms_metadata, get_denom_metadata, get_denom_owners

Distribution Module (9 tools)

get_distribution_params, get_validator_outstanding_rewards
get_validator_commission, get_validator_slashes
get_delegation_rewards, get_delegation_total_rewards
get_delegator_validators, get_delegator_withdraw_address, get_community_pool

Governance Module (8 tools)

get_governance_proposal, list_governance_proposals
get_governance_vote, list_governance_votes
list_governance_deposits, get_governance_params
get_governance_deposit, get_governance_tally_result

Marketplace Module (5 tools)

get_sell_order, list_sell_orders
list_sell_orders_by_batch, list_sell_orders_by_seller, list_allowed_denoms

Ecocredits Module (4 tools)

list_credit_types, list_classes, list_projects, list_credit_batches

Baskets Module (5 tools)

list_baskets, get_basket, list_basket_balances
get_basket_balance, get_basket_fee

Analytics Module (3 tools)

analyze_portfolio_impact, analyze_market_trends, compare_credit_methodologies

Development

Setup Development Environment

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in editable mode
pip install -e .

# Install development dependencies
pip install pytest black mypy ruff

Running Tests

# Run all tests
pytest tests/

# Run with coverage
pytest --cov=src/mcp_server tests/

# Run specific test file
pytest tests/test_prompts.py -v

Code Quality

# Format code
black src/

# Type checking
mypy src/

# Linting
ruff check src/

Documentation

Prompts Guide: Complete guide to interactive prompts
Thesis Document: Vision, use cases, and impact potential
Exploration Report: Technical deep-dive
Configuration: All configuration options

Use Cases

For AI Agents

Autonomous environmental market analysis
Automated portfolio optimization
Real-time credit price discovery
Methodology comparison and selection

For Developers

Building eco-finance applications
Integrating Regen data into dashboards
Creating custom analytics tools
Prototyping new market mechanisms

For Researchers

Environmental credit market analysis
Methodology effectiveness studies
Market liquidity and pricing research
Impact verification and tracking

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Regen Network - For building the ecological credit infrastructure
Anthropic - For the Model Context Protocol specification
The open source community

Links

Built with 🌱 for a regenerative future