agentic-flow 1.8.15 → 1.9.0

package/docs/guides/MCP-TOOLS.md

@@ -1,12 +1,102 @@
 # 🔧 MCP Tools: Complete Reference Guide
 
-**213 tools across 4 servers • Universal AI agent capabilities**
+**~135 tools across 5 servers • Universal AI agent capabilities**
 
 ---
 
 ## 📑 Quick Navigation
 
-[← Back to Main README](https://github.com/ruvnet/agentic-flow/blob/main/README.md) | [Multi-Model Router ←](https://github.com/ruvnet/agentic-flow/blob/main/docs/guides/MULTI-MODEL-ROUTER.md) | [Deployment Options →](https://github.com/ruvnet/agentic-flow/blob/main/docs/guides/DEPLOYMENT.md)
+[← Back to Main README](../../README.md) | [Quick Start →](#-quick-start-5-minutes) | [Authentication →](./MCP-AUTHENTICATION.md) | [Troubleshooting →](./MCP-TROUBLESHOOTING.md)
+
+---
+
+## 🚀 Quick Start (5 minutes)
+
+### Step 1: Prerequisites (1 minute)
+
+```bash
+# Verify you have Node.js 18+
+node --version
+
+# Check Claude CLI is installed
+claude --version
+```
+
+### Step 2: Add MCP Servers (2 minutes)
+
+```bash
+# 1. Claude Flow - Core orchestration (required)
+claude mcp add claude-flow npx claude-flow@alpha mcp start
+
+# 2. Flow Nexus - Cloud features (optional, requires registration)
+claude mcp add flow-nexus npx flow-nexus@latest mcp start
+
+# 3. Agentic Payments - Payment authorization (optional)
+# Built-in with agentic-flow, auto-detected
+
+# 4. Agentic Flow - Agent execution (optional)
+claude mcp add agentic-flow npx agentic-flow@latest mcp start
+
+# Verify servers are running
+claude mcp list
+```
+
+### Step 3: First Tool Call (2 minutes)
+
+```javascript
+// Initialize a swarm (no auth required)
+mcp__claude-flow__swarm_init({
+  topology: 'mesh',
+  maxAgents: 8,
+  strategy: 'balanced'
+});
+
+// Response:
+// {
+//   success: true,
+//   swarmId: 'swarm-abc123',
+//   topology: 'mesh',
+//   maxAgents: 8
+// }
+```
+
+**✅ Success!** You're now using MCP tools. Continue to [Authentication Setup](#-prerequisites--authentication) for advanced features.
+
+---
+
+## 📋 Prerequisites & Authentication
+
+### Setup Overview
+
+| Server | Auth Required | Setup Time | Documentation |
+|--------|---------------|------------|---------------|
+| **Claude Flow** | ❌ No | 0 min | Ready to use |
+| **AgentDB** | ❌ No (local) | 0 min | Built-in with Claude Flow |
+| **Agentic Flow** | ❌ No | 0 min | Built-in package |
+| **Flow Nexus** | ✅ Yes | 2 min | [Auth Guide](./MCP-AUTHENTICATION.md) |
+| **Agentic Payments** | ✅ Keypair | 1 min | [Payment Setup](./MCP-AUTHENTICATION.md#agentic-payments) |
+
+### Quick Authentication Setup
+
+**Flow Nexus (for cloud features):**
+```bash
+# Register once
+npx flow-nexus@latest register
+
+# Login each session
+npx flow-nexus@latest login
+```
+
+**Agentic Payments (for payment features):**
+```javascript
+// Generate keypair once
+const identity = mcp__agentic-payments__generate_agent_identity({
+  include_private_key: true
+});
+// Store private key securely!
+```
+
+**→ Full setup guide:** [MCP-AUTHENTICATION.md](./MCP-AUTHENTICATION.md)
 
 ---
 
@@ -38,1062 +128,1115 @@ MCP tools provide standardized interfaces for:
 - Agents can execute real actions, not just suggest them
 - Cross-session memory enables learning and improvement
 - Multi-agent coordination for complex tasks
-- Integration with 1000+ external services
+- Integration with external services
 
 ---
 
 ## 🚀 MCP Server Overview
 
-### Available Servers
+### Available Servers (Verified Tool Counts)
+
+| Server | Tools | Focus Area | Auth | Installation |
+|--------|-------|------------|------|--------------|
+| **Claude Flow** | 46 | Orchestration, memory, neural | None | `claude mcp add claude-flow npx claude-flow@alpha mcp start` |
+| **AgentDB** | 9 | Advanced memory, causal learning | None (local) | Built-in with Claude Flow |
+| **Flow Nexus** | 70+ | Cloud execution, sandboxes, templates | Required | `claude mcp add flow-nexus npx flow-nexus@latest mcp start` |
+| **Agentic Payments** | 10 | Payment authorization, mandates | Keypair | Built-in with agentic-flow |
+| **Agentic Flow** | ~10 | Agent execution, optimization | None | `claude mcp add agentic-flow npx agentic-flow@latest mcp start` |
 
-| Server | Tools | Focus Area | Installation |
-|--------|-------|------------|--------------|
-| **Claude Flow** | 101 tools | Agent orchestration, memory, neural | `claude mcp add claude-flow npx claude-flow@alpha mcp start` |
-| **Flow Nexus** | 96 tools | Cloud execution, sandboxes, payments | `claude mcp add flow-nexus npx flow-nexus@latest mcp start` |
-| **Agentic Payments** | 12 tools | Payment authorization, mandates | Built-in with agentic-flow |
-| **Claude Flow SDK** | 4 tools | Low-level SDK integration | Built-in with agentic-flow |
+**Total**: ~135+ verified MCP tools
 
-**Total**: 213 MCP tools available
+**Note**: Tool counts verified through source code analysis (October 2025). See [AgentDB Verification Report](../agentdb-tools-verification.md) and [Tool Architecture](../mcp-tools-architecture.md) for details.
 
 ---
 
 ## 📚 Tool Categories
 
-### 1️⃣ Swarm & Agent Orchestration (20 tools)
+### Category Overview
+
+| Category | Tools | Primary Server | Auth Required |
+|----------|-------|----------------|---------------|
+| [1. AgentDB - Advanced Memory](#1%EF%B8%8F⃣-agentdb---advanced-memory-9-tools) | 9 | AgentDB | No |
+| [2. Swarm & Agent Orchestration](#2%EF%B8%8F⃣-swarm--agent-orchestration-26-tools) | 26 | Claude Flow | No |
+| [3. Memory & Learning](#3%EF%B8%8F⃣-memory--learning-20-tools) | 20 | Claude Flow | No |
+| [4. Neural Networks & AI](#4%EF%B8%8F⃣-neural-networks--ai-15-tools) | 15 | Claude Flow, Flow Nexus | Mixed |
+| [5. Cloud Execution & Sandboxes](#5%EF%B8%8F⃣-cloud-execution--sandboxes-24-tools) | 24 | Flow Nexus | Yes |
+| [6. GitHub Integration](#6%EF%B8%8F⃣-github-integration-16-tools) | 16 | Claude Flow | No |
+| [7. Payment Authorization](#7%EF%B8%8F⃣-payment-authorization-10-tools) | 10 | Agentic Payments | Keypair |
+| [8. Workflow Automation](#8%EF%B8%8F⃣-workflow-automation-22-tools) | 22 | Flow Nexus | Yes |
+| [9. Performance & Monitoring](#9%EF%B8%8F⃣-performance--monitoring-18-tools) | 18 | Claude Flow | No |
+| [10. App Store & Templates](#-app-store--templates-12-tools) | 12 | Flow Nexus | Yes |
 
-Coordinate multiple agents for complex tasks.
+---
 
-#### **Core Swarm Tools**
+## 1️⃣ AgentDB - Advanced Memory (9 tools)
 
-```javascript
-// Initialize swarm with specific topology
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'swarm_init',
-    params: {
-      topology: 'mesh',      // mesh, hierarchical, ring, star
-      maxAgents: 8,
-      strategy: 'balanced'   // balanced, specialized, adaptive
-    }
-  }
-});
+State-of-the-art agent memory with causal learning and explainable recall.
 
-// Spawn specialized agent
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'agent_spawn',
-    params: {
-      type: 'coder',         // researcher, analyst, optimizer, coordinator
-      name: 'backend-dev',
-      capabilities: ['api-design', 'database', 'testing']
-    }
-  }
-});
+### Reflexion Memory (Self-Critique Learning)
 
-// Orchestrate complex task
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'task_orchestrate',
-    params: {
-      task: 'Build REST API with authentication',
-      strategy: 'adaptive',  // parallel, sequential, adaptive
-      priority: 'high',
-      maxAgents: 5
-    }
-  }
-});
-```
+#### `reflexion_store`
 
-#### **Monitoring & Status**
+Store an episode with self-critique for learning from experience.
 
 ```javascript
-// Get swarm status
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'swarm_status',
-    params: { swarmId: 'swarm-123' }
-  }
-});
-
-// List active agents
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'agent_list',
-    params: { filter: 'active' }  // all, active, idle, busy
-  }
+// Store successful authentication implementation
+mcp__agentdb__reflexion_store({
+  session_id: 'session-123',
+  task: 'implement_oauth2_authentication',
+  reward: 0.95,
+  success: true,
+  critique: 'OAuth2 PKCE flow worked perfectly for mobile apps',
+  input: 'Need secure authentication for mobile app',
+  output: 'Implemented OAuth2 with authorization code + PKCE',
+  latency_ms: 1200,
+  tokens: 500
 });
+```
 
-// Get agent performance metrics
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'agent_metrics',
-    params: {
-      agentId: 'agent-456',
-      metric: 'performance'  // cpu, memory, tasks, performance
-    }
-  }
-});
+**Response:**
+```json
+{
+  "success": true,
+  "episodeId": 42,
+  "message": "✅ Stored episode #42\nTask: implement_oauth2_authentication\nReward: 0.95\nSuccess: true"
+}
 ```
 
-#### **Advanced Swarm Operations**
+**Common Errors:**
+- `INVALID_REWARD`: Reward must be 0-1
+- `MISSING_SESSION`: Provide session_id
 
-```javascript
-// Scale swarm up/down
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'swarm_scale',
-    params: {
-      swarmId: 'swarm-123',
-      targetSize: 15
-    }
-  }
-});
+**See Also:**
+- [`reflexion_retrieve`](#reflexion_retrieve) - Find similar past episodes
+- [`skill_create`](#skill_create) - Convert successful episodes to skills
 
-// Optimize topology dynamically
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'topology_optimize',
-    params: { swarmId: 'swarm-123' }
-  }
-});
+---
 
-// Destroy swarm and cleanup
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'swarm_destroy',
-    params: { swarmId: 'swarm-123' }
-  }
+#### `reflexion_retrieve`
+
+Retrieve relevant past episodes for learning from experience.
+
+```javascript
+// Find past successful authentication implementations
+mcp__agentdb__reflexion_retrieve({
+  task: 'authentication implementation',
+  k: 10,
+  only_successes: true,
+  min_reward: 0.8
 });
 ```
 
+**Response:**
+```json
+{
+  "success": true,
+  "episodes": [
+    {
+      "id": 42,
+      "task": "implement_oauth2_authentication",
+      "reward": 0.95,
+      "similarity": 0.87,
+      "critique": "OAuth2 PKCE flow worked perfectly..."
+    }
+  ],
+  "count": 10
+}
+```
+
 ---
 
-### 2️⃣ Memory & Learning (18 tools)
+### Skill Library (Reusable Agent Skills)
 
-Persistent memory across sessions with learning capabilities.
+#### `skill_create`
 
-#### **Memory Storage & Retrieval**
+Create a reusable skill in the skill library.
 
 ```javascript
-// Store memory with TTL and namespace
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'memory_usage',
-    params: {
-      action: 'store',
-      key: 'api-design-pattern',
-      value: JSON.stringify({
-        pattern: 'REST with JWT auth',
-        successRate: 0.95,
-        usageCount: 47
-      }),
-      namespace: 'backend-patterns',
-      ttl: 2592000  // 30 days in seconds
-    }
-  }
-});
-
-// Retrieve memory
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'memory_usage',
-    params: {
-      action: 'retrieve',
-      key: 'api-design-pattern',
-      namespace: 'backend-patterns'
-    }
-  }
+// Create JWT authentication skill
+mcp__agentdb__skill_create({
+  name: 'jwt_auth',
+  description: 'Generate secure JWT tokens with 24h expiry',
+  code: "const jwt = require('jsonwebtoken'); jwt.sign(payload, secret, {expiresIn: '24h'});",
+  success_rate: 0.92
 });
+```
 
-// Search memories with pattern
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'memory_search',
-    params: {
-      pattern: 'authentication',
-      namespace: 'backend-patterns',
-      limit: 10
-    }
-  }
-});
+**Response:**
+```json
+{
+  "success": true,
+  "skillId": 15,
+  "message": "✅ Created skill #15: jwt_auth"
+}
 ```
 
-#### **Memory Management**
+---
 
-```javascript
-// List all memories in namespace
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'memory_usage',
-    params: {
-      action: 'list',
-      namespace: 'backend-patterns'
-    }
-  }
-});
+#### `skill_search`
 
-// Delete memory
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'memory_usage',
-    params: {
-      action: 'delete',
-      key: 'old-pattern',
-      namespace: 'backend-patterns'
-    }
-  }
-});
+Search for applicable skills by semantic similarity.
 
