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:

Get an Alchemy API Key:
- Sign up at Alchemy
- Create a new app for Ethereum mainnet
- Copy your API key
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
Configure Environment Variables:
# Add to your .env file ALCHEMY_API_KEY=your_alchemy_api_key_here VAULT_PRIVATE_KEY=your_vault_private_key_here
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

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

License

MIT License - see LICENSE file for details.

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

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.

Related MCP Servers

Lightning Network MCP Server
AbdelStark
-
security
A
license
-
quality
Enables AI models to interact with the Lightning Network by providing an MCP-compliant API to pay invoices.
Last updated -
15
4
MIT License
Flutterwave MCP Server
bajoski34
-
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
Payman AI MCP Server
hrishi0102
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 -
7
3
Payments Developer Portal MCP Server
PraveenJoshua23
-
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 -

View all related MCP servers

Shark MCP - AI Agent Microloan Server