Kleros MCP Server

A Model Context Protocol (MCP) server that retrieves comprehensive Kleros court dispute data including meta-evidence and evidence submissions from multiple blockchain networks.

Features

• 🔗 Multi-chain Support: Ethereum Mainnet and Gnosis Chain
• 📊 Comprehensive Data: Meta-evidence, evidence submissions, and IPFS content
• 🌐 Remote Hosting Ready: Streamable HTTP transport with session management
• 🔒 Secure: DNS rebinding protection and proper CORS configuration
• ⚡ Fast: Parallel IPFS content retrieval with error handling
• 📱 Claude Desktop Compatible: Direct URL integration

Supported Networks

• Ethereum Mainnet (chainId: 1)
• Gnosis Chain (chainId: 100)

Data Sources

• Meta-evidence API: Kleros dispute metadata
• Ethereum Subgraph: Evidence submissions on Ethereum
• Gnosis Subgraph: Evidence submissions on Gnosis Chain
• IPFS Gateway: Evidence content via Kleros CDN

Claude Desktop Integration

Easy Setup (Recommended)

1. Open Claude Desktop Settings

   • Click on Settings in the sidebar

2. Go to Connectors

   • Navigate to Settings → Connectors

3. Add Custom Connector

   • Click "Add custom connector"
   • Enter a name: Kleros Court
   • Paste the URL: https://kleros-mcp-server-new.fly.dev/mcp
   • Click "Add"

4. Start Using
   • The Kleros Court tool will now be available in Claude Desktop
   • Try: "Get dispute data for dispute ID 481 on Gnosis Chain"

Alternative Configuration File Method

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "kleros": {
      "url": "https://kleros-mcp-server-new.fly.dev/mcp"
    }
  }
}

MCP Tool

get_dispute_data

Retrieves comprehensive dispute data from Kleros including meta-evidence and evidence submissions.

Parameters:

• disputeId (string): The dispute ID to retrieve data for
• chainId (number): The chain ID (1 for Ethereum, 100 for Gnosis)

Example Usage:

• "Get dispute data for dispute ID 123 on Ethereum"
• "Show me details for dispute 481 on Gnosis Chain"
• "Retrieve evidence for dispute 50 on chain 100"

Sample Response:

# Kleros Dispute Data

**Dispute ID:** 481
**Chain:** Gnosis Chain (100)

## Meta-Evidence
**Title:** Web3 Security Auditor Registry
**Description:** A curated registry of verified security auditors...

## Evidence Submissions (3)

### Evidence 1
**Title:** Challenge Justification
**Description:** Pokémon is not a web3 auditor, reject the submission.
**Type:** text/plain

Quick Start

Prerequisites

• Node.js 18.x or higher
• npm or yarn

Local Development

1. Clone and install dependencies:

   git clone <your-repo>
   cd kleros-mcp-server
   npm install
   

2. Build the project:

   npm run build
   

3. Start the server:

   npm start
   

4. Health check:

   curl http://localhost:8080/health
   

Development Mode

For development with auto-restart:

npm run dev

Deployment

Fly.io Deployment

1. Install Fly CLI:

   curl -L https://fly.io/install.sh | sh
   

2. Login to Fly:

   fly auth login
   

3. Create app (update app name in fly.toml if needed):

   fly apps create kleros-mcp-server-new
   

4. Build and deploy:

   npm run build
   fly deploy
   

5. Check deployment:

   fly status
   fly logs
   

Your MCP server will be available at: https://kleros-mcp-server-new.fly.dev/mcp

Environment Variables

Set any required environment variables:

fly secrets set ALLOWED_HOSTS=your-domain.com

API Endpoints

Health Check

GET /health

Returns server status and timestamp.

MCP Protocol

POST /mcp
GET /mcp (for SSE notifications)
DELETE /mcp (for session termination)

Main MCP protocol endpoints with session management.

Architecture

kleros-mcp-server/
├── src/
│   ├── index.ts              # Express server with Streamable HTTP transport
│   ├── server.ts             # MCP server setup and tool registration
│   ├── services/
│   │   ├── disputeService.ts # Main dispute data coordination
│   │   ├── metaEvidenceService.ts # Meta-evidence API integration
│   │   ├── subgraphService.ts     # Subgraph queries
│   │   └── ipfsService.ts         # IPFS content retrieval
│   ├── types/
│   │   └── index.ts          # TypeScript type definitions
│   └── utils/
│       └── constants.ts      # API endpoints and configuration
├── Dockerfile                # Container configuration
├── fly.toml                  # Fly.io deployment configuration
└── package.json

Error Handling

The server includes comprehensive error handling:

• Network timeouts: 10-15 second timeouts for external APIs
• IPFS failures: Graceful handling of unreachable content
• Subgraph errors: Detailed error reporting for query failures
• Input validation: Proper validation of dispute IDs and chain IDs

Development

Adding New Chains

1. Add chain ID to SUPPORTED_CHAIN_IDS in src/types/index.ts
2. Add subgraph URL to API_ENDPOINTS.SUBGRAPHS in src/utils/constants.ts
3. Add network name to NETWORK_NAMES in src/utils/constants.ts

Testing

Test the dispute data retrieval:

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_dispute_data",
      "arguments": {
        "disputeId": "123",
        "chainId": 1
      }
    },
    "id": 1
  }'

MCP Inspector Compliance

This server passes all MCP Inspector checks:

• ✅ Proper protocol implementation
• ✅ Correct message formatting
• ✅ Standard error codes
• ✅ Session management
• ✅ Resource cleanup

Security

• DNS rebinding protection enabled
• CORS properly configured
• Non-root container user
• Input validation and sanitization
• Graceful error handling without information leakage

Troubleshooting

Common Issues

1. 404 Subgraph Errors: Check if subgraph URLs are up to date
2. IPFS Timeout: Evidence content may be temporarily unavailable
3. Invalid Dispute ID: Ensure the dispute exists on the specified chain

Getting Help

• Check server health: curl https://kleros-mcp-server-new.fly.dev/health
• View logs: fly logs (for deployed version)
• Test locally: npm run dev

License

MIT

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

Support

For issues and questions:

• Create an issue in the repository
• Check the logs: fly logs (for deployed version)
• Verify health: curl https://kleros-mcp-server-new.fly.dev/health