-// Create memory backup
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'memory_backup',
-    params: { path: '/backups/memory-20241012.db' }
-  }
+```javascript
+// Find authentication-related skills
+mcp__agentdb__skill_search({
+  task: 'authentication security',
+  k: 5,
+  min_success_rate: 0.8
 });
+```
 
-// Restore from backup
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'memory_restore',
-    params: { backupPath: '/backups/memory-20241012.db' }
-  }
-});
+**Response:**
+```json
+{
+  "success": true,
+  "skills": [
+    {
+      "id": 15,
+      "name": "jwt_auth",
+      "description": "Generate secure JWT tokens...",
+      "successRate": 0.92,
+      "similarity": 0.85
+    }
+  ]
+}
 ```
 
 ---
 
-### 3️⃣ Neural Networks & AI (15 tools)
+### Causal Memory (Cause-Effect Learning)
 
-Train and deploy neural networks with WASM acceleration.
+#### `causal_add_edge`
 
-#### **Neural Training**
+Add a causal relationship between actions and outcomes.
 
 ```javascript
-// Train neural patterns
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'neural_train',
-    params: {
-      pattern_type: 'coordination',  // optimization, prediction
-      training_data: JSON.stringify({
-        inputs: [...],
-        outputs: [...]
-      }),
-      epochs: 50
-    }
-  }
+// Record that adding tests improves code quality
+mcp__causal_add_edge({
+  cause: 'add_unit_tests',
+  effect: 'code_quality_improvement',
+  uplift: 0.25,
+  confidence: 0.95,
+  sample_size: 100
 });
+```
 
