agenticbtc-mcp 1.0.1 → 1.0.3

package/bin/agentbtc.js

@@ -17,7 +17,6 @@ function getClaudeConfigPath() {
   } else if (platform === "win32") {
     return join(process.env.APPDATA || join(homedir(), "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
   } else {
-    // Linux/other
     return join(homedir(), ".config", "claude", "claude_desktop_config.json");
   }
 }
@@ -51,11 +50,10 @@ async function checkApi(apiUrl, apiKey) {
 
 // Commands
 async function setup() {
-  console.log("🚀 AgentBTC Setup\n");
+  console.log("🚀 AgenticBTC Setup\n");
   
-  // Get configuration from user
-  const apiUrl = await prompt(`AgentBTC API URL (http://localhost:8000): `) || "http://localhost:8000";
-  const apiKey = await prompt("AgentBTC API Key: ");
+  const apiUrl = await prompt(`AgenticBTC API URL (https://agenticbtc.app): `) || "https://agenticbtc.app";
+  const apiKey = await prompt("AgenticBTC API Key: ");
   
   if (!apiKey) {
     console.log("❌ API Key is required");
@@ -82,7 +80,6 @@ async function setup() {
   const configPath = getClaudeConfigPath();
   let config = { mcpServers: {} };
   
-  // Load existing config if it exists
   if (existsSync(configPath)) {
     try {
       const existing = readFileSync(configPath, "utf8");
@@ -95,25 +92,25 @@ async function setup() {
     }
   }
   
-  // Add AgentBTC server config
+  // Add AgenticBTC server config
   const serverConfig = {
     command: "npx",
-    args: ["agentbtc", "server"],
+    args: ["agenticbtc-mcp", "server"],
     env: {
-      AGENTBTC_API_URL: apiUrl,
-      AGENTBTC_API_KEY: apiKey,
+      AGENTICBTC_API_URL: apiUrl,
+      AGENTICBTC_API_KEY: apiKey,
       NODE_TLS_REJECT_UNAUTHORIZED: "0"
     }
   };
   
   if (lndHost) {
-    serverConfig.env.AGENTBTC_LND_HOST = lndHost;
+    serverConfig.env.AGENTICBTC_LND_HOST = lndHost;
   }
   if (lndMacaroon) {
-    serverConfig.env.AGENTBTC_LND_MACAROON = lndMacaroon;
+    serverConfig.env.AGENTICBTC_LND_MACAROON = lndMacaroon;
   }
   
-  config.mcpServers.agentbtc = serverConfig;
+  config.mcpServers.agenticbtc = serverConfig;
   
   // Create config directory if needed
   try {
@@ -137,25 +134,23 @@ async function setup() {
   }
   
   console.log("\n🎉 Setup complete!");
-  console.log("💡 Restart Claude Desktop to load the AgentBTC server.");
-  console.log("🔧 Test with: agentbtc status");
+  console.log("💡 Restart Claude Desktop to load the AgenticBTC MCP server.");
+  console.log("🔧 Test with: npx agenticbtc-mcp status");
 }
 
 async function status() {
-  const apiUrl = process.env.AGENTBTC_API_URL || "http://localhost:8000";
-  const apiKey = process.env.AGENTBTC_API_KEY || "";
-  const lndHost = process.env.AGENTBTC_LND_HOST || "";
+  const apiUrl = process.env.AGENTICBTC_API_URL || process.env.AGENTBTC_API_URL || "https://agenticbtc.app";
+  const apiKey = process.env.AGENTICBTC_API_KEY || process.env.AGENTBTC_API_KEY || "";
+  const lndHost = process.env.AGENTICBTC_LND_HOST || process.env.AGENTBTC_LND_HOST || "";
   
-  console.log("📊 AgentBTC Status\n");
+  console.log("📊 AgenticBTC Status\n");
   
-  // Configuration
   console.log("Configuration:");
   console.log(`  API URL: ${apiUrl}`);
   console.log(`  API Key: ${apiKey ? "✅ Set" : "❌ Not set"}`);
   console.log(`  LND Host: ${lndHost || "❌ Not configured"}`);
-  console.log(`  LND Macaroon: ${process.env.AGENTBTC_LND_MACAROON ? "✅ Set" : "❌ Not set"}`);
+  console.log(`  LND Macaroon: ${(process.env.AGENTICBTC_LND_MACAROON || process.env.AGENTBTC_LND_MACAROON) ? "✅ Set" : "❌ Not set"}`);
   
-  // API connectivity
   console.log("\n🔄 Testing API connection...");
   const apiTest = await checkApi(apiUrl, apiKey);
   if (apiTest.ok) {
@@ -167,12 +162,12 @@ async function status() {
     }
   }
   
-  // LND connectivity (if configured)
-  if (lndHost && process.env.AGENTBTC_LND_MACAROON) {
+  if (lndHost && (process.env.AGENTICBTC_LND_MACAROON || process.env.AGENTBTC_LND_MACAROON)) {
+    const macaroon = process.env.AGENTICBTC_LND_MACAROON || process.env.AGENTBTC_LND_MACAROON;
     console.log("\n🔄 Testing LND connection...");
     try {
       const lndRes = await fetch(`${lndHost}/v1/getinfo`, {
-        headers: { "Grpc-Metadata-macaroon": process.env.AGENTBTC_LND_MACAROON }
+        headers: { "Grpc-Metadata-macaroon": macaroon }
       });
       if (lndRes.ok) {
         const lndData = await lndRes.json();
@@ -187,52 +182,52 @@ async function status() {
     }
   }
   
-  // Claude Desktop config
   const configPath = getClaudeConfigPath();
   console.log(`\n🔧 Claude Desktop config: ${configPath}`);
   if (existsSync(configPath)) {
     try {
       const config = JSON.parse(readFileSync(configPath, "utf8"));
-      if (config.mcpServers?.agentbtc) {
-        console.log("✅ AgentBTC server configured in Claude Desktop");
+      if (config.mcpServers?.agenticbtc) {
+        console.log("✅ AgenticBTC server configured in Claude Desktop");
+      } else if (config.mcpServers?.agentbtc) {
+        console.log("⚠️  Old AgentBTC config found — run 'npx agenticbtc-mcp start' to upgrade");
       } else {
-        console.log("⚠️  AgentBTC server not found in Claude Desktop config");
-        console.log("   Run: agentbtc setup");
+        console.log("⚠️  AgenticBTC server not found in Claude Desktop config");
+        console.log("   Run: npx agenticbtc-mcp start");
       }
     } catch (error) {
       console.log(`❌ Could not read config: ${error.message}`);
     }
   } else {
     console.log("❌ Claude Desktop config not found");
-    console.log("   Run: agentbtc setup");
+    console.log("   Run: npx agenticbtc-mcp start");
   }
 }
 
 function server() {
-  // Import and start the MCP server
   import("../src/server.js");
 }
 
 function help() {
   console.log(`
-🚀 AgentBTC - Bitcoin Lightning MCP Server for AI Agents
+🚀 AgenticBTC - Intelligent Payment Routing for AI Agents
 
 Usage:
-  agentbtc start          Get started with AgentBTC (interactive setup)
-  agentbtc setup          Interactive setup for Claude Desktop
-  agentbtc server         Start the MCP server (used by Claude Desktop)
-  agentbtc status         Check configuration and connectivity
-  agentbtc --help         Show this help message
+  npx agenticbtc-mcp start     Get started (interactive setup)
+  npx agenticbtc-mcp setup     Interactive setup for Claude Desktop
+  npx agenticbtc-mcp server    Start the MCP server (used by Claude Desktop)
+  npx agenticbtc-mcp status    Check configuration and connectivity
+  npx agenticbtc-mcp --help    Show this help message
 
 Examples:
-  npx agentbtc start      # Get started - first-time setup
-  agentbtc status         # Check if everything is working
+  npx agenticbtc-mcp start     # First-time setup
+  npx agenticbtc-mcp status    # Check if everything is working
 
 Environment Variables:
-  AGENTBTC_API_URL        AgentBTC API endpoint (default: http://localhost:8000)
-  AGENTBTC_API_KEY        AgentBTC API key (required)
-  AGENTBTC_LND_HOST       Lightning node REST API host (optional)
-  AGENTBTC_LND_MACAROON   Lightning node macaroon in hex (optional)
+  AGENTICBTC_API_URL        AgenticBTC API endpoint (default: https://agenticbtc.app)
+  AGENTICBTC_API_KEY        AgenticBTC API key (required)
+  AGENTICBTC_LND_HOST       Lightning node REST API host (optional)
+  AGENTICBTC_LND_MACAROON   Lightning node macaroon in hex (optional)
 
 More info: https://agenticbtc.app
 `);
@@ -257,6 +252,6 @@ switch (command) {
     break;
   default:
     console.log(`Unknown command: ${command}`);
-    console.log("Run 'agentbtc --help' for usage information.");
+    console.log("Run 'npx agenticbtc-mcp --help' for usage information.");
     process.exit(1);
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agenticbtc-mcp",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Privacy-intelligent payments for AI agents — your privacy, your choice. Universal payment router with Lightning, Strike, Coinbase, PayPal, Venmo support.",
   "keywords": [
     "bitcoin",
@@ -46,4 +46,4 @@
     "start": "node src/server.js",
     "test": "node bin/agenticbtc.js --help"
   }
-}
+}

package/src/server.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * AgentBTC MCP Server
+ * AgenticBTC MCP Server
  * Exposes Bitcoin payment capabilities to Claude Desktop via Model Context Protocol.
  */
 
@@ -73,22 +73,143 @@ async function apiCall(path, options = {}) {
   return { status: res.status, data };
 }
 
+// Helper: resolve agent by name or ID
+async function resolveAgent(nameOrId) {
+  const { status, data } = await apiCall(`/api/v1/admin/agents`);
+  if (status !== 200) return null;
+  const agents = Array.isArray(data) ? data : (data.agents || []);
+  // Try exact ID match first
+  let agent = agents.find(a => a.id === nameOrId);
+  if (!agent) {
+    // Try case-insensitive name match
+    const lower = nameOrId.toLowerCase();
+    agent = agents.find(a => a.name.toLowerCase() === lower);
+  }
+  if (!agent) {
+    // Try partial name match
+    const lower = nameOrId.toLowerCase();
+    agent = agents.find(a => a.name.toLowerCase().includes(lower));
+  }
+  return agent || null;
+}
+
+// Check spending policy before a payment
+async function checkSpendingPolicy(agentId, amountSats) {
+  try {
+    const { status, data } = await apiCall(`/api/v1/agents/${agentId}/spending-check?amount_sats=${amountSats}`);
+    if (status === 200) return data;
+    return { allowed: true, note: "Policy check unavailable — allowing" };
+  } catch (e) {
+    return { allowed: true, note: "Policy check failed — allowing" };
+  }
+}
+
+// Log a transaction after payment
+async function logTransaction(agentId, amountSats, destination, memo, status) {
+  try {
+    await apiCall(`/api/v1/agents/${agentId}/transactions`, {
+      method: "POST",
+      body: JSON.stringify({
+        type: "payment",
+        amount_sats: amountSats,
+        destination: destination,
+        memo: memo,
+        status: status,
+      }),
+    });
+  } catch (e) {
+    // Silent fail — don't block on logging
+  }
+}
+
+// Determine auth level from API key
+async function getAuthLevel() {
+  try {
+    const { status, data } = await apiCall("/api/v1/me");
+    if (status === 200) return data;
+    return { is_owner: true }; // Fallback if endpoint not available
+  } catch (e) {
+    return { is_owner: true };
+  }
+}
+
 // Tool: Get agent wallet balance
 server.tool(
   "get_agent_balance",
   "Get Bitcoin balance for an agent wallet",
-  { agent_id: z.string().describe("Agent wallet ID") },
+  { agent_id: z.string().describe("Agent wallet name or ID") },
   async ({ agent_id }) => {
-    const { status, data } = await apiCall(`/api/v1/agents/${agent_id}`);
-    if (status === 200) {
+    const agent = await resolveAgent(agent_id);
+    if (agent) {
       return {
         content: [{
           type: "text",
           text: JSON.stringify({
             success: true,
-            agent: data.name,
-            balance_sats: data.balance_sats || 0,
-            balance_btc: data.balance_btc || "0.00000000",
+            agent: agent.name,
+            agent_id: agent.id,
+            balance_sats: agent.balance_sats || 0,
+            balance_btc: ((agent.balance_sats || 0) / 100000000).toFixed(8),
+            enabled: agent.enabled,
+          }, null, 2),
+        }],
+      };
+    }
+    return { content: [{ type: "text", text: `Error: Agent '${agent_id}' not found` }] };
+  }
+);
+
+// Tool: List all agent wallets  
+server.tool(
+  "list_agent_wallets",
+  "List all agent wallets with their balances and status (agent key: own wallet only)",
+  {},
+  async () => {
+    // Check if using agent key — scope to own wallet
+    const auth = await getAuthLevel();
+    if (!auth.is_owner && auth.agent_id) {
+      const agent = await resolveAgent(auth.agent_id);
+      if (agent) {
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              success: true,
+              total_agents: 1,
+              note: "Agent key — showing own wallet only",
+              agents: [{
+                id: agent.id, name: agent.name,
+                balance_sats: agent.balance_sats || 0,
+                balance_btc: ((agent.balance_sats || 0) / 100000000).toFixed(8),
+                enabled: agent.enabled,
+              }],
+            }, null, 2),
+          }],
+        };
+      }
+    }
+    const { status, data } = await apiCall(`/api/v1/admin/agents`);
+    if (status === 200) {
+      const agentList = Array.isArray(data) ? data : (data.agents || []);
+      const agents = agentList.map(agent => ({
+        id: agent.id,
+        name: agent.name,
+        description: agent.description || "",
+        balance_sats: agent.balance_sats || 0,
+        balance_btc: ((agent.balance_sats || 0) / 100000000).toFixed(8),
+        enabled: agent.enabled,
+        created_at: agent.created_at,
+      }));
+      
+      return {
+        content: [{
+          type: "text", 
+          text: JSON.stringify({
+            success: true,
+            total_agents: agents.length,
+            enabled_agents: agents.filter(a => a.enabled).length,
+            total_balance_sats: agents.reduce((sum, a) => sum + a.balance_sats, 0),
+            agents: agents,
           }, null, 2),
         }],
       };
@@ -97,12 +218,16 @@ server.tool(
   }
 );
 
-// Tool: Create agent wallet
+// Tool: Create agent wallet (owner only)
 server.tool(
   "create_agent_wallet",
-  "Create a new Bitcoin wallet for an AI agent",
+  "Create a new Bitcoin wallet for an AI agent (owner access required)",
   { agent_name: z.string().describe("Name for the agent wallet") },
   async ({ agent_name }) => {
+    const auth = await getAuthLevel();
+    if (!auth.is_owner) {
+      return { content: [{ type: "text", text: "Error: Owner access required to create wallets" }] };
+    }
     const { status, data } = await apiCall("/api/v1/agents", {
       method: "POST",
       body: JSON.stringify({ name: agent_name }),
@@ -124,48 +249,161 @@ server.tool(
   }
 );
 
+// Tool: Create Lightning invoice
+server.tool(
+  "create_lightning_invoice",
+  "Create a Lightning Network invoice to receive Bitcoin payments",
+  {
+    amount_sats: z.number().describe("Amount in satoshis"),
+    description: z.string().optional().default("AgentBTC MCP payment").describe("Invoice description"),
+    agent: z.string().optional().describe("Agent wallet name or ID (optional)"),
+  },
+  async ({ amount_sats, description, agent }) => {
+    if (!LND_HOST) {
+      return { content: [{ type: "text", text: "Error: LND node not configured. Set AGENTBTC_LND_HOST environment variable." }] };
+    }
+
+    // Resolve agent if provided (for logging/tracking)
+    let agentName = null;
+    if (agent) {
+      const resolved = await resolveAgent(agent);
+      if (!resolved) {
+        return { content: [{ type: "text", text: `Error: Agent '${agent}' not found` }] };
+      }
+      agentName = resolved.name;
+    }
+
+    try {
+      // Create invoice directly via LND REST API
+      const res = await fetch(`${LND_HOST}/v1/invoices`, {
+        method: "POST",
+        headers: {
+          "Grpc-Metadata-macaroon": LND_MACAROON,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          value: amount_sats,
+          memo: description + (agentName ? ` [${agentName}]` : ""),
+          expiry: "3600",
+        }),
+      });
+      const data = await res.json();
+
+      if (res.ok && data.payment_request) {
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              success: true,
+              invoice: data.payment_request,
+              amount_sats: amount_sats,
+              description: description,
+              agent: agentName,
+              payment_hash: data.r_hash,
+              expires: "1 hour",
+            }, null, 2),
+          }],
+        };
+      }
+      return { content: [{ type: "text", text: `Error creating invoice: ${JSON.stringify(data)}` }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: `LND connection error: ${e.message}` }] };
+    }
+  }
+);
+
 // Tool: Pay Lightning invoice
 server.tool(
   "pay_lightning_invoice",
   "Pay a Lightning Network invoice using agent wallet funds",
   {
     invoice: z.string().describe("BOLT11 Lightning invoice to pay"),
+    agent: z.string().optional().describe("Agent wallet name or ID (for spending policy enforcement)"),
     fee_limit_sats: z.number().optional().default(100).describe("Max fee in sats"),
   },
-  async ({ invoice, fee_limit_sats }) => {
-    // Check routing status before paying
-    const routingStatus = await checkRoutingStatus();
-    if (routingStatus === "suspended") {
-      return { content: [{ type: "text", text: "⛔ Account suspended — routing verification failed. Contact support." }] };
+  async ({ invoice, agent, fee_limit_sats }) => {
+    if (!LND_HOST) {
+      return { content: [{ type: "text", text: "Error: LND node not configured. Set AGENTBTC_LND_HOST environment variable." }] };
     }
 
-    const { status, data } = await apiCall("/api/v1/invoices/pay", {
-      method: "POST",
-      body: JSON.stringify({ payment_request: invoice, fee_limit_sats }),
-    });
-    if (status === 201 || status === 200) {
-      // Report payment for routing verification
-      await reportPayment(
-        data.payment_hash,
-        data.amount_sats,
-        data.destination || "",
-        [BK_BLOCK_NODE_PUBKEY]
-      );
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({
-            success: true,
-            amount_sats: data.amount_sats,
-            platform_fee_sats: data.platform_fee_sats,
-            payment_hash: data.payment_hash,
-            status: data.status,
-            message: `Paid ${data.amount_sats} sats ⚡`,
-          }, null, 2),
-        }],
-      };
+    // Resolve agent for spending policy enforcement
+    let resolvedAgent = null;
+    if (agent) {
+      resolvedAgent = await resolveAgent(agent);
+      if (!resolvedAgent) {
+        return { content: [{ type: "text", text: `Error: Agent '${agent}' not found` }] };
+      }
+      if (!resolvedAgent.enabled) {
+        return { content: [{ type: "text", text: `Error: Agent '${resolvedAgent.name}' is disabled — payments blocked` }] };
+      }
+    }
+
+    // Auto-detect agent from API key auth level
+    if (!resolvedAgent) {
+      const auth = await getAuthLevel();
+      if (auth.agent_id) {
+        resolvedAgent = { id: auth.agent_id, name: auth.agent_name || auth.agent_id };
+      }
+    }
+
+    try {
+      // Decode invoice first to get amount for policy check
+      const decodeRes = await fetch(`${LND_HOST}/v1/payreq/${invoice}`, {
+        headers: { "Grpc-Metadata-macaroon": LND_MACAROON },
+      });
+      const decoded = await decodeRes.json();
+      const amountSats = parseInt(decoded.num_satoshis || 0);
+
+      // Check spending policy if agent is identified
+      if (resolvedAgent && amountSats > 0) {
+        const policy = await checkSpendingPolicy(resolvedAgent.id, amountSats);
+        if (!policy.allowed) {
+          return { content: [{ type: "text", text: `Payment blocked: ${policy.reason}` }] };
+        }
+      }
+
+      // Pay invoice directly via LND REST API
+      const res = await fetch(`${LND_HOST}/v1/channels/transactions`, {
+        method: "POST",
+        headers: {
+          "Grpc-Metadata-macaroon": LND_MACAROON,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          payment_request: invoice,
+          fee_limit: { fixed: fee_limit_sats },
+        }),
+      });
+      const data = await res.json();
+
+      if (res.ok && !data.payment_error) {
+        const paidAmount = parseInt(data.value || data.value_sat || amountSats || 0);
+        
+        // Log transaction against agent
+        if (resolvedAgent) {
+          await logTransaction(resolvedAgent.id, paidAmount, decoded.destination || "", decoded.description || "", "completed");
+        }
+
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              success: true,
+              payment_hash: data.payment_hash,
+              amount_sats: paidAmount,
+              fee_sats: parseInt(data.fee || data.fee_sat || 0),
+              agent: resolvedAgent?.name || null,
+              status: data.status || "SUCCEEDED",
+              message: `Paid ${paidAmount} sats ⚡`,
+            }, null, 2),
+          }],
+        };
+      }
+      const errMsg = data.payment_error || data.message || JSON.stringify(data);
+      return { content: [{ type: "text", text: `Payment failed: ${errMsg}` }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: `LND connection error: ${e.message}` }] };
     }
