Skip to main content
Glama

Shark MCP - AI Agent Microloan Server

by solumos

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

TierMin Successful LoansMax Credit Limit
Starter0$1.00
Bronze3$2.50
Silver10$5.00
Gold25$10.00
Platinum50$25.00
Diamond100$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.

-
security - not tested
F
license - not found
-
quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables AI agents to request and manage microloans for HTTP 402 Payment Required transactions. Provides automated underwriting, credit management, and USDC disbursement with progressive credit limits based on repayment history.

  1. Features
    1. MCP Tools Available
      1. Quick Start
        1. 1. Setup Database
        2. 2. Configure Alchemy for USDC Transfers
        3. 3. Install Dependencies
        4. 4. Run Database Migrations
        5. 5. Start the Server
        6. 6. Access MCP Server
      2. Architecture
        1. Core Components
        2. Database Models
        3. Credit Tiers
      3. Usage Example
        1. For AI Agents
        2. For Administrators
      4. Development
        1. Running Tests
        2. Code Formatting
        3. Type Checking
      5. Security
        1. Contributing
          1. License

            Related MCP Servers

            • -
              security
              A
              license
              -
              quality
              Enables AI models to interact with the Lightning Network by providing an MCP-compliant API to pay invoices.
              Last updated -
              3
              3
              TypeScript
              MIT License
            • -
              security
              F
              license
              -
              quality
              An MCP server that enables AI assistants to interact with Flutterwave payment services, providing tools for transaction management, payment link generation, and automated customer support.
              Last updated -
              TypeScript
            • A
              security
              F
              license
              A
              quality
              A server that provides easy access to Payman AI's APIs, allowing users to create payees, search payees, send payments, and check balances using natural language prompts.
              Last updated -
              5
              3
              JavaScript
              • Apple
            • -
              security
              F
              license
              -
              quality
              A Model Context Protocol server that connects to a payments company's developer portal, providing AI assistants with access to payment documentation, APIs, and guides.
              Last updated -
              JavaScript

            View all related MCP servers

            MCP directory API

            We provide all the information about MCP servers via our MCP API.

            curl -X GET 'https://glama.ai/api/mcp/v1/servers/solumos/shark-mcp'

            If you have feedback or need assistance with the MCP directory API, please join our Discord server