-// Check training status
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'neural_status',
-    params: { modelId: 'model-123' }
-  }
-});
+**Response:**
+```json
+{
+  "success": true,
+  "edgeId": 7,
+  "message": "✅ Added causal edge #7\nadd_unit_tests → code_quality_improvement\nUplift: 0.25"
+}
 ```
 
-#### **Neural Inference**
+---
+
+#### `causal_query`
+
+Query causal effects to understand what actions cause outcomes.
 
 ```javascript
-// Run inference
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'neural_predict',
-    params: {
-      modelId: 'model-123',
-      input: JSON.stringify({ features: [...] })
-    }
-  }
+// Check if adding tests causally improves code quality
+mcp__causal_query({
+  cause: 'add_unit_tests',
+  effect: 'code_quality_improvement',
+  min_confidence: 0.7,
+  min_uplift: 0.1,
+  limit: 5
 });
+```
 
-// Analyze cognitive patterns
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'neural_patterns',
-    params: {
-      action: 'analyze',  // learn, predict
-      operation: 'code-review',
-      outcome: 'success'
+**Response:**
+```json
+{
+  "success": true,
+  "edges": [
+    {
+      "id": 7,
+      "cause": "add_unit_tests",
+      "effect": "code_quality_improvement",
+      "uplift": 0.25,
+      "confidence": 0.95,
+      "sampleSize": 100
     }
-  }
-});
+  ]
+}
 ```
 
-#### **Model Management**
+---
+
+### Explainable Recall (Provenance Certificates)
+
+#### `recall_with_certificate`
+
+Retrieve memories with causal utility scoring and provenance certificate.
 
 ```javascript
-// Load pre-trained model
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'model_load',
-    params: { modelPath: '/models/pretrained-v1.onnx' }
-  }
+// Retrieve memories with causal utility weighting
+mcp__recall_with_certificate({
+  query: 'successful API optimization strategies',
+  k: 5,
+  alpha: 0.6,  // 60% weight on similarity
+  beta: 0.3,   // 30% weight on causal uplift
+  gamma: 0.1   // 10% weight on recency
 });
+```
 
-// Save trained model
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'model_save',
-    params: {
-      modelId: 'model-123',
-      path: '/models/custom-v1.onnx'
+**Response:**
+```json
+{
+  "success": true,
+  "results": [
+    {
+      "type": "skill",
+      "id": 15,
+      "content": "jwt_auth implementation...",
+      "similarity": 0.85,
+      "uplift": 0.25,
+      "score": 0.78
     }
-  }
+  ],
+  "certificateId": "cert-abc123",
+  "count": 5
+}
+```
+
+---
+
+### Nightly Learner (Pattern Discovery)
+
+#### `learner_discover`
+
+Automatically discover causal patterns from episode history.
+
+```javascript
+// Discover causal patterns from past episodes
+mcp__learner_discover({
+  min_attempts: 3,
+  min_success_rate: 0.6,
+  min_confidence: 0.7,
+  dry_run: true  // Preview first
 });
+```
 
-// Compress model for faster inference
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'neural_compress',
-    params: {
-      modelId: 'model-123',
-      ratio: 0.5  // 50% compression
+**Response:**
+```json
+{
+  "success": true,
+  "patterns": [
+    {
+      "cause": "add_unit_tests",
+      "effect": "code_quality_improvement",
+      "uplift": 0.25,
+      "sampleSize": 100,
+      "confidence": 0.95
     }
-  }
-});
+  ],
+  "count": 5,
+  "dryRun": true
+}
 ```
 
 ---
 
-### 4️⃣ Cloud Execution & Sandboxes (24 tools)
+### Database Utilities
 
-Execute code in isolated cloud environments.
+#### `db_stats`
 
-#### **Sandbox Management (Flow Nexus)**
+Get database statistics showing record counts.
 
 ```javascript
-// Create execution sandbox
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'sandbox_create',
-    params: {
-      template: 'node',  // python, react, nextjs, claude-code
-      name: 'api-dev',
-      env_vars: {
-        DATABASE_URL: 'postgresql://...',
-        API_KEY: 'sk-...'
-      },
-      timeout: 3600  // 1 hour
-    }
-  }
-});
+// Get database statistics
+mcp__db_stats({});
+```
 
-// Execute code in sandbox
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'sandbox_execute',
-    params: {
-      sandbox_id: 'sandbox-789',
-      code: 'console.log("Hello from sandbox!")',
-      language: 'javascript',
-      timeout: 60
-    }
-  }
-});
+**Response:**
+```json
+{
+  "success": true,
+  "stats": {
+    "causalEdges": 42,
+    "experiments": 156,
+    "observations": 1024,
+    "episodes": 387,
+    "skills": 23
+  }
+}
+```
 
-// Upload file to sandbox
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'sandbox_upload',
-    params: {
-      sandbox_id: 'sandbox-789',
-      file_path: '/app/config.json',
-      content: JSON.stringify({ port: 3000 })
-    }
-  }
+---
+
+## 2️⃣ Swarm & Agent Orchestration (26 tools)
+
+Coordinate multiple agents for complex tasks.
+
+### Core Swarm Tools
+
+#### `swarm_init`
+
+Initialize swarm with specific topology.
+
+```javascript
+// Initialize mesh topology swarm
+mcp__claude-flow__swarm_init({
+  topology: 'mesh',      // mesh, hierarchical, ring, star
+  maxAgents: 8,
+  strategy: 'balanced'   // balanced, specialized, adaptive
 });
 ```
 
