ICON MCP v101 MCP Server

ICON MCP v101 MCP Server

This is an MCP (Model Context Protocol) server that provides with authentication via Bearer tokens access to the ICON MCP v101 API. It enables AI agents and LLMs to interact with ICON MCP v101 through standardized tools.

Features

• 🔧 MCP Protocol: Built on the Model Context Protocol for seamless AI integration
• 🌐 Full API Access: Provides tools for interacting with ICON MCP v101 endpoints
• 🔐 Secure Authentication: Supports API key authentication via Bearer tokens
• 💳 HTTP 402 Payment Protocol: Dual-mode operation (authenticated or paid access)
• 🔗 D402 Integration: Uses traia_iatp.d402 for blockchain payment verification
• 🐳 Docker Support: Easy deployment with Docker and Docker Compose
• ⚡ Async Operations: Built with FastMCP for efficient async handling

API Documentation

• ICON MCP v101 Website: https://pro-api.coinmarketcap.com
• API Documentation:

Available Tools

This server provides the following tools:

• example_tool: Placeholder tool (to be implemented)

Note: Replace example_tool with actual ICON MCP v101 API tools based on the documentation.

Installation

Using Docker (Recommended)

1. Clone this repository:

   git clone https://github.com/Traia-IO/icon-mcp-v101-mcp-server.git
   cd icon-mcp-v101-mcp-server
   

2. Set your API key:

   export ICON_MCP_V101_API_KEY="your-api-key-here"
   

3. Run with Docker:

   ./run_local_docker.sh
   

Using Docker Compose

1. Create a .env file with your configuration:

Server's internal API key (for payment mode)

ICON_MCP_V101_API_KEY=your-api-key-here

Server payment address (for HTTP 402 protocol)

SERVER_ADDRESS=0x1234567890123456789012345678901234567890

Operator keys (for signing settlement attestations)

MCP_OPERATOR_PRIVATE_KEY=0x1234567890abcdef... MCP_OPERATOR_ADDRESS=0x9876543210fedcba...

Optional: Testing mode (skip settlement for local dev)

D402_TESTING_MODE=false PORT=8000

2. Start the server:
```bash
docker-compose up

Manual Installation

1. Install dependencies using uv:

   uv pip install -e .
   

2. Run the server:

ICON_MCP_V101_API_KEY="your-api-key-here" uv run python -m server

## Usage

### Health Check

Test if the server is running:
```bash
python mcp_health_check.py

Using with CrewAI

from traia_iatp.mcp.traia_mcp_adapter import create_mcp_adapter_with_auth

# Connect with authentication
with create_mcp_adapter_with_auth(
    url="http://localhost:8000/mcp/",
    api_key="your-api-key"
) as tools:
    # Use the tools
    for tool in tools:
        print(f"Available tool: {tool.name}")
        
    # Example usage
    result = await tool.example_tool(query="test")
    print(result)

Authentication & Payment (HTTP 402 Protocol)

This server supports two modes of operation:

Mode 1: Authenticated Access (Free)

Clients with their own ICON MCP v101 API key can use the server for free:

# Request with client's API key
curl -X POST http://localhost:8000/mcp \
  -H "Authorization: Bearer CLIENT_ICON_MCP_V101_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method":"tools/call","params":{"name":"example_tool","arguments":{"query":"test"}}}'

Flow:

1. Client provides their ICON MCP v101 API key
2. Server uses client's API key to call ICON MCP v101 API
3. No payment required
4. Client pays ICON MCP v101 directly

Mode 2: Payment Required (Paid Access)

Clients without an API key can pay-per-use via HTTP 402 protocol:

# Request with payment proof (x402/d402 protocol)
curl -X POST http://localhost:8000/mcp \
  -H "X-PAYMENT: <base64_encoded_x402_payment>" \
  -H "Content-Type: application/json" \
  -d '{"method":"tools/call","params":{"name":"example_tool","arguments":{"query":"test"}}}'

Flow:

1. Client makes initial request without payment
2. Server returns HTTP 402 with PaymentRequirements (token, network, amount)
3. Client creates EIP-3009 transferWithAuthorization payment signature
4. Client base64-encodes payment and sends in X-PAYMENT header
5. Server verifies payment via traia_iatp.d402.mcp_middleware
6. Server uses its INTERNAL ICON MCP v101 API key to call the API
7. Client receives result

D402 Protocol Details

This server uses the traia_iatp.d402 module for payment verification:

• Payment Method: EIP-3009 transferWithAuthorization (gasless)
• Supported Tokens: USDC, TRAIA, or any ERC20 token
• Default Price: $0.001 per request (configurable via DEFAULT_PRICE_USD)
• Networks: Base Sepolia, Sepolia, Polygon, etc.
• Facilitator: d402.org (public) or custom facilitator

Environment Variables for Payment Mode

# Required
ICON_MCP_V101_API_KEY=your_internal_icon-mcp-v101_api_key  # Server's API key (for payment mode)
SERV