-    return { content: [{ type: "text", text: `Payment failed: ${JSON.stringify(data)}` }] };
   }
 );
 
@@ -319,6 +557,795 @@ server.tool(
   }
 );
 
+// Tool: Get transaction history
+server.tool(
+  "get_transaction_history",
+  "Get recent Lightning payment history",
+  {
+    max_payments: z.number().optional().default(10).describe("Maximum number of payments to return"),
+  },
+  async ({ max_payments }) => {
+    if (!LND_HOST) {
+      return { content: [{ type: "text", text: "Error: LND node not configured." }] };
+    }
+    try {
+      // Get payments (outgoing)
+      const payRes = await fetch(`${LND_HOST}/v1/payments?include_incomplete=false&max_payments=${max_payments}&reversed=true`, {
+        headers: { "Grpc-Metadata-macaroon": LND_MACAROON },
+      });
+      const payData = await payRes.json();
+
+      // Get invoices (incoming)
+      const invRes = await fetch(`${LND_HOST}/v1/invoices?num_max_invoices=${max_payments}&reversed=true`, {
+        headers: { "Grpc-Metadata-macaroon": LND_MACAROON },
+      });
+      const invData = await invRes.json();
+
+      const payments = (payData.payments || []).map(p => ({
+        type: "sent",
+        amount_sats: parseInt(p.value_sat || p.value || 0),
+        fee_sats: parseInt(p.fee_sat || p.fee || 0),
+        status: p.status,
+        payment_hash: p.payment_hash,
+        created_at: new Date(parseInt(p.creation_date) * 1000).toISOString(),
+      }));
+
+      const invoices = (invData.invoices || []).filter(i => i.state === "SETTLED").map(i => ({
+        type: "received",
+        amount_sats: parseInt(i.value || 0),
+        memo: i.memo || "",
+        settled_at: new Date(parseInt(i.settle_date) * 1000).toISOString(),
+        payment_hash: Buffer.from(i.r_hash, "base64").toString("hex"),
+      }));
+
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            payments_sent: payments,
+            payments_received: invoices,
+            total_sent: payments.reduce((s, p) => s + p.amount_sats, 0),
+            total_received: invoices.reduce((s, i) => s + i.amount_sats, 0),
+          }, null, 2),
+        }],
+      };
+    } catch (e) {
+      return { content: [{ type: "text", text: `LND error: ${e.message}` }] };
+    }
+  }
+);
+
+// Tool: Check channel balance
+server.tool(
+  "check_channel_balance",
+  "Check available Lightning channel balance (outbound and inbound liquidity)",
+  {},
+  async () => {
+    if (!LND_HOST) {
+      return { content: [{ type: "text", text: "Error: LND node not configured." }] };
+    }
+    try {
+      const res = await fetch(`${LND_HOST}/v1/balance/channels`, {
+        headers: { "Grpc-Metadata-macaroon": LND_MACAROON },
+      });
+      const data = await res.json();
+
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            local_balance_sats: parseInt(data.local_balance?.sat || data.balance || 0),
+            remote_balance_sats: parseInt(data.remote_balance?.sat || 0),
+            unsettled_local_sats: parseInt(data.unsettled_local_balance?.sat || 0),
+            unsettled_remote_sats: parseInt(data.unsettled_remote_balance?.sat || 0),
+            pending_open_local_sats: parseInt(data.pending_open_local_balance?.sat || 0),
+            note: "local_balance = outbound (can send), remote_balance = inbound (can receive)",
+          }, null, 2),
+        }],
+      };
+    } catch (e) {
+      return { content: [{ type: "text", text: `LND error: ${e.message}` }] };
+    }
+  }
+);
+
+// Tool: Delete agent wallet
+server.tool(
+  "delete_agent_wallet",
+  "Delete an agent wallet by name or ID (owner access required)",
+  {
+    agent: z.string().describe("Agent wallet name or ID to delete"),
+  },
+  async ({ agent }) => {
+    const auth = await getAuthLevel();
+    if (!auth.is_owner) {
+      return { content: [{ type: "text", text: "Error: Owner access required to delete wallets" }] };
+    }
+    const resolved = await resolveAgent(agent);
+    if (!resolved) {
+      return { content: [{ type: "text", text: `Error: Agent '${agent}' not found` }] };
+    }
+
+    const { status, data } = await apiCall(`/api/v1/agents/${resolved.id}`, {
+      method: "DELETE",
+    });
+
+    if (status === 200 || status === 204) {
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            deleted_agent: resolved.name,
+            deleted_id: resolved.id,
+            message: `Deleted wallet '${resolved.name}'`,
+          }, null, 2),
+        }],
+      };
+    }
+    return { content: [{ type: "text", text: `Error deleting agent: ${JSON.stringify(data)}` }] };
+  }
+);
+
+// Tool: Send to Lightning address
+server.tool(
+  "send_to_lightning_address",
+  "Send sats to a Lightning address (user@domain.com) using LNURL-pay protocol",
+  {
+    address: z.string().describe("Lightning address (e.g. user@domain.com)"),
+    amount_sats: z.number().describe("Amount in satoshis to send"),
+    agent: z.string().optional().describe("Agent wallet name or ID (for spending policy enforcement)"),
+    comment: z.string().optional().default("").describe("Optional comment for the recipient"),
+  },
+  async ({ address, amount_sats, agent, comment }) => {
+    if (!LND_HOST) {
+      return { content: [{ type: "text", text: "Error: LND node not configured." }] };
+    }
+
+    // Resolve agent for spending policy
+    let resolvedAgent = null;
+    if (agent) {
+      resolvedAgent = await resolveAgent(agent);
+      if (!resolvedAgent) return { content: [{ type: "text", text: `Error: Agent '${agent}' not found` }] };
+      if (!resolvedAgent.enabled) return { content: [{ type: "text", text: `Error: Agent '${resolvedAgent.name}' is disabled` }] };
+    }
+    if (!resolvedAgent) {
+      const auth = await getAuthLevel();
+      if (auth.agent_id) resolvedAgent = { id: auth.agent_id, name: auth.agent_name || auth.agent_id };
+    }
+
+    // Check spending policy
+    if (resolvedAgent) {
+      const policy = await checkSpendingPolicy(resolvedAgent.id, amount_sats);
+      if (!policy.allowed) return { content: [{ type: "text", text: `Payment blocked: ${policy.reason}` }] };
+    }
+
+    try {
+      // Parse Lightning address
+      const parts = address.split("@");
+      if (parts.length !== 2) {
+        return { content: [{ type: "text", text: `Error: Invalid Lightning address format. Expected user@domain.com` }] };
+      }
+      const [user, domain] = parts;
+
+      // Step 1: Fetch LNURL-pay metadata
+      const lnurlRes = await fetch(`https://${domain}/.well-known/lnurlp/${user}`);
+      if (!lnurlRes.ok) {
+        return { content: [{ type: "text", text: `Error: Could not resolve Lightning address. ${lnurlRes.status} from ${domain}` }] };
+      }
+      const lnurlData = await lnurlRes.json();
+
+      // Validate amount
+      const minSats = Math.ceil((lnurlData.minSendable || 1000) / 1000);
+      const maxSats = Math.floor((lnurlData.maxSendable || 100000000000) / 1000);
+      if (amount_sats < minSats || amount_sats > maxSats) {
+        return { content: [{ type: "text", text: `Error: Amount must be between ${minSats} and ${maxSats} sats for this address.` }] };
+      }
+
+      // Step 2: Request invoice from callback
+      let callbackUrl = `${lnurlData.callback}${lnurlData.callback.includes("?") ? "&" : "?"}amount=${amount_sats * 1000}`;
+      if (comment && lnurlData.commentAllowed) {
+        callbackUrl += `&comment=${encodeURIComponent(comment)}`;
+      }
+      const invoiceRes = await fetch(callbackUrl);
+      if (!invoiceRes.ok) {
+        return { content: [{ type: "text", text: `Error: Failed to get invoice from ${domain}` }] };
+      }
+      const invoiceData = await invoiceRes.json();
+
+      if (!invoiceData.pr) {
+        return { content: [{ type: "text", text: `Error: No invoice returned from ${domain}` }] };
+      }
+
+      // Step 3: Pay the invoice via LND
+      const payRes = await fetch(`${LND_HOST}/v1/channels/transactions`, {
+        method: "POST",
+        headers: {
+          "Grpc-Metadata-macaroon": LND_MACAROON,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          payment_request: invoiceData.pr,
+          fee_limit: { fixed: Math.max(100, Math.floor(amount_sats * 0.01)) },
+        }),
+      });
+      const payData = await payRes.json();
+
+      if (payRes.ok && !payData.payment_error) {
+        // Log transaction
+        if (resolvedAgent) {
+          await logTransaction(resolvedAgent.id, amount_sats, address, comment || `Lightning address payment to ${address}`, "completed");
+        }
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              success: true,
+              recipient: address,
+              amount_sats: amount_sats,
+              fee_sats: parseInt(payData.fee || payData.fee_sat || 0),
+              agent: resolvedAgent?.name || null,
+              payment_hash: payData.payment_hash,
+              message: `Sent ${amount_sats} sats to ${address} ⚡`,
+            }, null, 2),
+          }],
+        };
+      }
+      return { content: [{ type: "text", text: `Payment failed: ${payData.payment_error || JSON.stringify(payData)}` }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+    }
+  }
+);
+
+// Tool: Decode Lightning invoice
+server.tool(
+  "decode_invoice",
+  "Decode a Lightning invoice to inspect amount, expiry, destination before paying",
+  {
+    invoice: z.string().describe("BOLT11 Lightning invoice to decode"),
+  },
+  async ({ invoice }) => {
+    if (!LND_HOST) {
+      return { content: [{ type: "text", text: "Error: LND node not configured." }] };
+    }
+    try {
+      const res = await fetch(`${LND_HOST}/v1/payreq/${invoice}`, {
+        headers: { "Grpc-Metadata-macaroon": LND_MACAROON },
+      });
+      const data = await res.json();
+
+      if (!res.ok) {
+        return { content: [{ type: "text", text: `Error decoding invoice: ${JSON.stringify(data)}` }] };
+      }
+
+      const expiry = parseInt(data.expiry || 3600);
+      const timestamp = parseInt(data.timestamp || 0);
+      const expiresAt = new Date((timestamp + expiry) * 1000).toISOString();
+      const isExpired = Date.now() > (timestamp + expiry) * 1000;
+
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            amount_sats: parseInt(data.num_satoshis || 0),
+            destination: data.destination,
+            description: data.description || "",
+            payment_hash: data.payment_hash,
+            timestamp: new Date(timestamp * 1000).toISOString(),
+            expires_at: expiresAt,
+            is_expired: isExpired,
+            cltv_expiry: parseInt(data.cltv_expiry || 0),
+            num_route_hints: (data.route_hints || []).length,
+          }, null, 2),
+        }],
+      };
+    } catch (e) {
+      return { content: [{ type: "text", text: `LND error: ${e.message}` }] };
+    }
+  }
+);
+
+// Tool: List channels
+server.tool(
+  "list_channels",
+  "List all Lightning channels with capacity, balance, and peer info",
+  {},
+  async () => {
+    if (!LND_HOST) {
+      return { content: [{ type: "text", text: "Error: LND node not configured." }] };
+    }
+    try {
+      const res = await fetch(`${LND_HOST}/v1/channels`, {
+        headers: { "Grpc-Metadata-macaroon": LND_MACAROON },
+      });
+      const data = await res.json();
+
+      const channels = (data.channels || []).map(ch => ({
+        channel_id: ch.chan_id,
+        remote_pubkey: ch.remote_pubkey,
+        capacity_sats: parseInt(ch.capacity || 0),
+        local_balance_sats: parseInt(ch.local_balance || 0),
+        remote_balance_sats: parseInt(ch.remote_balance || 0),
+        active: ch.active,
+        initiator: ch.initiator,
+        commit_fee_sats: parseInt(ch.commit_fee || 0),
+        unsettled_balance_sats: parseInt(ch.unsettled_balance || 0),
+        total_sent_sats: parseInt(ch.total_satoshis_sent || 0),
+        total_received_sats: parseInt(ch.total_satoshis_received || 0),
+      }));
+
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            num_channels: channels.length,
+            total_capacity_sats: channels.reduce((s, c) => s + c.capacity_sats, 0),
+            total_local_sats: channels.reduce((s, c) => s + c.local_balance_sats, 0),
+            total_remote_sats: channels.reduce((s, c) => s + c.remote_balance_sats, 0),
+            channels: channels,
+          }, null, 2),
+        }],
+      };
+    } catch (e) {
+      return { content: [{ type: "text", text: `LND error: ${e.message}` }] };
+    }
+  }
+);
+
+// ---------------------------------------------------------------
+// AI Self-Setup Tools
+// ---------------------------------------------------------------
+
+// Tool: Check setup status
+server.tool(
+  "setup_check_status",
+  "Check current AgenticBTC configuration status. Returns what's configured, what's missing, and the recommended next step.",
+  {},
+  async () => {
+    const status = {
+      api_url_configured: !!API_URL,
+      api_key_configured: !!API_KEY,
+      lightning_host_configured: !!LND_HOST,
+      lightning_macaroon_configured: !!LND_MACAROON,
+    };
+
+    // Test API connectivity
+    try {
+      const { status: httpStatus } = await apiCall("/api/v1/admin/agents");
+      status.api_reachable = httpStatus === 200;
+    } catch {
+      status.api_reachable = false;
+    }
+
+    // Test Lightning connectivity
+    status.lightning_reachable = false;
+    if (LND_HOST && LND_MACAROON) {
+      try {
+        const res = await fetch(`${LND_HOST}/v1/getinfo`, {
+          headers: { "Grpc-Metadata-macaroon": LND_MACAROON },
+        });
+        status.lightning_reachable = res.status === 200;
+      } catch {}
+    }
+
+    // Check for agent wallets
+    status.has_agent_wallets = false;
+    if (status.api_reachable) {
+      try {
+        const { data } = await apiCall("/api/v1/admin/agents");
+        const agents = Array.isArray(data) ? data : (data.agents || []);
+        status.has_agent_wallets = agents.length > 0;
+      } catch {}
+    }
+
+    // Determine next step
+    if (!status.api_key_configured) {
+      status.recommended_next_step = "Set your API key. Sign up at https://agenticbtc.app/dashboard to get one.";
+    } else if (!status.api_reachable) {
+      status.recommended_next_step = "API key set but cannot reach the server. Check your AGENTBTC_API_URL and AGENTBTC_API_KEY.";
+    } else if (!status.lightning_host_configured) {
+      status.recommended_next_step = "Connect a Lightning node. Use setup_configure_lightning with your Voltage or Umbrel node credentials.";
+    } else if (!status.lightning_reachable) {
+      status.recommended_next_step = "Lightning node configured but unreachable. Use setup_diagnose_issues for details.";
+    } else if (!status.has_agent_wallets) {
+      status.recommended_next_step = "Create your first agent wallet. Use setup_create_first_wallet.";
+    } else {
+      status.recommended_next_step = "Everything looks good! Use setup_test_payment_capabilities to verify end-to-end payments.";
+    }
+
+    return { content: [{ type: "text", text: JSON.stringify({ success: true, status }, null, 2) }] };
+  }
+);
+
+// Tool: Configure Lightning node
+server.tool(
+  "setup_configure_lightning",
+  "Configure Lightning node connection. Accepts lndconnect URL or host + macaroon. Validates before saving.",
+  {
+    lndconnect_url: z.string().optional().describe("lndconnect URL (lndconnect://host:port?macaroon=...)"),
+    host: z.string().optional().describe("LND REST API host (e.g. https://your-node.t.voltageapp.io:8080)"),
+    macaroon: z.string().optional().describe("Admin macaroon (hex-encoded)"),
+  },
+  async ({ lndconnect_url, host, macaroon }) => {
+    // Parse lndconnect URL if provided
+    if (lndconnect_url) {
+      try {
+        const url = new URL(lndconnect_url);
+        host = `https://${url.hostname}:${url.port || 8080}`;
+        macaroon = url.searchParams.get("macaroon") || "";
+      } catch (e) {
+        return { content: [{ type: "text", text: JSON.stringify({ success: false, error: `Failed to parse lndconnect URL: ${e.message}` }) }] };
+      }
+    }
+
+    if (!host || !macaroon) {
+      return { content: [{ type: "text", text: JSON.stringify({ success: false, error: "Provide either lndconnect_url, or both host and macaroon." }) }] };
+    }
+
+    try {
+      const res = await fetch(`${host}/v1/getinfo`, {
+        headers: { "Grpc-Metadata-macaroon": macaroon },
+      });
+      if (res.status === 200) {
+        const data = await res.json();
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              success: true,
+              message: "Lightning node connected successfully!",
+              node_alias: data.alias || "",
+              node_pubkey: data.identity_pubkey || "",
+              synced: data.synced_to_chain || false,
+              active_channels: data.num_active_channels || 0,
+              note: "Set AGENTBTC_LND_HOST and AGENTBTC_LND_MACAROON in your Claude Desktop config to persist this.",
+            }, null, 2),
+          }],
+        };
+      }
+      const body = await res.text();
+      return { content: [{ type: "text", text: JSON.stringify({ success: false, error: `Node returned HTTP ${res.status}: ${body}` }) }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: JSON.stringify({ success: false, error: `Connection failed: ${e.message}` }) }] };
+    }
+  }
+);
+
+// Tool: Test payment capabilities
+server.tool(
+  "setup_test_payment_capabilities",
+  "Test that AgenticBTC payments work end to end. Checks API, Lightning, channels, and liquidity.",
+  {},
+  async () => {
+    const caps = {
+      api_connected: false,
+      lightning_connected: false,
+      can_create_invoices: false,
+      can_send_payments: false,
+      channels_available: false,
+      outbound_liquidity_sats: 0,
+      inbound_liquidity_sats: 0,
+    };
+
+    // Test API
+    try {
+      const { status } = await apiCall("/api/v1/admin/agents");
+      caps.api_connected = status === 200;
+    } catch {}
+
+    // Test Lightning
+    if (LND_HOST && LND_MACAROON) {
+      try {
+        const res = await fetch(`${LND_HOST}/v1/getinfo`, {
+          headers: { "Grpc-Metadata-macaroon": LND_MACAROON },
+        });
+        caps.lightning_connected = res.status === 200;
+      } catch {}
+
+      if (caps.lightning_connected) {
+        // Test invoice creation
+        try {
+          const res = await fetch(`${LND_HOST}/v1/invoices`, {
+            method: "POST",
+            headers: { "Grpc-Metadata-macaroon": LND_MACAROON, "Content-Type": "application/json" },
+            body: JSON.stringify({ value: 1, memo: "AgenticBTC setup test", expiry: "60" }),
+          });
+          if (res.ok) {
+            const data = await res.json();
+            caps.can_create_invoices = !!data.payment_request;
+          }
+        } catch {}
+
+        // Check channel balance
+        try {
+          const res = await fetch(`${LND_HOST}/v1/balance/channels`, {
+            headers: { "Grpc-Metadata-macaroon": LND_MACAROON },
+          });
+          if (res.ok) {
+            const data = await res.json();
+            caps.outbound_liquidity_sats = parseInt(data.local_balance?.sat || data.balance || 0);
+            caps.inbound_liquidity_sats = parseInt(data.remote_balance?.sat || 0);
+            caps.channels_available = caps.outbound_liquidity_sats > 0;
+            caps.can_send_payments = caps.outbound_liquidity_sats > 0;
+          }
+        } catch {}
+      }
+    }
+
+    caps.fully_operational = caps.api_connected && caps.can_send_payments;
+    if (caps.fully_operational) {
+      caps.summary = `AgenticBTC is fully operational. You can send up to ${caps.outbound_liquidity_sats} sats and receive up to ${caps.inbound_liquidity_sats} sats.`;
+    } else {
+      const issues = [];
+      if (!caps.api_connected) issues.push("API not connected");
+      if (!caps.lightning_connected) issues.push("Lightning node not connected");
+      else if (!caps.can_send_payments) issues.push("No outbound liquidity (open a channel or receive funds)");
+      caps.summary = `Not fully operational. Issues: ${issues.join(", ")}`;
+    }
+
+    return { content: [{ type: "text", text: JSON.stringify({ success: true, capabilities: caps }, null, 2) }] };
+  }
+);
+
+// Tool: Diagnose issues
+server.tool(
+  "setup_diagnose_issues",
+  "Diagnose AgenticBTC configuration problems. Returns specific error messages with fix instructions.",
+  {},
+  async () => {
+    const issues = [];
+
+    // Check API key
+    if (!API_KEY) {
+      issues.push({ component: "API Key", status: "missing", error: "No API key configured", fix: "Set AGENTBTC_API_KEY in your Claude Desktop MCP config. Get your key from https://agenticbtc.app/dashboard" });
+    } else {
+      try {
+        const { status } = await apiCall("/api/v1/admin/agents");
+        if (status === 200) {
+          issues.push({ component: "API Key", status: "ok", error: null, fix: null });
+        } else if (status === 401) {
+          issues.push({ component: "API Key", status: "invalid", error: "API key rejected (401)", fix: "Generate a new API key from https://agenticbtc.app/dashboard" });
+        } else {
+          issues.push({ component: "API Key", status: "error", error: `Server returned ${status}`, fix: "AgenticBTC server may be down. Try again in a few minutes." });
+        }
+      } catch (e) {
+        issues.push({ component: "API Server", status: "unreachable", error: e.message, fix: `Check AGENTBTC_API_URL is correct. Current: ${API_URL}` });
+      }
+    }
+
+    // Check Lightning
+    if (!LND_HOST) {
+      issues.push({ component: "Lightning Node", status: "not_configured", error: "No Lightning node configured", fix: "Optional. Set AGENTBTC_LND_HOST to your LND REST URL (e.g. https://your-node.t.voltageapp.io:8080)" });
+    } else if (!LND_MACAROON) {
+      issues.push({ component: "Lightning Macaroon", status: "missing", error: "LND host set but no macaroon", fix: "Set AGENTBTC_LND_MACAROON to your hex-encoded admin macaroon." });
+    } else {
+      try {
+        const res = await fetch(`${LND_HOST}/v1/getinfo`, {
+          headers: { "Grpc-Metadata-macaroon": LND_MACAROON },
+        });
+        if (res.status === 200) {
+          const data = await res.json();
+          if (!data.synced_to_chain) {
+            issues.push({ component: "Lightning Node", status: "syncing", error: "Node not synced yet", fix: "Wait for blockchain sync to complete (can take hours)." });
+          } else if ((data.num_active_channels || 0) === 0) {
+            issues.push({ component: "Lightning Channels", status: "no_channels", error: "No active channels", fix: "Open a Lightning channel from your Voltage dashboard or Lightning Terminal." });
+          } else {
+            issues.push({ component: "Lightning Node", status: "ok", error: null, fix: null });
+          }
+        } else if (res.status === 401) {
+          issues.push({ component: "Lightning Macaroon", status: "invalid", error: "Macaroon rejected (401)", fix: "Re-download macaroon from Voltage or re-export from your node." });
+        } else {
+          issues.push({ component: "Lightning Node", status: "error", error: `HTTP ${res.status}`, fix: "Check the host URL is correct." });
+        }
+      } catch (e) {
+        issues.push({ component: "Lightning Node", status: "unreachable", error: e.message, fix: `Cannot connect to ${LND_HOST}. Verify the node is online.` });
+      }
+    }
+
+    const allOk = issues.every(i => i.status === "ok" || i.status === "not_configured");
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          success: true,
+          healthy: allOk,
+          issues,
+          summary: allOk ? "All systems healthy!" : `Found ${issues.filter(i => !["ok", "not_configured"].includes(i.status)).length} issue(s) to fix.`,
+        }, null, 2),
+      }],
+    };
+  }
+);
+
+// Tool: Create first wallet
+server.tool(
+  "setup_create_first_wallet",
+  "Create the user's first agent wallet with sensible defaults (1000 sat per-tx limit, 10000 sat daily budget).",
+  {
+    wallet_name: z.string().optional().default("my-first-agent").describe("Name for the agent wallet"),
+  },
+  async ({ wallet_name }) => {
+    if (!API_KEY) {
+      return { content: [{ type: "text", text: JSON.stringify({ success: false, error: "API key not configured. Set AGENTBTC_API_KEY first." }) }] };
+    }
+    const { status, data } = await apiCall("/api/v1/agents", {
+      method: "POST",
+      body: JSON.stringify({ name: wallet_name }),
+    });
+    if (status === 200 || status === 201) {
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            message: `Agent wallet '${wallet_name}' created!`,
+            agent_id: data.id,
+            agent_api_key: data.api_key,
+            wallet_name,
+            defaults_applied: { per_transaction_limit_sats: 1000, daily_budget_sats: 10000 },
+            next_steps: [
+              "Fund the wallet by receiving a Lightning payment",
+              "Use 'get_agent_balance' to check the balance",
+              "Use 'pay_lightning_invoice' to make your first payment",
+            ],
+          }, null, 2),
+        }],
+      };
+    }
+    return { content: [{ type: "text", text: JSON.stringify({ success: false, error: `Failed to create wallet: ${JSON.stringify(data)}` }) }] };
+  }
+);
+
+// Tool: Get onboarding prompt
+server.tool(
+  "setup_get_onboarding_prompt",
+  "Returns a conversational prompt the AI should use to guide the user through AgenticBTC setup step by step.",
+  {},
+  async () => {
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          success: true,
+          onboarding_prompt: `You are helping a user set up AgenticBTC — a payment system that lets AI agents send and receive Bitcoin payments via Lightning Network.
+
+Guide the user through these steps in a friendly, conversational way:
+
+STEP 1: Check current status — Call setup_check_status to see what's already configured.
+STEP 2: API Key — If no API key, ask them to sign up at https://agenticbtc.app/dashboard
+STEP 3: Lightning Node (optional) — Ask if they have one. If yes, use setup_configure_lightning. If no, recommend Voltage (voltage.cloud).
+STEP 4: Create Agent Wallet — Call setup_create_first_wallet
+STEP 5: Test Everything — Call setup_test_payment_capabilities
+STEP 6: Complete — Call setup_complete_onboarding
+
+Be patient, explain everything in plain language, celebrate small wins.`,
+        }, null, 2),
+      }],
+    };
+  }
+);
+
+// Tool: Validate credentials
+server.tool(
+  "setup_validate_credentials",
+  "Validate API key and Lightning credentials without making any payments.",
+  {
+    api_key: z.string().optional().describe("API key to validate"),
+    lnd_host: z.string().optional().describe("LND host to validate"),
+    lnd_macaroon: z.string().optional().describe("LND macaroon to validate"),
+  },
+  async ({ api_key, lnd_host, lnd_macaroon }) => {
+    const testKey = api_key || API_KEY;
+    const testHost = lnd_host || LND_HOST;
+    const testMac = lnd_macaroon || LND_MACAROON;
+    const results = { api_key_valid: false, lightning_valid: false };
+
+    if (testKey) {
+      try {
+        const res = await fetch(`${API_URL}/api/v1/admin/agents`, {
+          headers: { "X-API-Key": testKey, "Content-Type": "application/json" },
+        });
+        results.api_key_valid = res.status === 200;
+        if (res.status === 401) results.api_key_error = "Invalid API key";
+        else if (res.status !== 200) results.api_key_error = `Server returned ${res.status}`;
+      } catch (e) {
+        results.api_key_error = e.message;
+      }
+    }
+
+    if (testHost && testMac) {
+      try {
+        const res = await fetch(`${testHost}/v1/getinfo`, {
+          headers: { "Grpc-Metadata-macaroon": testMac },
+        });
+        if (res.status === 200) {
+          const data = await res.json();
+          results.lightning_valid = true;
+          results.node_alias = data.alias || "";
+          results.node_pubkey = data.identity_pubkey || "";
+        } else if (res.status === 401) {
+          results.lightning_error = "Invalid macaroon";
+        } else {
+          results.lightning_error = `Node returned ${res.status}`;
+        }
+      } catch (e) {
+        results.lightning_error = e.message;
+      }
+    }
+
+    results.success = true;
+    return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+  }
+);
+
+// Tool: Complete onboarding
+server.tool(
+  "setup_complete_onboarding",
+  "Mark onboarding as complete. Returns a summary of everything that was configured.",
+  {},
+  async () => {
+    const summary = {
+      api_url: API_URL,
+      api_key_set: !!API_KEY,
+      lightning_configured: !!(LND_HOST && LND_MACAROON),
+    };
+
+    // Get node info
+    if (LND_HOST && LND_MACAROON) {
+      try {
+        const res = await fetch(`${LND_HOST}/v1/getinfo`, {
+          headers: { "Grpc-Metadata-macaroon": LND_MACAROON },
+        });
+        if (res.ok) {
+          const data = await res.json();
+          summary.node_alias = data.alias || "";
+          summary.node_pubkey = data.identity_pubkey || "";
+          summary.active_channels = data.num_active_channels || 0;
+        }
+      } catch {}
+    }
+
+    // Get wallet count
+    if (API_KEY) {
+      try {
+        const { status, data } = await apiCall("/api/v1/admin/agents");
+        if (status === 200) {
+          const agents = Array.isArray(data) ? data : (data.agents || []);
+          summary.agent_wallets = agents.length;
+        }
+      } catch {}
+    }
+
+    summary.onboarding_complete = true;
+    summary.what_you_can_do = [
+      "Create and manage agent wallets",
+      "Send and receive Lightning payments",
+      "Access L402-protected APIs",
+      "Set spending limits and budgets",
+      "Monitor transactions and balances",
+    ];
+    if (summary.lightning_configured) {
+      summary.what_you_can_do.push("Route payments through multiple rails with auto-failover");
+    }
+
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          success: true,
+          message: "Onboarding complete! AgenticBTC is ready to use.",
+          summary,
+        }, null, 2),
+      }],
+    };
+  }
+);
+
 // Start server
 const transport = new StdioServerTransport();
 await server.connect(transport);