-#### **Sandbox Operations**
+**Response:**
+```json
+{
+  "success": true,
+  "swarmId": "swarm-abc123",
+  "topology": "mesh",
+  "maxAgents": 8,
+  "strategy": "balanced"
+}
+```
+
+**Common Errors:**
+- `INVALID_TOPOLOGY`: Must be mesh, hierarchical, ring, or star
+- `MAX_AGENTS_EXCEEDED`: maxAgents must be 1-100
+
+**See Also:**
+- [`agent_spawn`](#agent_spawn) - Add agents to swarm
+- [`task_orchestrate`](#task_orchestrate) - Assign tasks
+- [`swarm_status`](#swarm_status) - Monitor progress
+
+---
+
+#### `agent_spawn`
+
+Spawn specialized agent in swarm.
 
 ```javascript
-// Get sandbox status
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'sandbox_status',
-    params: { sandbox_id: 'sandbox-789' }
-  }
+// Spawn backend developer agent
+mcp__claude-flow__agent_spawn({
+  type: 'coder',         // researcher, analyst, optimizer, coordinator
+  name: 'backend-dev',
+  capabilities: ['api-design', 'database', 'testing']
 });
+```
 
-// List all sandboxes
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'sandbox_list',
-    params: { status: 'running' }  // running, stopped, all
-  }
-});
+**Response:**
+```json
+{
+  "success": true,
+  "agentId": "agent-456",
+  "type": "coder",
+  "name": "backend-dev",
+  "capabilities": ["api-design", "database", "testing"]
+}
+```
 
-// Configure sandbox environment
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'sandbox_configure',
-    params: {
-      sandbox_id: 'sandbox-789',
-      env_vars: { NEW_VAR: 'value' },
-      install_packages: ['express', 'axios']
-    }
-  }
-});
+---
 
-// Stop sandbox
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'sandbox_stop',
-    params: { sandbox_id: 'sandbox-789' }
-  }
-});
+#### `task_orchestrate`
 
-// Delete sandbox
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'sandbox_delete',
-    params: { sandbox_id: 'sandbox-789' }
-  }
+Orchestrate complex task across swarm.
+
+```javascript
+// Build REST API with authentication
+mcp__claude-flow__task_orchestrate({
+  task: 'Build REST API with authentication',
+  strategy: 'adaptive',  // parallel, sequential, adaptive
+  priority: 'high',
+  maxAgents: 5
 });
 ```
 
+**Response:**
+```json
+{
+  "success": true,
+  "taskId": "task-789",
+  "strategy": "adaptive",
+  "priority": "high",
+  "assignedAgents": ["agent-456", "agent-457"]
+}
+```
+
 ---
 
-### 5️⃣ GitHub Integration (16 tools)
+### Monitoring & Status
 
-Comprehensive GitHub workflow automation.
+#### `swarm_status`
 
-#### **Repository Management**
+Get swarm status and details.
 
 ```javascript
-// Analyze repository
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'github_repo_analyze',
-    params: {
-      repo: 'ruvnet/agentic-flow',
-      analysis_type: 'code_quality'  // performance, security
-    }
-  }
-});
-
-// Manage pull requests
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'github_pr_manage',
-    params: {
-      repo: 'ruvnet/agentic-flow',
-      pr_number: 123,
-      action: 'review'  // merge, close
-    }
-  }
+// Check swarm health
+mcp__claude-flow__swarm_status({
+  swarmId: 'swarm-abc123'
 });
+```
 
-// Code review with AI
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'github_code_review',
-    params: {
-      repo: 'ruvnet/agentic-flow',
-      pr: 123
-    }
-  }
-});
+**Response:**
+```json
+{
+  "success": true,
+  "swarmId": "swarm-abc123",
+  "status": "active",
+  "topology": "mesh",
+  "activeAgents": 5,
+  "maxAgents": 8,
+  "tasksRunning": 3,
+  "tasksCompleted": 12
+}
 ```
 
-#### **Issue & Project Management**
+---
+
+#### `agent_list`
+
+List active agents in swarm.
 
 ```javascript
-// Track issues intelligently
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'github_issue_track',
-    params: {
-      repo: 'ruvnet/agentic-flow',
-      action: 'triage'  // assign, label, close
-    }
-  }
+// List all active agents
+mcp__claude-flow__agent_list({
+  filter: 'active'  // all, active, idle, busy
 });
+```
 
-// Coordinate releases
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'github_release_coord',
-    params: {
-      repo: 'ruvnet/agentic-flow',
-      version: 'v1.6.0'
+**Response:**
+```json
+{
+  "success": true,
+  "agents": [
+    {
+      "agentId": "agent-456",
+      "type": "coder",
+      "status": "busy",
+      "currentTask": "task-789"
     }
-  }
-});
+  ],
+  "count": 5
+}
+```
 
-// Automate workflows
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'github_workflow_auto',
-    params: {
-      repo: 'ruvnet/agentic-flow',
-      workflow: {
-        trigger: 'push',
-        actions: ['test', 'build', 'deploy']
-      }
-    }
-  }
+---
+
+#### `agent_metrics`
+
+Get agent performance metrics.
+
+```javascript
+// Get agent performance
+mcp__claude-flow__agent_metrics({
+  agentId: 'agent-456',
+  metric: 'performance'  // cpu, memory, tasks, performance
 });
 ```
 
+**Response:**
+```json
+{
+  "success": true,
+  "agentId": "agent-456",
+  "metrics": {
+    "tasksCompleted": 12,
+    "successRate": 0.92,
+    "avgLatencyMs": 1200,
+    "tokensUsed": 15000
+  }
+}
+```
+
 ---
 
-### 6️⃣ Payment Authorization (12 tools)
+### Advanced Swarm Operations
 
-AI-native payment authorization with Active Mandates.
+#### `swarm_scale`
 
-#### **Mandate Management (Agentic Payments)**
+Scale swarm up or down.
 
 ```javascript
-// Create payment mandate
-await query({
-  mcp: {
-    server: 'agentic-payments',
-    tool: 'create_active_mandate',
-    params: {
-      agent: 'shopping-bot@agentics',
-      holder: 'user-123',
-      amount: 12000,  // $120.00 in cents
-      currency: 'USD',
-      period: 'monthly',
-      kind: 'intent',
-      merchant_allow: ['amazon.com', 'ebay.com'],
-      expires_at: '2025-01-12T00:00:00Z'
-    }
-  }
-});
-
-// Sign mandate with Ed25519
-await query({
-  mcp: {
-    server: 'agentic-payments',
-    tool: 'sign_mandate',
-    params: {
-      mandate: { ... },
-      private_key: 'ed25519-private-key-hex'
-    }
-  }
+// Scale to 15 agents
+mcp__claude-flow__swarm_scale({
+  swarmId: 'swarm-abc123',
+  targetSize: 15
 });
+```
 
-// Verify mandate signature
-await query({
-  mcp: {
-    server: 'agentic-payments',
-    tool: 'verify_mandate',
-    params: {
-      signed_mandate: { ... },
-      check_guards: true  // Check expiration, revocation
-    }
-  }
-});
+**Response:**
+```json
+{
+  "success": true,
+  "swarmId": "swarm-abc123",
+  "previousSize": 8,
+  "newSize": 15,
+  "spawned": 7
+}
 ```
 
