AgentRoute Oracle MCP Server

Model Context Protocol (MCP) integration for AgentRoute Oracle

This MCP server enables AI agents (Claude, GPT, etc.) to discover and use AgentRoute Oracle's Lightning routing optimization capabilities.

What is MCP?

Model Context Protocol (MCP) is a standard protocol that allows AI agents to discover and use external tools. Think of it as a universal plug-and-play system for agent integrations.

With this MCP server, agents can:

• Discover AgentRoute Oracle capabilities
• Call routing functions directly
• Integrate without custom code
• Use across any MCP-compatible framework

Features

🔌 Four Core Tools

1. find_optimal_route - Find the best Lightning path for a Bitcoin transfer
2. get_route_alternatives - Get multiple route options for redundancy
3. estimate_route_fee - Estimate fees without executing
4. get_network_status - Check Lightning Network health

⚡ Agent-Friendly

• Simple, intuitive tool interface
• Clear descriptions and examples
• Automatic error handling
• L402 payment integration

🔒 Secure

• L402 protocol support
• Token-based authentication
• No private key exposure
• Non-custodial by design

Installation

Prerequisites

• Node.js 18+ or Python 3.8+
• AgentRoute Oracle API access
• L402 token (optional, for authenticated requests)

Setup

# Clone the repository
git clone https://github.com/Bitlatethenever/agentroute-mcp.git
cd agentroute-mcp

# Install dependencies
npm install

# Build
npm run build

# Start the server
npm start

Environment Variables

# Optional: Set custom API endpoint
export AGENTROUTE_API_URL=https://agentroute-oracle.onrender.com

# Optional: Set L402 token for authenticated requests
export L402_TOKEN=your_l402_token_here

Usage

With Claude Desktop

1. Add to Claude Desktop config:

{
  "mcpServers": {
    "agentroute": {
      "command": "node",
      "args": ["/path/to/agentroute-mcp/build/index.js"]
    }
  }
}

2. Restart Claude Desktop

3. Use in Claude:

Find the optimal Lightning route to send 5000 sats from my wallet to recipient's wallet.

Claude will automatically use the AgentRoute Oracle MCP tool.

With Other Agents

The MCP server works with any MCP-compatible framework:

• LangChain
• AutoGPT
• CrewAI
• Custom agents

Tool Reference

find_optimal_route

Find the optimal Lightning Network route for a Bitcoin transfer.

Parameters:

• source (string, required): Source wallet ID or node public key
• destination (string, required): Destination wallet ID or node public key
• amount_sats (number, required): Amount to send in satoshis
• timeout_seconds (number, optional): Timeout in seconds (default: 30)

Response:

{
  "success": true,
  "route_id": "route_abc123",
  "hops": 3,
  "fee_sats": 15,
  "success_probability": 0.95,
  "route_details": [
    {
      "hop": 1,
      "node": "03...",
      "channel": "123456:1:0",
      "fee_sats": 5
    }
  ],
  "timestamp": "2026-04-02T21:00:00Z"
}

get_route_alternatives

Get alternative Lightning routes for comparison and redundancy.

Parameters:

• source (string, required): Source wallet ID or node public key
• destination (string, required): Destination wallet ID or node public key
• amount_sats (number, required): Amount to send in satoshis
• limit (number, optional): Number of alternatives to return (default: 3)

Response:

{
  "success": true,
  "alternatives": [
    { "route_id": "route_1", "fee_sats": 15, "hops": 3 },
    { "route_id": "route_2", "fee_sats": 18, "hops": 4 },
    { "route_id": "route_3", "fee_sats": 12, "hops": 2 }
  ],
  "count": 3
}

estimate_route_fee

Estimate the fee for a route without executing the transaction.

Parameters:

• source (string, required): Source wallet ID or node public key
• destination (string, required): Destination wallet ID or node public key
• amount_sats (number, required): Amount to send in satoshis

Response:

{
  "success": true,
  "estimated_fee_sats": 15,
  "total_with_fee": 5015,
  "success_probability": 0.95
}

get_network_status

Get current Lightning Network status and health metrics.

Parameters: None

Response:

{
  "success": true,
  "network_status": {
    "active_channels": 45000,
    "total_capacity_sats": 2500000000,
    "average_fee_rate": 0.0001,
    "network_health": "healthy"
  }
}

Development

Build

npm run build

Development Mode

npm run dev

Testing

npm test

Integration Examples

LangChain Integration

from langchain.agents import Tool
from langchain_community.tools.mcp import MCPTool

# Load MCP tools
mcp_tool = MCPTool.from_mcp_server(
    server_params={"command": "node", "args": ["path/to/build/index.js"]}
)

# Use in agent
tools = [mcp_tool]
agent = initialize_agent(tools, llm, agent_type="zero-shot-react-description")

Direct API Usage

import axios from 'axios';

const response = await axios.post(
  'https://agentroute-oracle.onrender.com/route',
  {
    source: 'wallet_id_1',
    destination: 'wallet_id_2',
    amount_sats: 5000
  },
  {
    headers: {
      'Authorization': 'L402 <token>',
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.data);

Pricing

AgentRoute Oracle uses L402 micropayments:

• 10-30 sats per query (approximately $0.003-$0.009)
• No subscriptions - Pay only for what you use
• Transparent pricing - No hidden fees
• Dynamic pricing - Based on network demand

Error Handling

The MCP server handles errors gracefully:

{
  "error": "Route not found",
  "code": "ROUTE_NOT_FOUND",
  "message": "No route found between source and destination"
}

Common error codes:

• ROUTE_NOT_FOUND - No route exists between source and destination
• PAYMENT_REQUIRED - L402 payment required
• INVALID_REQUEST - Invalid parameters
• TIMEOUT - Request timed out

Security

Best Practices

• ✅ Never commit L402 tokens to version control
• ✅ Use environment variables for sensitive data
• ✅ Validate all input parameters
• ✅ Use HTTPS for all API calls
• ✅ Implement rate limiting on your end

L402 Protocol

AgentRoute Oracle uses the L402 protocol for secure micropayments:

• Automatic payment handling
• No private key exposure
• Non-custodial by design
• Lightning Network native

Troubleshooting

Server won't start

# Check Node.js version
node --version  # Should be 18+

# Check dependencies
npm install

# Try building again
npm run build

Connection errors

# Verify API endpoint
echo $AGENTROUTE_API_URL

# Test connectivity
curl https://agentroute-oracle.onrender.com/health

L402 payment errors

# Verify L402 token
echo $L402_TOKEN

# Check token validity
# Token should be in format: <macaroon>:<preimage>

Contributing

We welcome contributions! Areas we're looking for:

• Additional routing tools
• Language-specific clients
• Integration examples
• Documentation improvements
• Bug reports and fixes

See CONTRIBUTING.md for details.

Resources

• AgentRoute Oracle: https://agentroute-yvqamn6m.manus.space
• MCP Documentation: https://modelcontextprotocol.io/
• L402 Protocol: https://github.com/lightningnetwork/lnd/wiki/L402
• Claude Desktop MCP: https://github.com/anthropics/claude-desktop-config

License

MIT License - See LICENSE file for details.

Support

• GitHub Issues: Report bugs and request features
• Email: [email protected]
• Twitter: @AgentRouteOracle
• Discord: Coming soon

Acknowledgments

Built with gratitude for:

• The Bitcoin community
• Lightning Labs and the Lightning Network
• Anthropic and the MCP protocol
• The agent economy builders

Built for agents. By builders. ⚡

The future is AI. The future is Bitcoin. We're building the bridge.