Shark MCP - AI Agent Microloan Server

An MCP (Model Context Protocol) server for providing microloans to AI agents for x402 transactions. Built with FastAPI and FastMCP, this server enables AI agents to request small loans to pay for HTTP 402 Payment Required transactions.

Features

• Agent Registration: Whitelist-based registration with wallet address verification
• Microloan Processing: Automated underwriting and disbursement for small loans (<$1 initially)
• x402 Integration: Automatic payment of x402 transactions on behalf of agents
• Credit Management: Progressive credit limits based on repayment history
• Risk Assessment: Comprehensive credit scoring and risk evaluation
• Automated Collections: Overdue loan detection and collection processes
• MCP Tools: Rich set of tools for AI agents to interact with the loan system

MCP Tools Available

• request_loan(wallet_address, amount, purpose?, x402_url?) - Request a microloan
• check_credit_limit(wallet_address) - Check available credit and limits
• repay_loan(loan_id, amount, payment_hash?) - Repay a loan
• get_loan_status(loan_id) - Get detailed loan information
• list_agent_loans(wallet_address) - List all loans for an agent
• register_agent(wallet_address, signature, message?) - Register as a new agent

Quick Start

1. Setup Database

# Create PostgreSQL database
createdb shark_mcp

# Copy environment file
cp .env.example .env
# Edit .env with your database credentials

2. Configure Alchemy for USDC Transfers

To enable real USDC transfers (instead of mock transactions), you need to configure Alchemy:

1. Get an Alchemy API Key:

   • Sign up at Alchemy
   • Create a new app for Ethereum mainnet
   • Copy your API key

2. Set up a Vault Wallet:

   • Create a new Ethereum wallet to hold USDC for disbursements
   • Fund it with USDC and some ETH for gas fees
   • Export the private key

3. Configure Environment Variables:

   # Add to your .env file
   ALCHEMY_API_KEY=your_alchemy_api_key_here
   VAULT_PRIVATE_KEY=your_vault_private_key_here
   

4. Update USDC Contract Address:

   • In src/shark_mcp/mcp_server.py, replace the placeholder USDC contract address with the real one:

   # Real USDC address on Ethereum mainnet
   usdc_contract_address = "0xA0b86a33E6441b8C4C8C8C8C8C8C8C8C8C8C8C8C"
   

Note: The system uses web3.py with Alchemy's HTTP provider for blockchain interactions. Without these configurations, the system will use mock transactions for demonstration purposes.

3. Install Dependencies

pip install -e .

4. Run Database Migrations

alembic upgrade head

5. Start the Server

# Development
python -m shark_mcp.main

# Production
uvicorn shark_mcp.main:app --host 0.0.0.0 --port 8000

6. Access MCP Server

The MCP server is available at: http://localhost:8000/mcp

API documentation: http://localhost:8000/docs

Architecture

Core Components

• Agent Management: Registration, whitelisting, and wallet verification
• Loan Processing: Underwriting, disbursement, and repayment tracking
• Credit Assessment: Risk scoring and credit limit progression
• Collection System: Automated overdue detection and collection
• x402 Integration: Automatic payment of HTTP 402 transactions

Database Models

• Agent: Stores agent information and credit profiles
• Loan: Individual loan records with status tracking
• Transaction: Payment and repayment transaction history
• AuditLog: Comprehensive audit trail for all actions

Credit Tiers

Tier	Min Successful Loans	Max Credit Limit
Starter	0	$1.00
Bronze	3	$2.50
Silver	10	$5.00
Gold	25	$10.00
Platinum	50	$25.00
Diamond	100	$50.00

Usage Example

For AI Agents

# Register as an agent
result = await mcp.call_tool("register_agent", {
    "wallet_address": "0x1234...",
    "signature": "0xabcd...",
    "message": "Register for Shark MCP microloans"
})

# Check credit limit
credit_info = await mcp.call_tool("check_credit_limit", {
    "wallet_address": "0x1234..."
})

# Request a loan for x402 transaction
loan = await mcp.call_tool("request_loan", {
    "wallet_address": "0x1234...",
    "amount": 0.50,
    "purpose": "Payment for API access",
    "x402_url": "https://api.example.com/data"
})

# Repay the loan
repayment = await mcp.call_tool("repay_loan", {
    "loan_id": loan["loan_id"],
    "amount": 0.50,
    "payment_hash": "0x5678..."
})

For Administrators

# Whitelist an agent
curl -X POST "http://localhost:8000/api/v1/agents/whitelist" \
  -H "Content-Type: application/json" \
  -d '{"wallet_address": "0x1234...", "admin_id": "admin123"}'

# Get collection report
curl "http://localhost:8000/api/v1/admin/collection-report"

Development

Running Tests

pytest

Code Formatting

black src/
ruff check src/

Type Checking

mypy src/

Security

• All agents must provide cryptographic signatures proving wallet ownership
• Whitelist-based access control for loan eligibility
• Comprehensive audit logging for all operations
• Automated risk assessment and credit scoring
• Progressive credit limits based on payment history

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.