-#### **Payment Operations**
+---
 
-```javascript
-// Create intent-based mandate
-await query({
-  mcp: {
-    server: 'agentic-payments',
-    tool: 'create_intent_mandate',
-    params: {
-      merchant_id: 'shop-456',
-      customer_id: 'user-123',
-      intent: 'Purchase office supplies under $100',
-      max_amount: 100.00,
-      currency: 'USD'
-    }
-  }
-});
+#### `swarm_destroy`
 
-// Create cart-based mandate
-await query({
-  mcp: {
-    server: 'agentic-payments',
-    tool: 'create_cart_mandate',
-    params: {
-      merchant_id: 'shop-456',
-      customer_id: 'user-123',
-      items: [
-        { id: 'item-1', name: 'Laptop', quantity: 1, unit_price: 120000 },
-        { id: 'item-2', name: 'Mouse', quantity: 2, unit_price: 2500 }
-      ],
-      currency: 'USD'
-    }
-  }
-});
+Destroy swarm and cleanup resources.
 
-// Revoke mandate
-await query({
-  mcp: {
-    server: 'agentic-payments',
-    tool: 'revoke_mandate',
-    params: {
-      mandate_id: 'mandate-789',
-      reason: 'User cancelled subscription'
-    }
-  }
+```javascript
+// Cleanup swarm
+mcp__claude-flow__swarm_destroy({
+  swarmId: 'swarm-abc123'
 });
 ```
 
+**Response:**
+```json
+{
+  "success": true,
+  "swarmId": "swarm-abc123",
+  "agentsTerminated": 15,
+  "message": "Swarm destroyed successfully"
+}
+```
+
 ---
 
-### 7️⃣ Workflow Automation (22 tools)
+## 3️⃣ Memory & Learning (20 tools)
 
-Event-driven workflow execution with message queues.
+Persistent memory across sessions with learning capabilities.
 
-#### **Workflow Creation & Execution**
+### Memory Storage & Retrieval
 
-```javascript
-// Create workflow
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'workflow_create',
-    params: {
-      name: 'code-review-pipeline',
-      steps: [
-        { type: 'checkout', params: { branch: 'main' } },
-        { type: 'test', params: { coverage: 80 } },
-        { type: 'review', params: { reviewers: 2 } },
-        { type: 'merge', params: { strategy: 'squash' } }
-      ],
-      triggers: ['pull_request.opened', 'push.main']
-    }
-  }
-});
+#### `memory_usage`
 
-// Execute workflow
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'workflow_execute',
-    params: {
-      workflow_id: 'workflow-456',
-      input_data: { pr_number: 123 },
-      async: true  // Run via message queue
-    }
-  }
-});
+Store, retrieve, list, or delete memory with TTL and namespacing.
 
-// Get workflow status
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'workflow_status',
-    params: {
-      workflow_id: 'workflow-456',
-      include_metrics: true
-    }
-  }
+**Store memory:**
+```javascript
+// Store API design pattern
+mcp__claude-flow__memory_usage({
+  action: 'store',
+  key: 'api-design-pattern',
+  value: JSON.stringify({
+    pattern: 'REST with JWT auth',
+    successRate: 0.95,
+    usageCount: 47
+  }),
+  namespace: 'backend-patterns',
+  ttl: 2592000  // 30 days in seconds
 });
 ```
 
-#### **Advanced Workflow Features**
+**Response:**
+```json
+{
+  "success": true,
+  "action": "store",
+  "key": "api-design-pattern",
+  "namespace": "backend-patterns"
+}
+```
 
+**Retrieve memory:**
 ```javascript
-// Assign optimal agent to task
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'workflow_agent_assign',
-    params: {
-      task_id: 'task-789',
-      agent_type: 'coder',
-      use_vector_similarity: true
-    }
-  }
+// Retrieve pattern
+mcp__claude-flow__memory_usage({
+  action: 'retrieve',
+  key: 'api-design-pattern',
+  namespace: 'backend-patterns'
 });
+```
 
-// Check message queue status
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'workflow_queue_status',
-    params: {
-      queue_name: 'code-review-queue',
-      include_messages: true
-    }
-  }
+**Response:**
+```json
+{
+  "success": true,
+  "action": "retrieve",
+  "key": "api-design-pattern",
+  "value": "{\"pattern\":\"REST with JWT auth\",\"successRate\":0.95,\"usageCount\":47}",
+  "namespace": "backend-patterns"
+}
+```
+
+**List memories:**
+```javascript
+// List all in namespace
+mcp__claude-flow__memory_usage({
+  action: 'list',
+  namespace: 'backend-patterns'
 });
+```
 
-// Get workflow audit trail
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'workflow_audit_trail',
-    params: {
-      workflow_id: 'workflow-456',
-      start_time: '2024-10-01T00:00:00Z',
-      limit: 50
-    }
-  }
+**Delete memory:**
+```javascript
+// Delete old pattern
+mcp__claude-flow__memory_usage({
+  action: 'delete',
+  key: 'old-pattern',
+  namespace: 'backend-patterns'
 });
 ```
 
 ---
 
-### 8️⃣ Performance & Monitoring (18 tools)
-
-Real-time metrics, benchmarks, and optimization.
+#### `memory_search`
 
-#### **Performance Tracking**
+Search memories with pattern matching.
 
 ```javascript
-// Generate performance report
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'performance_report',
-    params: {
-      timeframe: '24h',  // 7d, 30d
-      format: 'detailed'  // summary, json
-    }
-  }
-});
-
-// Analyze bottlenecks
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'bottleneck_analyze',
-    params: {
-      component: 'swarm-coordinator',
-      metrics: ['latency', 'throughput', 'error_rate']
-    }
-  }
+// Search for authentication patterns
+mcp__claude-flow__memory_search({
+  pattern: 'authentication',
+  namespace: 'backend-patterns',
+  limit: 10
 });
+```
 
-// Track token usage
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'token_usage',
-    params: {
-      operation: 'code-review',
-      timeframe: '24h'
+**Response:**
+```json
+{
+  "success": true,
+  "results": [
+    {
+      "key": "api-design-pattern",
+      "value": "{\"pattern\":\"REST with JWT auth\"...}",
+      "similarity": 0.87
     }
-  }
-});
+  ],
+  "count": 10
+}
 ```
 
-#### **Benchmarking**
+---
+
+## 4️⃣ Neural Networks & AI (15 tools)
+
+Train and deploy neural networks with WASM acceleration.
+
+### Neural Training
+
+#### `neural_train`
+
+Train neural patterns with WASM acceleration.
 
 ```javascript
-// Run performance benchmarks
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'benchmark_run',
-    params: {
-      suite: 'swarm',  // wasm, agent, task
-      iterations: 10
-    }
-  }
+// Train coordination patterns
+mcp__claude-flow__neural_train({
+  pattern_type: 'coordination',  // optimization, prediction
+  training_data: JSON.stringify({
+    inputs: [[1, 0], [0, 1], [1, 1]],
+    outputs: [[1], [1], [0]]
+  }),
+  epochs: 50
 });
+```
 
-// Collect system metrics
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'metrics_collect',
-    params: {
-      components: ['gateway', 'agents', 'memory']
-    }
-  }
-});
+**Response:**
+```json
+{
+  "success": true,
+  "modelId": "model-123",
+  "patternType": "coordination",
+  "epochs": 50,
+  "finalLoss": 0.012
+}
+```
 
-// Analyze performance trends
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'trend_analysis',
-    params: {
-      metric: 'response_time',
-      period: '7d'
-    }
-  }
+---
+
+#### `neural_status`
+
+Check neural network training status.
+
+```javascript
+// Check model status
+mcp__claude-flow__neural_status({
+  modelId: 'model-123'
 });
 ```
 
+**Response:**
+```json
+{
+  "success": true,
+  "modelId": "model-123",
+  "status": "trained",
+  "accuracy": 0.95,
+  "trainingTime": 1200
+}
+```
+
 ---
 
-### 9️⃣ App Store & Templates (12 tools)
+### Neural Inference
 
-Deploy pre-built applications and templates.
+#### `neural_predict`
 
-#### **Template Management**
+Run inference on trained model.
 
 ```javascript
-// List available templates
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'template_list',
-    params: {
-      category: 'web-apps',
-      featured: true,
-      limit: 20
-    }
-  }
+// Predict with model
+mcp__claude-flow__neural_predict({
+  modelId: 'model-123',
+  input: JSON.stringify({ features: [1, 0, 1] })
 });
+```
 
-// Get template details
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'template_get',
-    params: {
-      template_id: 'template-123'
-    }
-  }
-});
+**Response:**
+```json
+{
+  "success": true,
+  "modelId": "model-123",
+  "prediction": [0.92],
+  "confidence": 0.95
+}
+```
 
-// Deploy template
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'template_deploy',
-    params: {
-      template_id: 'template-123',
-      deployment_name: 'my-app',
-      variables: {
-        anthropic_api_key: 'sk-ant-...',
-        port: 3000
-      }
-    }
-  }
+---
+
+## 5️⃣ Cloud Execution & Sandboxes (24 tools)
+
+Execute code in isolated cloud environments (Flow Nexus).
+
+**⚠️ Authentication Required:** [Setup Guide](./MCP-AUTHENTICATION.md#flow-nexus)
+
+### Sandbox Management
+
+#### `sandbox_create`
+
+Create execution sandbox with environment variables.
+
+```javascript
+// Create Node.js sandbox
+mcp__flow-nexus__sandbox_create({
+  template: 'node',  // python, react, nextjs, claude-code
+  name: 'api-dev',
+  env_vars: {
+    DATABASE_URL: 'postgresql://...',
+    API_KEY: 'sk-...'
+  },
+  timeout: 3600  // 1 hour
 });
 ```
 
-#### **App Publishing**
+**Response:**
+```json
+{
+  "success": true,
+  "sandbox_id": "sandbox-789",
+  "template": "node",
+  "status": "running"
+}
+```
+
+**Common Errors:**
+- `AUTH_REQUIRED`: Login first with `user_login`
+- `INVALID_TEMPLATE`: Must be node, python, react, nextjs, or claude-code
+- `INSUFFICIENT_CREDITS`: Add credits to account
+
+---
+
+#### `sandbox_execute`
+
+Execute code in sandbox.
 
 ```javascript
-// Publish app to store
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'app_store_publish_app',
-    params: {
-      name: 'Code Review Bot',
-      description: 'Automated code review with AI',
-      category: 'development',
-      source_code: '...',
-      tags: ['code-review', 'ai', 'automation'],
-      version: '1.0.0'
-    }
-  }
+// Run code in sandbox
+mcp__flow-nexus__sandbox_execute({
+  sandbox_id: 'sandbox-789',
+  code: 'console.log("Hello from sandbox!")',
+  language: 'javascript',
+  timeout: 60
 });
+```
 
-// List user's apps
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'app_installed',
-    params: { user_id: 'user-123' }
-  }
-});
+**Response:**
+```json
+{
+  "success": true,
+  "sandbox_id": "sandbox-789",
+  "output": "Hello from sandbox!\n",
+  "exitCode": 0,
+  "executionTime": 250
+}
+```
 
-// Get app analytics
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'app_analytics',
-    params: {
-      app_id: 'app-456',
-      timeframe: '30d'
-    }
-  }
+---
+
+#### `sandbox_upload`
+
+Upload file to sandbox.
+
+```javascript
+// Upload config file
+mcp__flow-nexus__sandbox_upload({
+  sandbox_id: 'sandbox-789',
+  file_path: '/app/config.json',
+  content: JSON.stringify({ port: 3000 })
 });
 ```
 
+**Response:**
+```json
+{
+  "success": true,
+  "sandbox_id": "sandbox-789",
+  "file_path": "/app/config.json",
+  "size": 15
+}
+```
+
 ---
 
-### 🔟 User Management & Auth (16 tools)
+## 6️⃣ GitHub Integration (16 tools)
+
+Comprehensive GitHub workflow automation.
+
+### Repository Management
 
-Authentication, authorization, and user operations.
+#### `github_repo_analyze`
 
-#### **Authentication (Flow Nexus)**
+Analyze repository code quality, performance, or security.
 
 ```javascript
-// Register new user
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'user_register',
-    params: {
-      email: 'user@example.com',
-      password: 'secure-password',
-      full_name: 'John Doe'
-    }
-  }
+// Analyze code quality
+mcp__claude-flow__github_repo_analyze({
+  repo: 'ruvnet/agentic-flow',
+  analysis_type: 'code_quality'  // performance, security
 });
+```
 
-// Login user
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'user_login',
-    params: {
-      email: 'user@example.com',
-      password: 'secure-password'
+**Response:**
+```json
+{
+  "success": true,
+  "repo": "ruvnet/agentic-flow",
+  "analysisType": "code_quality",
+  "score": 0.87,
+  "issues": [
+    {
+      "file": "src/index.ts",
+      "line": 42,
+      "message": "Consider adding error handling"
     }
-  }
-});
-
-// Logout user
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'user_logout',
-    params: {}
-  }
-});
+  ]
+}
 ```
 
-#### **User Profile Management**
+---
+
+## 7️⃣ Payment Authorization (10 tools)
+
+AI-native payment authorization with Active Mandates.
+
+**⚠️ Keypair Required:** [Setup Guide](./MCP-AUTHENTICATION.md#agentic-payments)
+
+### Mandate Management
+
+#### `create_active_mandate`
+
+Create payment mandate with spend caps and merchant restrictions.
 
 ```javascript
-// Get user profile
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'user_profile',
-    params: { user_id: 'user-123' }
-  }
+// Create monthly mandate
+mcp__agentic-payments__create_active_mandate({
+  agent: 'shopping-bot@agentics',
+  holder: 'user-123',
+  amount: 12000,  // $120.00 in cents
+  currency: 'USD',
+  period: 'monthly',
+  kind: 'intent',
+  merchant_allow: ['amazon.com', 'ebay.com'],
+  expires_at: '2025-01-12T00:00:00Z'
 });
+```
 
-// Update profile
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'user_update_profile',
-    params: {
-      user_id: 'user-123',
-      updates: {
-        full_name: 'John Smith',
-        avatar_url: 'https://...'
-      }
-    }
-  }
-});
+**Response:**
+```json
+{
+  "success": true,
+  "mandateId": "mandate-789",
+  "agent": "shopping-bot@agentics",
+  "amount": 12000,
+  "period": "monthly"
+}
+```
 
-// Get user statistics
-await query({
-  mcp: {
-    server: 'flow-nexus',
-    tool: 'user_stats',
-    params: { user_id: 'user-123' }
-  }
+---
+
+## 8️⃣ Workflow Automation (22 tools)
+
+Event-driven workflow execution with message queues (Flow Nexus).
+
+**⚠️ Authentication Required:** [Setup Guide](./MCP-AUTHENTICATION.md#flow-nexus)
+
+### Workflow Creation & Execution
+
+#### `workflow_create`
+
+Create event-driven workflow.
+
+```javascript
+// Create code review pipeline
+mcp__flow-nexus__workflow_create({
+  name: 'code-review-pipeline',
+  steps: [
+    { type: 'checkout', params: { branch: 'main' } },
+    { type: 'test', params: { coverage: 80 } },
+    { type: 'review', params: { reviewers: 2 } },
+    { type: 'merge', params: { strategy: 'squash' } }
+  ],
+  triggers: ['pull_request.opened', 'push.main']
 });
 ```
 
+**Response:**
+```json
+{
+  "success": true,
+  "workflow_id": "workflow-456",
+  "name": "code-review-pipeline",
+  "steps": 4
+}
+```
+
 ---
 
-## 🛠️ Tool Usage Patterns
+## 9️⃣ Performance & Monitoring (18 tools)
 
-### Pattern 1: Sequential Task Execution
+Real-time metrics, benchmarks, and optimization.
 
-```javascript
-// Step 1: Initialize swarm
-const swarm = await query({ mcp: { server: 'claude-flow', tool: 'swarm_init', params: { topology: 'mesh' } }});
+### Performance Tracking
 
-// Step 2: Spawn agents
-await query({ mcp: { server: 'claude-flow', tool: 'agent_spawn', params: { type: 'coder' } }});
-await query({ mcp: { server: 'claude-flow', tool: 'agent_spawn', params: { type: 'tester' } }});
+#### `performance_report`
 
-// Step 3: Execute task
-const result = await query({ mcp: { server: 'claude-flow', tool: 'task_orchestrate', params: { task: '...' } }});
+Generate performance report with metrics.
 
-// Step 4: Clean up
-await query({ mcp: { server: 'claude-flow', tool: 'swarm_destroy', params: { swarmId: swarm.id } }});
+```javascript
+// Get 24h performance report
+mcp__claude-flow__performance_report({
+  timeframe: '24h',  // 7d, 30d
+  format: 'detailed'  // summary, json
+});
 ```
 
-### Pattern 2: Memory-Augmented Execution
+**Response:**
+```json
+{
+  "success": true,
+  "timeframe": "24h",
+  "metrics": {
+    "totalRequests": 1250,
+    "avgLatencyMs": 150,
+    "p95LatencyMs": 350,
+    "errorRate": 0.02
+  }
+}
+```
+
+---
+
+## 🔟 App Store & Templates (12 tools)
+
+Deploy pre-built applications and templates (Flow Nexus).
+
+**⚠️ Authentication Required:** [Setup Guide](./MCP-AUTHENTICATION.md#flow-nexus)
+
+### Template Management
+
+#### `template_list`
+
+List available deployment templates.
 
 ```javascript
-// Retrieve relevant memories
-const memories = await query({
-  mcp: { server: 'claude-flow', tool: 'memory_search', params: { pattern: 'api-design' } }
+// List web app templates
+mcp__flow-nexus__template_list({
+  category: 'web-apps',
+  featured: true,
+  limit: 20
 });
+```
 
-// Execute task with memory context
-const result = await executeTask({ context: memories });
+**Response:**
+```json
+{
+  "success": true,
+  "templates": [
+    {
+      "template_id": "template-123",
+      "name": "React + Express Starter",
+      "category": "web-apps",
+      "featured": true
+    }
+  ],
+  "count": 20
+}
+```
 
-// Store new experience
-await query({
-  mcp: { server: 'claude-flow', tool: 'memory_usage', params: {
-    action: 'store',
-    key: 'new-pattern',
-    value: JSON.stringify(result)
-  }}
-});
+---
+
+## 🛠️ Response Types & Error Handling
+
+### Standard Response Structure
+
+**Success Response:**
+```typescript
+interface SuccessResponse<T> {
+  success: true;
+  data: T;
+  metadata?: {
+    timestamp: string;
+    latency_ms: number;
+    cache_hit?: boolean;
+  };
+}
 ```
 
-### Pattern 3: Cloud-Native Development
+**Error Response:**
+```typescript
+interface ErrorResponse {
+  success: false;
+  error: {
+    code: string;           // e.g., "AUTH_REQUIRED"
+    message: string;        // Human-readable
+    details?: object;       // Additional context
+    suggestion?: string;    // How to fix
+  };
+}
+```
 
-```javascript
-// Create sandbox
-const sandbox = await query({
-  mcp: { server: 'flow-nexus', tool: 'sandbox_create', params: { template: 'node' } }
-});
+### Common Error Codes
 
-// Execute code
-await query({
-  mcp: { server: 'flow-nexus', tool: 'sandbox_execute', params: {
-    sandbox_id: sandbox.id,
-    code: 'npm install && npm test'
-  }}
-});
+| Code | Meaning | Solution |
+|------|---------|----------|
+| `AUTH_REQUIRED` | Authentication needed | Run login/register first |
+| `INVALID_PARAMS` | Bad parameters | Check parameter types/values |
+| `NOT_FOUND` | Resource doesn't exist | Verify ID/name |
+| `RATE_LIMITED` | Too many requests | Wait and retry |
+| `INSUFFICIENT_CREDITS` | Not enough balance | Add credits or upgrade tier |
+| `SERVER_ERROR` | Internal error | Retry or report issue |
 
-// Get results
-const logs = await query({
-  mcp: { server: 'flow-nexus', tool: 'sandbox_logs', params: { sandbox_id: sandbox.id } }
-});
+### Error Handling Pattern
 
-// Cleanup
-await query({
-  mcp: { server: 'flow-nexus', tool: 'sandbox_delete', params: { sandbox_id: sandbox.id } }
-});
+```javascript
+try {
+  const result = mcp__flow-nexus__sandbox_create({
+    template: 'node',
+    name: 'test-sandbox'
+  });
+
+  if (result.success) {
+    console.log('Sandbox created:', result.data.sandbox_id);
+  }
+} catch (error) {
+  if (error.code === 'AUTH_REQUIRED') {
+    // Handle authentication
+    mcp__flow-nexus__user_login({ ... });
+    // Retry operation
+  } else if (error.code === 'RATE_LIMITED') {
+    // Wait and retry
+    await sleep(error.details.retry_after_ms);
+  } else {
+    // Log and report
+    console.error('Unexpected error:', error);
+  }
+}
 ```
 
 ---
@@ -1102,13 +1245,16 @@ await query({
 
 ### Latency Comparison
 
-| Tool Category | Average Latency | P99 Latency | Throughput |
-|---------------|----------------|-------------|------------|
-| **Memory Operations** | 5ms | 12ms | 10K ops/sec |
-| **Swarm Management** | 50ms | 120ms | 500 ops/sec |
-| **Neural Inference** | 15ms | 35ms | 2K ops/sec |
-| **Sandbox Creation** | 2s | 5s | 50 ops/min |
-| **GitHub Integration** | 200ms | 800ms | 100 ops/sec |
+**Note:** These benchmarks represent typical performance under normal conditions. Actual latency may vary based on network conditions, system load, and data volume.
+
+| Tool Category | Average Latency | P99 Latency | Throughput | Server |
+|---------------|----------------|-------------|------------|--------|
+| **Memory Operations** | 5ms | 12ms | 10K ops/sec | Claude Flow |
+| **Swarm Management** | 50ms | 120ms | 500 ops/sec | Claude Flow |
+| **Neural Inference** | 15ms | 35ms | 2K ops/sec | Claude Flow |
+| **Sandbox Creation** | 2s | 5s | 50 ops/min | Flow Nexus |
+| **GitHub Integration** | 200ms | 800ms | 100 ops/sec | Claude Flow |
+| **AgentDB Queries** | 10ms | 25ms | 5K ops/sec | AgentDB |
 
 ### Cost Optimization
 
@@ -1118,20 +1264,33 @@ await query({
 | **Memory Retrieval** | $0.05 (LLM) | $0.00 (local) | 100% |
 | **Task Orchestration** | $0.30 (manual) | $0.05 (auto) | 83% |
 
+**Optimization Tips:**
+- Batch operations when possible
+- Reuse sandboxes instead of creating new ones
+- Use memory caching for frequent queries
+- Enable WASM acceleration for neural operations
+
 ---
 
 ## 🔗 Related Documentation
 
 ### Core Components
-- [← Back to Main README](https://github.com/ruvnet/agentic-flow/blob/main/README.md)
-- [Agent Booster (Code Transformations)](https://github.com/ruvnet/agentic-flow/blob/main/docs/guides/AGENT-BOOSTER.md)
-- [ReasoningBank (Learning Memory)](https://github.com/ruvnet/agentic-flow/blob/main/docs/guides/REASONINGBANK.md)
-- [Multi-Model Router (Cost Optimization)](https://github.com/ruvnet/agentic-flow/blob/main/docs/guides/MULTI-MODEL-ROUTER.md)
+- [← Back to Main README](../../README.md)
+- [Quick Start Guide](./MCP-QUICKSTART.md) - 5-minute getting started
+- [Authentication Setup](./MCP-AUTHENTICATION.md) - Flow Nexus & Agentic Payments auth
+- [Troubleshooting Guide](./MCP-TROUBLESHOOTING.md) - Common issues & solutions
+- [Usage Examples](./MCP-EXAMPLES.md) - Real-world patterns
+
+### Technical References
+- [AgentDB Verification Report](../agentdb-tools-verification.md) - Tool count verification
+- [MCP Tools Architecture](../mcp-tools-architecture.md) - Design decisions
+- [Agent Booster (Code Transformations)](./AGENT-BOOSTER.md)
+- [ReasoningBank (Learning Memory)](./REASONINGBANK.md)
+- [Multi-Model Router (Cost Optimization)](./MULTI-MODEL-ROUTER.md)
 
 ### Advanced Topics
-- [Deployment Options →](https://github.com/ruvnet/agentic-flow/blob/main/docs/guides/DEPLOYMENT.md)
-- [Performance Benchmarks](https://github.com/ruvnet/agentic-flow/blob/main/docs/agentic-flow/benchmarks/README.md)
-- [API Reference](https://docs.rs/agentic-flow)
+- [Deployment Options](./DEPLOYMENT.md)
+- [Performance Benchmarks](../../benchmarks/README.md)
 
 ### External Resources
 - [MCP Specification](https://modelcontextprotocol.io)
@@ -1140,6 +1299,47 @@ await query({
 
 ---
 
+## ❓ FAQ
+
+### Getting Started
+
+**Q: Which MCP server should I start with?**
+A: Claude Flow (no auth required, core orchestration features).
+
+**Q: Do I need all servers?**
+A: No. Start with Claude Flow, add others as needed:
+- Flow Nexus: Cloud execution, sandboxes
+- Agentic Payments: Payment authorization
+- AgentDB: Advanced memory (included in Claude Flow)
+
+**Q: How do I know which tools I have access to?**
+A: Run `claude mcp list` to see installed servers.
+
+### Authentication
+
+**Q: Why does Flow Nexus require registration?**
+A: Cloud resources (sandboxes, storage) require account management.
+
+**Q: Can I use Flow Nexus tools without registering?**
+A: No. Registration is required for cloud features.
+
+**Q: Is my password stored securely?**
+A: Yes. Passwords are hashed with bcrypt, never stored in plaintext.
+
+### Pricing & Limits
+
+**Q: Are MCP tools free?**
+A: Mixed:
+- Claude Flow: Free, unlimited
+- AgentDB: Free, local storage
+- Flow Nexus: Free tier + paid upgrades
+- Agentic Payments: Transaction fees
+
+**Q: What are Flow Nexus rate limits?**
+A: Free tier: 100 requests/hour. Paid tiers: Higher limits.
+
+---
+
 ## 🤝 Contributing
 
 MCP tools are part of the agentic-flow ecosystem. Contributions welcome!
@@ -1151,16 +1351,16 @@ MCP tools are part of the agentic-flow ecosystem. Contributions welcome!
 - Documentation improvements
 - Usage examples
 
-See [CONTRIBUTING.md](https://github.com/ruvnet/agentic-flow/blob/main/CONTRIBUTING.md) for guidelines.
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
 
 ---
 
 ## 📄 License
 
-MIT License - see [LICENSE](https://github.com/ruvnet/agentic-flow/blob/main/LICENSE) for details.
+MIT License - see [LICENSE](../../LICENSE) for details.
 
 ---
 
-**Access 213 AI agent capabilities across 4 MCP servers. Universal integration.** 🔧
+**Access ~135 AI agent capabilities across 5 MCP servers. Universal integration.** 🔧
 
-[← Back to Main README](https://github.com/ruvnet/agentic-flow/blob/main/README.md)
+[← Back to Main README](../../README.md)