npm - @genlobe/mcp-server - Versions diffs - 2.2.0 → 3.1.0 - Mend

@genlobe/mcp-server 2.2.0 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/dist/index.js CHANGED Viewed

@@ -13,17 +13,23 @@
  * the End-user endpoints, NOT the Tenant/Dashboard endpoints.
  *
  * Usage:
- *   npx @multiagent/mcp-server
+ *   npx @genlobe/mcp-server
  *
  * Or configure in VS Code MCP settings with SAAS_API_URL environment variable.
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { createRequire } from "module";
 // =============================================================================
 // Configuration
 // =============================================================================
-const API_URL = process.env.SAAS_API_URL || process.env.API_URL || "https://api.example.com";
+// Read version from package.json so every surface (banner, API_OVERVIEW,
+// MCP Server metadata) stays in sync with whatever was last published.
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+const SERVER_VERSION = pkg.version;
+const API_URL = process.env.SAAS_API_URL || process.env.API_URL || "http://localhost:8001";
 const API_KEY = process.env.SAAS_API_KEY || process.env.API_KEY || "";
 // Cache for API responses
 const cache = new Map();
@@ -37,50 +43,65 @@ const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
  */
 const API_OVERVIEW = {
     name: "Multi-tenant SaaS API",
-    version: "2.2.0",
-    description: `
-This is a Backend-as-a-Service API for building SaaS applications.
-## Architecture Overview
-There are TWO types of authentication contexts:
-### 1. TENANT CONTEXT (Dashboard)
-- Used by: Tenant owners/admins managing their SaaS account
-- Authentication: JWT from /v1/tenant-auth/login
-- Purpose: Manage API keys, team members, view analytics, configure settings
-- These endpoints are NOT for end-user frontends
-### 2. END-USER CONTEXT (API)
-- Used by: End-users of applications built on top of this API
-- Authentication: API Key (X-API-Key header) + optional User JWT
-- Purpose: User auth, organizations, subscriptions, billing
-- These endpoints ARE for building end-user frontends
-## API Key Types
-- \`pk_live_*\`: Public key - safe to expose in frontend code (LIMITED to auth endpoints only)
-- \`sk_live_*\`: Secret key - backend only, never expose (FULL API access)
-## Security Features (for public keys)
-### Origin Validation
-Public keys (pk_live_*) require Origin header validation:
-- When creating a public key, the tenant specifies allowed origins
-- Requests from other origins are rejected
-- This prevents stolen API keys from being used on other domains
-### Rate Limiting (per IP)
-- Register: 3/hour (blocked 30 min after exceeding)
-- Login: 10/15 min (blocked 15 min after exceeding)
-- Forgot password: 3/hour (blocked 30 min after exceeding)
-- Resend verification: 3/hour (blocked 30 min after exceeding)
-## When Building a Frontend
-If you're building a frontend application for end-users, you should:
-1. Use ONLY the End-user endpoints (not Tenant/Dashboard endpoints)
-2. Use the public API key (pk_live_*) for client-side requests
-3. Include X-API-Key header in ALL requests
-4. After login, also include Authorization: Bearer <jwt> for authenticated requests
+    version: SERVER_VERSION,
+    description: `
+This is a Backend-as-a-Service API for building SaaS applications.
+## Architecture Overview
+There are TWO types of authentication contexts:
+### 1. TENANT CONTEXT (Dashboard)
+- Used by: Tenant owners/admins managing their SaaS account
+- Authentication: JWT from /v1/tenant-auth/login
+- Purpose: Manage API keys, team members, view analytics, configure settings
+- These endpoints are NOT for end-user frontends
+### 2. END-USER CONTEXT (API)
+- Used by: End-users of applications built on top of this API
+- Authentication: API Key (X-API-Key header) + optional User JWT
+- Purpose: User auth, organizations, subscriptions, billing
+- These endpoints ARE for building end-user frontends
+## API Key Types
+- \`pk_live_*\`: Public key - safe to expose in frontend code (LIMITED to auth endpoints only)
+- \`sk_live_*\`: Secret key - backend only, never expose (FULL API access)
+## API Key Organization Scope (B2B2C)
+Every API key is associated with exactly one organization inside a tenant:
+- **Root-org key** (tenant-wide): the key inherits the tenant's root organization. Callers MUST send \`X-Organization-Id\` to target a non-root customer organization.
+- **Customer-org key** (scoped): the key is bound to a specific customer organization. The organization context is resolved automatically from the key — the \`X-Organization-Id\` header is ignored for these keys.
+**Implication for end-user endpoints that list "X-Organization-Id required":**
+- If the request uses a root-org key → the header IS required.
+- If the request uses a customer-org-scoped key → the header is optional (the key's org wins). Sending a different org_id in the header has no effect; the scope of the key is authoritative.
+**Implication for \`POST /v1/auth/register\`:** the new end-user joins the API key's organization automatically as role=\`member\`. The platform no longer creates a "<email>'s Organization" per signup — that auto-spawn behavior was removed. Do not try to pass \`organization_id\` in the request body; it isn't part of the schema. The X-API-Key alone determines where the user lands.
+Tenants assign keys to customer organizations from their dashboard.
+## Security Features (for public keys)
+### Origin Validation
+Public keys (pk_live_*) require Origin header validation:
+- When creating a public key, the tenant specifies allowed origins
+- Requests from other origins are rejected
+- This prevents stolen API keys from being used on other domains
+### Rate Limiting (per IP)
+- Register: 3/hour (blocked 30 min after exceeding)
+- Login: 10/15 min (blocked 15 min after exceeding)
+- Forgot password: 3/hour (blocked 30 min after exceeding)
+- Resend verification: 3/hour (blocked 30 min after exceeding)
+## When Building a Frontend
+If you're building a frontend application for end-users, you should:
+1. Use ONLY the End-user endpoints (not Tenant/Dashboard endpoints)
+2. Use the public API key (pk_live_*) for client-side requests
+3. Include X-API-Key header in ALL requests
+4. After login, also include Authorization: Bearer <jwt> for authenticated requests
 `,
     base_url: API_URL,
     documentation_urls: {
@@ -128,12 +149,12 @@ const END_USER_ENDPOINTS = {
                     message: "Registration successful. Please check your email to verify your account.",
                     verification_required: "true"
                 },
-                note: "The response depends on whether the tenant has email verification enabled. When verification IS required, NO tokens are returned — the user must verify their email first, then login. Check for 'verification_required: true' in the response to show the appropriate UI.",
-                example_request: `{
-  "email": "user@example.com",
-  "password": "SecurePass123",
-  "display_name": "John Doe",
-  "return_to": "https://myapp.com/verify-email"
+                note: "Two important things:\n\n1) The response depends on whether the tenant has email verification enabled. When verification IS required, NO tokens are returned — the user must verify their email first, then login. Check for 'verification_required: true' in the response to show the appropriate UI.\n\n2) Organization assignment is automatic from the API key (B2B2C). The new end-user joins the organization the API key is scoped to (root-org or a customer-org) as role=member. NO per-user 'personal' organization is auto-spawned anymore. Do not pass any organization_id in the body — it isn't accepted, and the routing happens server-side from the X-API-Key.",
+                example_request: `{
+  "email": "user@example.com",
+  "password": "SecurePass123",
+  "display_name": "John Doe",
+  "return_to": "https://myapp.com/verify-email"
 }`
             },
             {
@@ -147,9 +168,9 @@ const END_USER_ENDPOINTS = {
                     password: "string (required)"
                 },
                 response: "Same as register",
-                example_request: `{
-  "email": "user@example.com",
-  "password": "SecurePass123"
+                example_request: `{
+  "email": "user@example.com",
+  "password": "SecurePass123"
 }`
             },
             {
@@ -317,10 +338,10 @@ const END_USER_ENDPOINTS = {
                     slug: "string (required) - URL-friendly identifier",
                     description: "string (optional)"
                 },
-                example_request: `{
-  "name": "My Company",
-  "slug": "my-company",
-  "description": "Our awesome company"
+                example_request: `{
+  "name": "My Company",
+  "slug": "my-company",
+  "description": "Our awesome company"
 }`
             },
             {
@@ -554,26 +575,26 @@ const END_USER_ENDPOINTS = {
                         updated_at: "ISO datetime"
                     }
                 ],
-                example_response: `[
-  {
-    "id": "550e8400-e29b-41d4-a716-446655440000",
-    "name": "Pro Plan",
-    "description": "For growing teams",
-    "price_monthly": 29.99,
-    "price_yearly": 299.99,
-    "currency": "usd",
-    "features": ["API Access", "Priority Support", "Advanced Analytics"],
-    "is_active": true,
-    "is_free": false,
-    "max_cost_usd_per_month": 100.00,
-    "max_messages_per_month": 1000,
-    "max_tokens_per_month": null,
-    "stripe_product_id": "prod_xxxxx",
-    "stripe_price_id_monthly": "price_xxxxx",
-    "stripe_price_id_yearly": "price_xxxxx",
-    "created_at": "2024-01-15T10:30:00Z",
-    "updated_at": "2024-01-15T10:30:00Z"
-  }
+                example_response: `[
+  {
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "name": "Pro Plan",
+    "description": "For growing teams",
+    "price_monthly": 29.99,
+    "price_yearly": 299.99,
+    "currency": "usd",
+    "features": ["API Access", "Priority Support", "Advanced Analytics"],
+    "is_active": true,
+    "is_free": false,
+    "max_cost_usd_per_month": 100.00,
+    "max_messages_per_month": 1000,
+    "max_tokens_per_month": null,
+    "stripe_product_id": "prod_xxxxx",
+    "stripe_price_id_monthly": "price_xxxxx",
+    "stripe_price_id_yearly": "price_xxxxx",
+    "created_at": "2024-01-15T10:30:00Z",
+    "updated_at": "2024-01-15T10:30:00Z"
+  }
 ]`
             },
             {
@@ -600,24 +621,24 @@ const END_USER_ENDPOINTS = {
                     created_at: "ISO datetime",
                     updated_at: "ISO datetime"
                 },
-                example_response: `{
-  "id": "550e8400-e29b-41d4-a716-446655440000",
-  "plan_id": "660e8400-e29b-41d4-a716-446655440001",
-  "organization_id": "770e8400-e29b-41d4-a716-446655440002",
-  "tenant_id": "880e8400-e29b-41d4-a716-446655440003",
-  "stripe_customer_id": "cus_xxxxx",
-  "stripe_subscription_id": "sub_xxxxx",
-  "billing_cycle": "monthly",
-  "status": "active",
-  "current_period_start": "2024-01-01T00:00:00Z",
-  "current_period_end": "2024-02-01T00:00:00Z",
-  "cancel_at_period_end": false,
-  "canceled_at": null,
-  "trial_start": null,
-  "trial_end": null,
-  "subscription_metadata": {},
-  "created_at": "2024-01-01T00:00:00Z",
-  "updated_at": "2024-01-01T00:00:00Z"
+                example_response: `{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "plan_id": "660e8400-e29b-41d4-a716-446655440001",
+  "organization_id": "770e8400-e29b-41d4-a716-446655440002",
+  "tenant_id": "880e8400-e29b-41d4-a716-446655440003",
+  "stripe_customer_id": "cus_xxxxx",
+  "stripe_subscription_id": "sub_xxxxx",
+  "billing_cycle": "monthly",
+  "status": "active",
+  "current_period_start": "2024-01-01T00:00:00Z",
+  "current_period_end": "2024-02-01T00:00:00Z",
+  "cancel_at_period_end": false,
+  "canceled_at": null,
+  "trial_start": null,
+  "trial_end": null,
+  "subscription_metadata": {},
+  "created_at": "2024-01-01T00:00:00Z",
+  "updated_at": "2024-01-01T00:00:00Z"
 }`,
                 note: "Does NOT include plan_name or price. Use plan_id to fetch plan details if needed."
             },
@@ -797,12 +818,12 @@ const END_USER_ENDPOINTS = {
                     price: "string - Display price",
                     message: "string | null"
                 },
-                example_request: `{
-  "user_id": "550e8400-e29b-41d4-a716-446655440000",
-  "organization_id": "660e8400-e29b-41d4-a716-446655440001",
-  "plan_id": "770e8400-e29b-41d4-a716-446655440002",
-  "success_url": "https://myapp.com/billing/success",
-  "cancel_url": "https://myapp.com/billing/cancel"
+                example_request: `{
+  "user_id": "550e8400-e29b-41d4-a716-446655440000",
+  "organization_id": "660e8400-e29b-41d4-a716-446655440001",
+  "plan_id": "770e8400-e29b-41d4-a716-446655440002",
+  "success_url": "https://myapp.com/billing/success",
+  "cancel_url": "https://myapp.com/billing/cancel"
 }`
             },
             {
@@ -824,9 +845,9 @@ const END_USER_ENDPOINTS = {
                     cancel_at_period_end: "boolean | null"
                 },
                 note: "Upgrades create Stripe prorations. Downgrades cancel at period end and schedule the new plan.",
-                example_request: `{
-  "subscription_id": "550e8400-e29b-41d4-a716-446655440000",
-  "new_plan_id": "660e8400-e29b-41d4-a716-446655440001"
+                example_request: `{
+  "subscription_id": "550e8400-e29b-41d4-a716-446655440000",
+  "new_plan_id": "660e8400-e29b-41d4-a716-446655440001"
 }`
             },
             {
@@ -899,31 +920,31 @@ const END_USER_ENDPOINTS = {
                     },
                     error: "string | null - Error message if any"
                 },
-                example_response: `{
-  "period_start": "2024-01-01T00:00:00Z",
-  "period_end": "2024-02-01T00:00:00Z",
-  "plan_name": "Pro Plan",
-  "plan_id": "550e8400-e29b-41d4-a716-446655440000",
-  "usage": {
-    "messages": {
-      "current": 450,
-      "max": 1000,
-      "remaining": 550,
-      "percentage": 45.0
-    },
-    "cost_usd": {
-      "current": 23.50,
-      "max": 100.0,
-      "remaining": 76.50,
-      "percentage": 23.5
-    },
-    "tokens": {
-      "total": 125000,
-      "input": 75000,
-      "output": 50000
-    }
-  },
-  "error": null
+                example_response: `{
+  "period_start": "2024-01-01T00:00:00Z",
+  "period_end": "2024-02-01T00:00:00Z",
+  "plan_name": "Pro Plan",
+  "plan_id": "550e8400-e29b-41d4-a716-446655440000",
+  "usage": {
+    "messages": {
+      "current": 450,
+      "max": 1000,
+      "remaining": 550,
+      "percentage": 45.0
+    },
+    "cost_usd": {
+      "current": 23.50,
+      "max": 100.0,
+      "remaining": 76.50,
+      "percentage": 23.5
+    },
+    "tokens": {
+      "total": 125000,
+      "input": 75000,
+      "output": 50000
+    }
+  },
+  "error": null
 }`
             },
             {
@@ -1077,26 +1098,26 @@ const END_USER_ENDPOINTS = {
                     execution_metadata: "object | null",
                     created_at: "ISO datetime"
                 },
-                example_request: `{
-  "messages": [
-    {"role": "user", "content": "Hello, how can you help me?"}
-  ],
-  "temperature": 0.7
+                example_request: `{
+  "messages": [
+    {"role": "user", "content": "Hello, how can you help me?"}
+  ],
+  "temperature": 0.7
 }`,
-                example_response: `{
-  "id": "550e8400-e29b-41d4-a716-446655440000",
-  "agent_id": "660e8400-e29b-41d4-a716-446655440001",
-  "tenant_id": "770e8400-e29b-41d4-a716-446655440002",
-  "user_id": "880e8400-e29b-41d4-a716-446655440003",
-  "organization_id": "990e8400-e29b-41d4-a716-446655440004",
-  "input_text": "Hello, how can you help me?",
-  "output_text": "I'm an AI assistant designed to help you with...",
-  "tokens_used": 150,
-  "execution_time_ms": 1234,
-  "status": "SUCCESS",
-  "error_message": null,
-  "execution_metadata": {"model": "gpt-4o", "temperature": 0.7},
-  "created_at": "2024-01-30T10:30:00Z"
+                example_response: `{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "agent_id": "660e8400-e29b-41d4-a716-446655440001",
+  "tenant_id": "770e8400-e29b-41d4-a716-446655440002",
+  "user_id": "880e8400-e29b-41d4-a716-446655440003",
+  "organization_id": "990e8400-e29b-41d4-a716-446655440004",
+  "input_text": "Hello, how can you help me?",
+  "output_text": "I'm an AI assistant designed to help you with...",
+  "tokens_used": 150,
+  "execution_time_ms": 1234,
+  "status": "SUCCESS",
+  "error_message": null,
+  "execution_metadata": {"model": "gpt-4o", "temperature": 0.7},
+  "created_at": "2024-01-30T10:30:00Z"
 }`,
                 note: "Usage is tracked against your plan limits. Use /v1/api/usage/current to check remaining usage."
             },
@@ -1507,13 +1528,13 @@ const END_USER_ENDPOINTS = {
                     order_dir: "'asc' | 'desc' (default 'desc')"
                 },
                 notes: "Supported operators: eq, ne, gt, gte, lt, lte, like, ilike, in, not_in",
-                example_request: `{
-  "schema_id": "550e8400-e29b-41d4-a716-446655440000",
-  "query": {
-    "price": { "operator": "gt", "value": 100 },
-    "category": "electronics",
-    "status": { "operator": "in", "value": ["active", "pending"] }
-  }
+                example_request: `{
+  "schema_id": "550e8400-e29b-41d4-a716-446655440000",
+  "query": {
+    "price": { "operator": "gt", "value": 100 },
+    "category": "electronics",
+    "status": { "operator": "in", "value": ["active", "pending"] }
+  }
 }`
             }
         ]
@@ -1706,7 +1727,7 @@ const END_USER_ENDPOINTS = {
         endpoints: [
             {
                 method: "POST",
-                path: "/v1/external-agents/{agent_id}/calls",
+                path: "/v1/user/external-agents/{agent_id}/calls",
                 summary: "Register an external agent call",
                 auth: { api_key: "sk_live_*", jwt: true },
                 rate_limit: "120 per minute per IP",
@@ -1721,6 +1742,7 @@ const END_USER_ENDPOINTS = {
                     total_tokens: "integer (optional) - Total tokens. If not provided, calculated as input + output",
                     cost_usd: "number (optional, default: 0.0) - Cost in USD",
                     duration_ms: "integer (optional, default: 0) - Call duration in milliseconds",
+                    model_name: "string (optional) - Model used (e.g., openai/gpt-4o). If provided, cost is calculated from provider rates instead of flat rate",
                     status: "string (optional, default: 'SUCCESS') - 'SUCCESS' or 'ERROR'",
                     error_message: "string (optional) - Error message if status is ERROR",
                     call_metadata: "object (optional) - Arbitrary metadata about the call"
@@ -1741,7 +1763,60 @@ const END_USER_ENDPOINTS = {
                     call_metadata: "object | null",
                     created_at: "ISO datetime"
                 },
-                note: "Does NOT add to tenant billing — the tenant pays the AI provider directly. This endpoint is for tracking/analytics only."
+                note: "Adds a fixed cost (EXTERNAL_AGENT_REQUEST_COST env var, default $0.01) to tenant billing. If model_name is provided with tokens > 0, cost is calculated from provider rates instead."
+            },
+            {
+                method: "POST",
+                path: "/v1/user/external-agents/{agent_id}/usage",
+                summary: "Register usage metrics for an external agent",
+                auth: { api_key: "sk_live_*", jwt: true },
+                rate_limit: "120 per minute per IP",
+                path_params: {
+                    agent_id: "uuid (required) - The external agent ID"
+                },
+                request_body: {
+                    input_tokens: "integer (optional, default: 0) - Number of input tokens consumed",
+                    output_tokens: "integer (optional, default: 0) - Number of output tokens consumed",
+                    cost_usd: "number (optional) - Explicit cost in USD. If omitted, calculated from model rates or flat rate",
+                    model_name: "string (optional) - Model used (e.g., openai/gpt-4o)",
+                    provider: "string (optional) - Provider name (e.g., openai, anthropic). Defaults to 'external_agent'",
+                    metadata: "object (optional) - Arbitrary metadata"
+                },
+                response: {
+                    tracked: "boolean - Whether usage was tracked successfully",
+                    tokens: "integer - Total tokens tracked",
+                    cost_usd: "number - Cost tracked in USD",
+                    model_name: "string - Model name used for tracking",
+                    provider: "string - Provider name used for tracking"
+                },
+                note: "Use this for batch usage reporting or updating token counts without creating a full call record. Tracks tokens and cost in tenant billing."
+            },
+            {
+                method: "POST",
+                path: "/v1/user/external-agents/{agent_id}/execute",
+                summary: "Execute an external agent via its configured webhook",
+                auth: { api_key: "sk_live_*", jwt: true },
+                rate_limit: "60 per minute per IP",
+                path_params: {
+                    agent_id: "uuid (required) - The external agent ID"
+                },
+                request_body: {
+                    input: "string (required) - Input text forwarded to the external agent",
+                    metadata: "object (optional) - Arbitrary context forwarded to the webhook"
+                },
+                response: {
+                    output: "string - Agent response text",
+                    input_tokens: "integer - Input tokens reported by the webhook",
+                    output_tokens: "integer - Output tokens reported by the webhook",
+                    total_tokens: "integer - input + output",
+                    duration_ms: "integer - Execution time measured by Genlobe",
+                    cost_usd: "number - Platform fee registered for this call",
+                    model_name: "string | null - Model reported by the webhook",
+                    status: "string - SUCCESS or ERROR",
+                    error_message: "string | null",
+                    call_id: "uuid | null - Registered call record"
+                },
+                note: "Requires the external agent to have webhook_url configured. Genlobe POSTs {agent_id, input, metadata} to the webhook and expects {output, input_tokens?, output_tokens?, model_name?} in the JSON response."
             }
         ]
     }
@@ -1749,619 +1824,619 @@ const END_USER_ENDPOINTS = {
 // =============================================================================
 // TypeScript/JavaScript SDK Template
 // =============================================================================
-const SDK_TEMPLATE_TYPESCRIPT = `/**
- * Multi-tenant SaaS API Client
- *
- * Usage:
- * const api = new ApiClient('pk_live_your_key_here', 'https://api.yoursaas.com');
- *
- * // Login
- * const { access_token, user } = await api.auth.login('email@example.com', 'password');
- *
- * // Set token for authenticated requests
- * api.setAccessToken(access_token);
- *
- * // Get user's organizations
- * const orgs = await api.organizations.getMyOrganizations();
- */
-interface TokenResponse {
-  access_token: string;
-  refresh_token: string;
-  token_type: string;
-  expires_in: number;
-  user: {
-    id: string;
-    email: string;
-    display_name: string | null;
-    avatar_url: string | null;
-    is_active: boolean;
-    created_at: string;
-  };
-}
-interface Organization {
-  id: string;
-  name: string;
-  slug: string;
-  description?: string;
-  logo_url?: string;
-  role: 'owner' | 'admin' | 'member' | 'developer';
-  created_at: string;
-}
-interface ApiError {
-  detail: string;
-  error?: string;
-  error_description?: string;
-}
-class ApiClient {
-  private apiKey: string;
-  private baseUrl: string;
-  private accessToken: string | null = null;
-  private refreshToken: string | null = null;
-  constructor(apiKey: string, baseUrl: string) {
-    if (!apiKey) throw new Error('API key is required');
-    if (!baseUrl) throw new Error('Base URL is required');
-    this.apiKey = apiKey;
-    this.baseUrl = baseUrl.replace(/\\/$/, ''); // Remove trailing slash
-  }
-  setAccessToken(token: string) {
-    this.accessToken = token;
-  }
-  setRefreshToken(token: string) {
-    this.refreshToken = token;
-  }
-  private organizationId: string | null = null;
-  setOrganizationId(orgId: string) {
-    this.organizationId = orgId;
-  }
-  private async request<T>(
-    method: string,
-    endpoint: string,
-    body?: any,
-    requiresAuth = false
-  ): Promise<T> {
-    const headers: Record<string, string> = {
-      'X-API-Key': this.apiKey,
-      'Content-Type': 'application/json',
-    };
-    if (requiresAuth && this.accessToken) {
-      headers['Authorization'] = \`Bearer \${this.accessToken}\`;
-    }
-    if (this.organizationId) {
-      headers['X-Organization-Id'] = this.organizationId;
-    }
-    const response = await fetch(\`\${this.baseUrl}\${endpoint}\`, {
-      method,
-      headers,
-      body: body ? JSON.stringify(body) : undefined,
-    });
-    if (!response.ok) {
-      const error: ApiError = await response.json();
-      throw new Error(error.detail || \`Request failed: \${response.status}\`);
-    }
-    return response.json();
-  }
-  // Auth endpoints
-  auth = {
-    register: async (email: string, password: string, displayName?: string) => {
-      const result = await this.request<TokenResponse>('POST', '/v1/auth/register', {
-        email,
-        password,
-        display_name: displayName,
-      });
-      this.accessToken = result.access_token;
-      this.refreshToken = result.refresh_token;
-      return result;
-    },
-    login: async (email: string, password: string) => {
-      const result = await this.request<TokenResponse>('POST', '/v1/auth/login', {
-        email,
-        password,
-      });
-      this.accessToken = result.access_token;
-      this.refreshToken = result.refresh_token;
-      return result;
-    },
-    logout: async () => {
-      await this.request('POST', '/v1/auth/logout', undefined, true);
-      this.accessToken = null;
-      this.refreshToken = null;
-    },
-    me: async () => {
-      return this.request<TokenResponse['user']>('GET', '/v1/auth/me', undefined, true);
-    },
-    refresh: async () => {
-      if (!this.refreshToken) throw new Error('No refresh token available');
-      const result = await this.request<TokenResponse>('POST', '/v1/auth/refresh', {
-        refresh_token: this.refreshToken,
-      });
-      this.accessToken = result.access_token;
-      return result;
-    },
-    forgotPassword: async (email: string) => {
-      return this.request('POST', '/v1/auth/forgot-password', { email });
-    },
-    resetPassword: async (token: string, newPassword: string) => {
-      return this.request('POST', '/v1/auth/reset-password', {
-        token,
-        new_password: newPassword,
-      });
-    },
-    changePassword: async (currentPassword: string, newPassword: string) => {
-      return this.request('POST', '/v1/auth/change-password', {
-        current_password: currentPassword,
-        new_password: newPassword,
-      });
-    },
-    verifyEmail: async (token: string) => {
-      return this.request('POST', '/v1/auth/verify-email', { token });
-    },
-    resendVerification: async (email: string) => {
-      return this.request('POST', '/v1/auth/resend-verification', { email });
-    },
-    getProviders: async () => {
-      return this.request<{ providers: Array<{ provider: string; name: string }> }>(
-        'GET', '/v1/auth/providers'
-      );
-    },
-    getGoogleAuthUrl: async (redirectUri: string) => {
-      return this.request<{ authorization_url: string }>(
-        'GET', \`/v1/auth/google/url?redirect_uri=\${encodeURIComponent(redirectUri)}\`
-      );
-    },
-  };
-  // Agent endpoints
-  agents = {
-    getAvailable: async (skip = 0, limit = 50) => {
-      return this.request(
-        'GET',
-        \`/v1/user/agents/available?skip=\${skip}&limit=\${limit}\`,
-        undefined,
-        true
-      );
-    },
-    get: async (agentId: string) => {
-      return this.request('GET', \`/v1/user/agents/\${agentId}\`, undefined, true);
-    },
-    chat: async (agentId: string, messages: Array<{ role: string; content: string }>, options?: { temperature?: number; model?: string; conversation_id?: string }) => {
-      return this.request('POST', \`/v1/user/agents/\${agentId}/chat\`, {
-        messages,
-        ...options,
-      }, true);
-    },
-    getHistory: async (agentId: string, skip = 0, limit = 20) => {
-      return this.request(
-        'GET',
-        \`/v1/user/agents/\${agentId}/history?skip=\${skip}&limit=\${limit}\`,
-        undefined,
-        true
-      );
-    },
-    createConversation: async (agentId: string, title?: string) => {
-      return this.request('POST', \`/v1/user/agents/\${agentId}/conversations\`, {
-        title,
-      }, true);
-    },
-    listConversations: async (agentId: string, skip = 0, limit = 20) => {
-      return this.request(
-        'GET',
-        \`/v1/user/agents/\${agentId}/conversations?skip=\${skip}&limit=\${limit}\`,
-        undefined,
-        true
-      );
-    },
-    getConversation: async (agentId: string, conversationId: string) => {
-      return this.request(
-        'GET',
-        \`/v1/user/agents/\${agentId}/conversations/\${conversationId}\`,
-        undefined,
-        true
-      );
-    },
-    endConversation: async (agentId: string, conversationId: string) => {
-      return this.request(
-        'DELETE',
-        \`/v1/user/agents/\${agentId}/conversations/\${conversationId}\`,
-        undefined,
-        true
-      );
-    },
-  };
-  // Organization endpoints
-  organizations = {
-    getMyOrganizations: async () => {
-      return this.request<{ organizations: Organization[] }>(
-        'GET',
-        '/v1/organizations/my-organizations',
-        undefined,
-        true
-      );
-    },
-    create: async (name: string, slug: string, description?: string) => {
-      return this.request<Organization>(
-        'POST',
-        '/v1/organizations',
-        { name, slug, description },
-        true
-      );
-    },
-    get: async (id: string) => {
-      return this.request<Organization>(
-        'GET',
-        \`/v1/organizations/\${id}\`,
-        undefined,
-        true
-      );
-    },
-    update: async (id: string, data: { name?: string; description?: string }) => {
-      return this.request<Organization>(
-        'PUT',
-        \`/v1/organizations/\${id}\`,
-        data,
-        true
-      );
-    },
-    getMembers: async (id: string) => {
-      return this.request(
-        'GET',
-        \`/v1/organizations/\${id}/members\`,
-        undefined,
-        true
-      );
-    },
-    invite: async (id: string, email: string, role: 'admin' | 'member' | 'developer') => {
-      return this.request(
-        'POST',
-        \`/v1/organizations/\${id}/invite\`,
-        { email, role },
-        true
-      );
-    },
-    acceptInvitation: async (token: string) => {
-      return this.request(
-        'POST',
-        '/v1/organizations/accept-invitation',
-        { token },
-        true
-      );
-    },
-    rejectInvitation: async (token: string) => {
-      return this.request(
-        'POST',
-        '/v1/organizations/reject-invitation',
-        { token }
-      );
-    },
-    updateMemberRole: async (orgId: string, userId: string, role: 'admin' | 'member' | 'developer') => {
-      return this.request(
-        'PUT',
-        \`/v1/organizations/\${orgId}/members/\${userId}\`,
-        { role },
-        true
-      );
-    },
-    removeMember: async (orgId: string, userId: string) => {
-      return this.request(
-        'DELETE',
-        \`/v1/organizations/\${orgId}/members/\${userId}\`,
-        undefined,
-        true
-      );
-    },
-    deactivateMember: async (orgId: string, userId: string) => {
-      return this.request(
-        'POST',
-        \`/v1/organizations/\${orgId}/members/\${userId}/deactivate\`,
-        undefined,
-        true
-      );
-    },
-    setDefault: async (orgId: string) => {
-      return this.request(
-        'POST',
-        \`/v1/organizations/\${orgId}/set-default\`,
-        undefined,
-        true
-      );
-    },
-    getSubscription: async (orgId: string) => {
-      return this.request('GET', \`/v1/organizations/\${orgId}/subscription\`, undefined, true);
-    },
-    subscribe: async (orgId: string, planId: string) => {
-      return this.request('POST', \`/v1/organizations/\${orgId}/subscription/\${planId}\`, undefined, true);
-    },
-    cancelSubscription: async (orgId: string) => {
-      return this.request('DELETE', \`/v1/organizations/\${orgId}/subscription\`, undefined, true);
-    },
-    getUsage: async (orgId: string) => {
-      return this.request('GET', \`/v1/organizations/\${orgId}/usage\`, undefined, true);
-    },
-  };
-  // Subscription endpoints
-  subscriptions = {
-    getPlans: async () => {
-      return this.request('GET', '/v1/subscriptions/plans', undefined, true);
-    },
-    getCurrent: async () => {
-      return this.request('GET', '/v1/subscriptions/current', undefined, true);
-    },
-    checkout: async (planId: string, successUrl: string, cancelUrl: string) => {
-      return this.request<{ checkout_url: string; session_id: string }>(
-        'POST',
-        '/v1/subscriptions/checkout',
-        {
-          plan_id: planId,
-          success_url: successUrl,
-          cancel_url: cancelUrl,
-        },
-        true
-      );
-    },
-    getById: async (subscriptionId: string) => {
-      return this.request('GET', \`/v1/subscriptions/subscriptions/\${subscriptionId}\`, undefined, true);
-    },
-    cancel: async (subscriptionId: string, cancelAtPeriodEnd = true) => {
-      return this.request(
-        'DELETE',
-        \`/v1/subscriptions/subscriptions/\${subscriptionId}?cancel_at_period_end=\${cancelAtPeriodEnd}\`,
-        undefined,
-        true
-      );
-    },
-  };
-  // Billing endpoints (sk_live_* only)
-  billing = {
-    getAvailablePlans: async () => {
-      return this.request('GET', '/v1/billing/available-plans', undefined, true);
-    },
-    createCheckoutSession: async (data: { user_id: string; organization_id: string; plan_id: string; success_url: string; cancel_url: string }) => {
-      return this.request<{ checkout_url: string; session_id: string; plan_name: string; price: string }>('POST', '/v1/billing/create-checkout-session', data, true);
-    },
-    changePlan: async (data: { subscription_id: string; new_plan_id: string }) => {
-      return this.request('POST', '/v1/billing/change-plan', data, true);
-    },
-    cancelSubscription: async (subscriptionId: string, cancelAtPeriodEnd = true) => {
-      return this.request('POST', \`/v1/billing/cancel-subscription?subscription_id=\${subscriptionId}&cancel_at_period_end=\${cancelAtPeriodEnd}\`, undefined, true);
-    },
-    getBillingHistory: async (organizationId: string, limit = 20) => {
-      return this.request('GET', \`/v1/billing/billing-history-org/\${organizationId}?limit=\${limit}\`, undefined, true);
-    },
-  };
-  // Plans endpoints (JWT required)
-  plans = {
-    list: async (skip = 0, limit = 100, includeInactive = false) => {
-      return this.request('GET', \`/v1/plans?skip=\${skip}&limit=\${limit}&include_inactive=\${includeInactive}\`, undefined, true);
-    },
-    getActive: async () => {
-      return this.request('GET', '/v1/plans/active', undefined, true);
-    },
-    getFree: async () => {
-      return this.request('GET', '/v1/plans/free', undefined, true);
-    },
-    getById: async (planId: string) => {
-      return this.request('GET', \`/v1/plans/\${planId}\`, undefined, true);
-    },
-  };
-  // User management endpoints
-  users = {
-    list: async (page = 1, perPage = 20, includeInactive = false) => {
-      return this.request('GET', \`/v1/users?page=\${page}&per_page=\${perPage}&include_inactive=\${includeInactive}\`, undefined, true);
-    },
-    stats: async () => {
-      return this.request('GET', '/v1/users/stats', undefined, true);
-    },
-    get: async (userId: string, includeSettings = false) => {
-      return this.request('GET', \`/v1/users/\${userId}?include_settings=\${includeSettings}\`, undefined, true);
-    },
-    update: async (userId: string, data: { display_name?: string; avatar_url?: string; locale?: string }) => {
-      return this.request('PUT', \`/v1/users/\${userId}\`, data, true);
-    },
-    updateSettings: async (userId: string, settings: any) => {
-      return this.request('PUT', \`/v1/users/\${userId}/settings\`, settings, true);
-    },
-    deactivate: async (userId: string) => {
-      return this.request('POST', \`/v1/users/\${userId}/deactivate\`, undefined, true);
-    },
-    activate: async (userId: string) => {
-      return this.request('POST', \`/v1/users/\${userId}/activate\`, undefined, true);
-    },
-    delete: async (userId: string) => {
-      return this.request('DELETE', \`/v1/users/\${userId}\`, undefined, true);
-    },
-  };
-  // Usage endpoints
-  usage = {
-    getCurrent: async (organizationId: string) => {
-      return this.request('GET', \`/v1/api/usage/current?organization_id=\${organizationId}\`, undefined, true);
-    },
-    getHistory: async (organizationId: string, limit = 20, offset = 0) => {
-      return this.request(
-        'GET',
-        \`/v1/api/usage/history?organization_id=\${organizationId}&limit=\${limit}&offset=\${offset}\`,
-        undefined,
-        true
-      );
-    },
-    getEntityUsage: async (organizationId: string) => {
-      return this.request('GET', \`/v1/api/usage/entity-usage?organization_id=\${organizationId}\`, undefined, true);
-    },
-    getStats: async (organizationId: string) => {
-      return this.request('GET', \`/v1/usage/stats?organization_id=\${organizationId}\`, undefined, true);
-    },
-    check: async (data: { tokens: number; usage_type?: string; user_id: string; organization_id: string }) => {
-      return this.request('POST', '/v1/usage/check', data, true);
-    },
-    consume: async (data: { tokens: number; usage_type?: string; user_id: string; organization_id: string }) => {
-      return this.request('POST', '/v1/usage/consume', data, true);
-    },
-  };
-  // Entity Schema endpoints
-  entitySchemas = {
-    list: async (page = 1, size = 20) => {
-      return this.request('GET', \`/v1/entity/schemas?page=\${page}&size=\${size}\`, undefined, true);
-    },
-    create: async (data: { name: string; slug: string; description?: string; fields_definition: any }) => {
-      return this.request('POST', '/v1/entity/schemas', data, true);
-    },
-    get: async (schemaId: string) => {
-      return this.request('GET', \`/v1/entity/schemas/\${schemaId}\`, undefined, true);
-    },
-    update: async (schemaId: string, data: { name?: string; description?: string; fields_definition?: any; is_active?: boolean }) => {
-      return this.request('PUT', \`/v1/entity/schemas/\${schemaId}\`, data, true);
-    },
-    delete: async (schemaId: string) => {
-      return this.request('DELETE', \`/v1/entity/schemas/\${schemaId}\`, undefined, true);
-    },
-  };
-  // Entity Record endpoints
-  entityRecords = {
-    create: async (schemaId: string, data: any) => {
-      return this.request('POST', '/v1/entity/records', { schema_id: schemaId, data }, true);
-    },
-    get: async (recordId: string) => {
-      return this.request('GET', \`/v1/entity/records/\${recordId}\`, undefined, true);
-    },
-    update: async (recordId: string, data: any) => {
-      return this.request('PUT', \`/v1/entity/records/\${recordId}\`, { data }, true);
-    },
-    delete: async (recordId: string) => {
-      return this.request('DELETE', \`/v1/entity/records/\${recordId}\`, undefined, true);
-    },
-    search: async (searchReq: { schema_id?: string; query?: any; page?: number; size?: number; order_by?: string; order_dir?: string }) => {
-      const params = new URLSearchParams();
-      if (searchReq.page) params.set('page', String(searchReq.page));
-      if (searchReq.size) params.set('size', String(searchReq.size));
-      if (searchReq.order_by) params.set('order_by', searchReq.order_by);
-      if (searchReq.order_dir) params.set('order_dir', searchReq.order_dir);
-      return this.request('POST', \`/v1/entity/records/search?\${params}\`, { schema_id: searchReq.schema_id, query: searchReq.query }, true);
-    },
-  };
-  // Department endpoints
-  departments = {
-    get: async (departmentId: string, userId: string) => {
-      return this.request('GET', \`/v1/departments/\${departmentId}?user_id=\${userId}\`, undefined, true);
-    },
-  };
-}
-export { ApiClient, TokenResponse, Organization, ApiError };
+const SDK_TEMPLATE_TYPESCRIPT = `/**
+ * Multi-tenant SaaS API Client
+ *
+ * Usage:
+ * const api = new ApiClient('pk_live_your_key_here', 'https://api.yoursaas.com');
+ *
+ * // Login
+ * const { access_token, user } = await api.auth.login('email@example.com', 'password');
+ *
+ * // Set token for authenticated requests
+ * api.setAccessToken(access_token);
+ *
+ * // Get user's organizations
+ * const orgs = await api.organizations.getMyOrganizations();
+ */
+interface TokenResponse {
+  access_token: string;
+  refresh_token: string;
+  token_type: string;
+  expires_in: number;
+  user: {
+    id: string;
+    email: string;
+    display_name: string | null;
+    avatar_url: string | null;
+    is_active: boolean;
+    created_at: string;
+  };
+}
+interface Organization {
+  id: string;
+  name: string;
+  slug: string;
+  description?: string;
+  logo_url?: string;
+  role: 'owner' | 'admin' | 'member' | 'developer';
+  created_at: string;
+}
+interface ApiError {
+  detail: string;
+  error?: string;
+  error_description?: string;
+}
+class ApiClient {
+  private apiKey: string;
+  private baseUrl: string;
+  private accessToken: string | null = null;
+  private refreshToken: string | null = null;
+  constructor(apiKey: string, baseUrl: string) {
+    if (!apiKey) throw new Error('API key is required');
+    if (!baseUrl) throw new Error('Base URL is required');
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\\/$/, ''); // Remove trailing slash
+  }
+  setAccessToken(token: string) {
+    this.accessToken = token;
+  }
+  setRefreshToken(token: string) {
+    this.refreshToken = token;
+  }
+  private organizationId: string | null = null;
+  setOrganizationId(orgId: string) {
+    this.organizationId = orgId;
+  }
+  private async request<T>(
+    method: string,
+    endpoint: string,
+    body?: any,
+    requiresAuth = false
+  ): Promise<T> {
+    const headers: Record<string, string> = {
+      'X-API-Key': this.apiKey,
+      'Content-Type': 'application/json',
+    };
+    if (requiresAuth && this.accessToken) {
+      headers['Authorization'] = \`Bearer \${this.accessToken}\`;
+    }
+    if (this.organizationId) {
+      headers['X-Organization-Id'] = this.organizationId;
+    }
+    const response = await fetch(\`\${this.baseUrl}\${endpoint}\`, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!response.ok) {
+      const error: ApiError = await response.json();
+      throw new Error(error.detail || \`Request failed: \${response.status}\`);
+    }
+    return response.json();
+  }
+  // Auth endpoints
+  auth = {
+    register: async (email: string, password: string, displayName?: string) => {
+      const result = await this.request<TokenResponse>('POST', '/v1/auth/register', {
+        email,
+        password,
+        display_name: displayName,
+      });
+      this.accessToken = result.access_token;
+      this.refreshToken = result.refresh_token;
+      return result;
+    },
+    login: async (email: string, password: string) => {
+      const result = await this.request<TokenResponse>('POST', '/v1/auth/login', {
+        email,
+        password,
+      });
+      this.accessToken = result.access_token;
+      this.refreshToken = result.refresh_token;
+      return result;
+    },
+    logout: async () => {
+      await this.request('POST', '/v1/auth/logout', undefined, true);
+      this.accessToken = null;
+      this.refreshToken = null;
+    },
+    me: async () => {
+      return this.request<TokenResponse['user']>('GET', '/v1/auth/me', undefined, true);
+    },
+    refresh: async () => {
+      if (!this.refreshToken) throw new Error('No refresh token available');
+      const result = await this.request<TokenResponse>('POST', '/v1/auth/refresh', {
+        refresh_token: this.refreshToken,
+      });
+      this.accessToken = result.access_token;
+      return result;
+    },
+    forgotPassword: async (email: string) => {
+      return this.request('POST', '/v1/auth/forgot-password', { email });
+    },
+    resetPassword: async (token: string, newPassword: string) => {
+      return this.request('POST', '/v1/auth/reset-password', {
+        token,
+        new_password: newPassword,
+      });
+    },
+    changePassword: async (currentPassword: string, newPassword: string) => {
+      return this.request('POST', '/v1/auth/change-password', {
+        current_password: currentPassword,
+        new_password: newPassword,
+      });
+    },
+    verifyEmail: async (token: string) => {
+      return this.request('POST', '/v1/auth/verify-email', { token });
+    },
+    resendVerification: async (email: string) => {
+      return this.request('POST', '/v1/auth/resend-verification', { email });
+    },
+    getProviders: async () => {
+      return this.request<{ providers: Array<{ provider: string; name: string }> }>(
+        'GET', '/v1/auth/providers'
+      );
+    },
+    getGoogleAuthUrl: async (redirectUri: string) => {
+      return this.request<{ authorization_url: string }>(
+        'GET', \`/v1/auth/google/url?redirect_uri=\${encodeURIComponent(redirectUri)}\`
+      );
+    },
+  };
+  // Agent endpoints
+  agents = {
+    getAvailable: async (skip = 0, limit = 50) => {
+      return this.request(
+        'GET',
+        \`/v1/user/agents/available?skip=\${skip}&limit=\${limit}\`,
+        undefined,
+        true
+      );
+    },
+    get: async (agentId: string) => {
+      return this.request('GET', \`/v1/user/agents/\${agentId}\`, undefined, true);
+    },
+    chat: async (agentId: string, messages: Array<{ role: string; content: string }>, options?: { temperature?: number; model?: string; conversation_id?: string }) => {
+      return this.request('POST', \`/v1/user/agents/\${agentId}/chat\`, {
+        messages,
+        ...options,
+      }, true);
+    },
+    getHistory: async (agentId: string, skip = 0, limit = 20) => {
+      return this.request(
+        'GET',
+        \`/v1/user/agents/\${agentId}/history?skip=\${skip}&limit=\${limit}\`,
+        undefined,
+        true
+      );
+    },
+    createConversation: async (agentId: string, title?: string) => {
+      return this.request('POST', \`/v1/user/agents/\${agentId}/conversations\`, {
+        title,
+      }, true);
+    },
+    listConversations: async (agentId: string, skip = 0, limit = 20) => {
+      return this.request(
+        'GET',
+        \`/v1/user/agents/\${agentId}/conversations?skip=\${skip}&limit=\${limit}\`,
+        undefined,
+        true
+      );
+    },
+    getConversation: async (agentId: string, conversationId: string) => {
+      return this.request(
+        'GET',
+        \`/v1/user/agents/\${agentId}/conversations/\${conversationId}\`,
+        undefined,
+        true
+      );
+    },
+    endConversation: async (agentId: string, conversationId: string) => {
+      return this.request(
+        'DELETE',
+        \`/v1/user/agents/\${agentId}/conversations/\${conversationId}\`,
+        undefined,
+        true
+      );
+    },
+  };
+  // Organization endpoints
+  organizations = {
+    getMyOrganizations: async () => {
+      return this.request<{ organizations: Organization[] }>(
+        'GET',
+        '/v1/organizations/my-organizations',
+        undefined,
+        true
+      );
+    },
+    create: async (name: string, slug: string, description?: string) => {
+      return this.request<Organization>(
+        'POST',
+        '/v1/organizations',
+        { name, slug, description },
+        true
+      );
+    },
+    get: async (id: string) => {
+      return this.request<Organization>(
+        'GET',
+        \`/v1/organizations/\${id}\`,
+        undefined,
+        true
+      );
+    },
+    update: async (id: string, data: { name?: string; description?: string }) => {
+      return this.request<Organization>(
+        'PUT',
+        \`/v1/organizations/\${id}\`,
+        data,
+        true
+      );
+    },
+    getMembers: async (id: string) => {
+      return this.request(
+        'GET',
+        \`/v1/organizations/\${id}/members\`,
+        undefined,
+        true
+      );
+    },
+    invite: async (id: string, email: string, role: 'admin' | 'member' | 'developer') => {
+      return this.request(
+        'POST',
+        \`/v1/organizations/\${id}/invite\`,
+        { email, role },
+        true
+      );
+    },
+    acceptInvitation: async (token: string) => {
+      return this.request(
+        'POST',
+        '/v1/organizations/accept-invitation',
+        { token },
+        true
+      );
+    },
+    rejectInvitation: async (token: string) => {
+      return this.request(
+        'POST',
+        '/v1/organizations/reject-invitation',
+        { token }
+      );
+    },
+    updateMemberRole: async (orgId: string, userId: string, role: 'admin' | 'member' | 'developer') => {
+      return this.request(
+        'PUT',
+        \`/v1/organizations/\${orgId}/members/\${userId}\`,
+        { role },
+        true
+      );
+    },
+    removeMember: async (orgId: string, userId: string) => {
+      return this.request(
+        'DELETE',
+        \`/v1/organizations/\${orgId}/members/\${userId}\`,
+        undefined,
+        true
+      );
+    },
+    deactivateMember: async (orgId: string, userId: string) => {
+      return this.request(
+        'POST',
+        \`/v1/organizations/\${orgId}/members/\${userId}/deactivate\`,
+        undefined,
+        true
+      );
+    },
+    setDefault: async (orgId: string) => {
+      return this.request(
+        'POST',
+        \`/v1/organizations/\${orgId}/set-default\`,
+        undefined,
+        true
+      );
+    },
+    getSubscription: async (orgId: string) => {
+      return this.request('GET', \`/v1/organizations/\${orgId}/subscription\`, undefined, true);
+    },
+    subscribe: async (orgId: string, planId: string) => {
+      return this.request('POST', \`/v1/organizations/\${orgId}/subscription/\${planId}\`, undefined, true);
+    },
+    cancelSubscription: async (orgId: string) => {
+      return this.request('DELETE', \`/v1/organizations/\${orgId}/subscription\`, undefined, true);
+    },
+    getUsage: async (orgId: string) => {
+      return this.request('GET', \`/v1/organizations/\${orgId}/usage\`, undefined, true);
+    },
+  };
+  // Subscription endpoints
+  subscriptions = {
+    getPlans: async () => {
+      return this.request('GET', '/v1/subscriptions/plans', undefined, true);
+    },
+    getCurrent: async () => {
+      return this.request('GET', '/v1/subscriptions/current', undefined, true);
+    },
+    checkout: async (planId: string, successUrl: string, cancelUrl: string) => {
+      return this.request<{ checkout_url: string; session_id: string }>(
+        'POST',
+        '/v1/subscriptions/checkout',
+        {
+          plan_id: planId,
+          success_url: successUrl,
+          cancel_url: cancelUrl,
+        },
+        true
+      );
+    },
+    getById: async (subscriptionId: string) => {
+      return this.request('GET', \`/v1/subscriptions/subscriptions/\${subscriptionId}\`, undefined, true);
+    },
+    cancel: async (subscriptionId: string, cancelAtPeriodEnd = true) => {
+      return this.request(
+        'DELETE',
+        \`/v1/subscriptions/subscriptions/\${subscriptionId}?cancel_at_period_end=\${cancelAtPeriodEnd}\`,
+        undefined,
+        true
+      );
+    },
+  };
+  // Billing endpoints (sk_live_* only)
+  billing = {
+    getAvailablePlans: async () => {
+      return this.request('GET', '/v1/billing/available-plans', undefined, true);
+    },
+    createCheckoutSession: async (data: { user_id: string; organization_id: string; plan_id: string; success_url: string; cancel_url: string }) => {
+      return this.request<{ checkout_url: string; session_id: string; plan_name: string; price: string }>('POST', '/v1/billing/create-checkout-session', data, true);
+    },
+    changePlan: async (data: { subscription_id: string; new_plan_id: string }) => {
+      return this.request('POST', '/v1/billing/change-plan', data, true);
+    },
+    cancelSubscription: async (subscriptionId: string, cancelAtPeriodEnd = true) => {
+      return this.request('POST', \`/v1/billing/cancel-subscription?subscription_id=\${subscriptionId}&cancel_at_period_end=\${cancelAtPeriodEnd}\`, undefined, true);
+    },
+    getBillingHistory: async (organizationId: string, limit = 20) => {
+      return this.request('GET', \`/v1/billing/billing-history-org/\${organizationId}?limit=\${limit}\`, undefined, true);
+    },
+  };
+  // Plans endpoints (JWT required)
+  plans = {
+    list: async (skip = 0, limit = 100, includeInactive = false) => {
+      return this.request('GET', \`/v1/plans?skip=\${skip}&limit=\${limit}&include_inactive=\${includeInactive}\`, undefined, true);
+    },
+    getActive: async () => {
+      return this.request('GET', '/v1/plans/active', undefined, true);
+    },
+    getFree: async () => {
+      return this.request('GET', '/v1/plans/free', undefined, true);
+    },
+    getById: async (planId: string) => {
+      return this.request('GET', \`/v1/plans/\${planId}\`, undefined, true);
+    },
+  };
+  // User management endpoints
+  users = {
+    list: async (page = 1, perPage = 20, includeInactive = false) => {
+      return this.request('GET', \`/v1/users?page=\${page}&per_page=\${perPage}&include_inactive=\${includeInactive}\`, undefined, true);
+    },
+    stats: async () => {
+      return this.request('GET', '/v1/users/stats', undefined, true);
+    },
+    get: async (userId: string, includeSettings = false) => {
+      return this.request('GET', \`/v1/users/\${userId}?include_settings=\${includeSettings}\`, undefined, true);
+    },
+    update: async (userId: string, data: { display_name?: string; avatar_url?: string; locale?: string }) => {
+      return this.request('PUT', \`/v1/users/\${userId}\`, data, true);
+    },
+    updateSettings: async (userId: string, settings: any) => {
+      return this.request('PUT', \`/v1/users/\${userId}/settings\`, settings, true);
+    },
+    deactivate: async (userId: string) => {
+      return this.request('POST', \`/v1/users/\${userId}/deactivate\`, undefined, true);
+    },
+    activate: async (userId: string) => {
+      return this.request('POST', \`/v1/users/\${userId}/activate\`, undefined, true);
+    },
+    delete: async (userId: string) => {
+      return this.request('DELETE', \`/v1/users/\${userId}\`, undefined, true);
+    },
+  };
+  // Usage endpoints
+  usage = {
+    getCurrent: async (organizationId: string) => {
+      return this.request('GET', \`/v1/api/usage/current?organization_id=\${organizationId}\`, undefined, true);
+    },
+    getHistory: async (organizationId: string, limit = 20, offset = 0) => {
+      return this.request(
+        'GET',
+        \`/v1/api/usage/history?organization_id=\${organizationId}&limit=\${limit}&offset=\${offset}\`,
+        undefined,
+        true
+      );
+    },
+    getEntityUsage: async (organizationId: string) => {
+      return this.request('GET', \`/v1/api/usage/entity-usage?organization_id=\${organizationId}\`, undefined, true);
+    },
+    getStats: async (organizationId: string) => {
+      return this.request('GET', \`/v1/usage/stats?organization_id=\${organizationId}\`, undefined, true);
+    },
+    check: async (data: { tokens: number; usage_type?: string; user_id: string; organization_id: string }) => {
+      return this.request('POST', '/v1/usage/check', data, true);
+    },
+    consume: async (data: { tokens: number; usage_type?: string; user_id: string; organization_id: string }) => {
+      return this.request('POST', '/v1/usage/consume', data, true);
+    },
+  };
+  // Entity Schema endpoints
+  entitySchemas = {
+    list: async (page = 1, size = 20) => {
+      return this.request('GET', \`/v1/entity/schemas?page=\${page}&size=\${size}\`, undefined, true);
+    },
+    create: async (data: { name: string; slug: string; description?: string; fields_definition: any }) => {
+      return this.request('POST', '/v1/entity/schemas', data, true);
+    },
+    get: async (schemaId: string) => {
+      return this.request('GET', \`/v1/entity/schemas/\${schemaId}\`, undefined, true);
+    },
+    update: async (schemaId: string, data: { name?: string; description?: string; fields_definition?: any; is_active?: boolean }) => {
+      return this.request('PUT', \`/v1/entity/schemas/\${schemaId}\`, data, true);
+    },
+    delete: async (schemaId: string) => {
+      return this.request('DELETE', \`/v1/entity/schemas/\${schemaId}\`, undefined, true);
+    },
+  };
+  // Entity Record endpoints
+  entityRecords = {
+    create: async (schemaId: string, data: any) => {
+      return this.request('POST', '/v1/entity/records', { schema_id: schemaId, data }, true);
+    },
+    get: async (recordId: string) => {
+      return this.request('GET', \`/v1/entity/records/\${recordId}\`, undefined, true);
+    },
+    update: async (recordId: string, data: any) => {
+      return this.request('PUT', \`/v1/entity/records/\${recordId}\`, { data }, true);
+    },
+    delete: async (recordId: string) => {
+      return this.request('DELETE', \`/v1/entity/records/\${recordId}\`, undefined, true);
+    },
+    search: async (searchReq: { schema_id?: string; query?: any; page?: number; size?: number; order_by?: string; order_dir?: string }) => {
+      const params = new URLSearchParams();
+      if (searchReq.page) params.set('page', String(searchReq.page));
+      if (searchReq.size) params.set('size', String(searchReq.size));
+      if (searchReq.order_by) params.set('order_by', searchReq.order_by);
+      if (searchReq.order_dir) params.set('order_dir', searchReq.order_dir);
+      return this.request('POST', \`/v1/entity/records/search?\${params}\`, { schema_id: searchReq.schema_id, query: searchReq.query }, true);
+    },
+  };
+  // Department endpoints
+  departments = {
+    get: async (departmentId: string, userId: string) => {
+      return this.request('GET', \`/v1/departments/\${departmentId}?user_id=\${userId}\`, undefined, true);
+    },
+  };
+}
+export { ApiClient, TokenResponse, Organization, ApiError };
 `;
 // =============================================================================
 // Request Headers Helper
 // =============================================================================
-const REQUEST_HEADERS = `
-## Required Headers for ALL Requests
-\`\`\`
-X-API-Key: pk_live_xxxxx
-Content-Type: application/json
-\`\`\`
-## For Authenticated Requests (after login)
-\`\`\`
-X-API-Key: pk_live_xxxxx
-Content-Type: application/json
-Authorization: Bearer <access_token>
-\`\`\`
-## Header Details
-| Header | Required | Description |
-|--------|----------|-------------|
-| X-API-Key | Always | Your API key (pk_live_* for frontend) |
-| Content-Type | For POST/PUT/PATCH | Always use application/json |
-| Authorization | After login | Bearer token from login response |
-| X-Organization-Id | For org-scoped endpoints | Organization UUID (entities, usage) |
+const REQUEST_HEADERS = `
+## Required Headers for ALL Requests
+\`\`\`
+X-API-Key: pk_live_xxxxx
+Content-Type: application/json
+\`\`\`
+## For Authenticated Requests (after login)
+\`\`\`
+X-API-Key: pk_live_xxxxx
+Content-Type: application/json
+Authorization: Bearer <access_token>
+\`\`\`
+## Header Details
+| Header | Required | Description |
+|--------|----------|-------------|
+| X-API-Key | Always | Your API key (pk_live_* for frontend) |
+| Content-Type | For POST/PUT/PATCH | Always use application/json |
+| Authorization | After login | Bearer token from login response |
+| X-Organization-Id | For org-scoped endpoints | Organization UUID (entities, usage) |
 `;
 // =============================================================================
 // API Client
@@ -2395,12 +2470,390 @@ async function fetchFromApi(endpoint) {
         throw error;
     }
 }
+function detectKeyType(key) {
+    if (!key)
+        return { type: null, prefix: "" };
+    // Mask everything past the prefix so logs don't leak.
+    const prefix = key.slice(0, 12) + "…";
+    if (key.startsWith("pk_"))
+        return { type: "public", prefix };
+    if (key.startsWith("sk_"))
+        return { type: "secret", prefix };
+    return { type: null, prefix };
+}
+function SECURITY_GUIDE(detected) {
+    if (detected === null) {
+        return `# API key security guide
+No \`SAAS_API_KEY\` is configured in the MCP env, so this guide is generic.
+Configure a key first (\`validate_credentials\` will tell you which one
+you have) and rerun this tool to get the targeted guide.
+## Two key types — pick the right one BEFORE writing code
+### Public key (\`pk_live_*\`)
+- **Surface:** safe to ship in browser / mobile bundles, **only when
+  paired with allowed-origins restrictions configured at key creation**.
+- **Allowed endpoints:** auth-only (\`/v1/auth/register\`, \`login\`,
+  \`refresh\`, \`logout\`, \`me\`, \`forgot-password\`, \`reset-password\`).
+- **Forbidden:** any admin / data-listing endpoint. The backend rejects
+  these calls at the middleware level — no surprises.
+### Secret key (\`sk_live_*\`)
+- **Surface:** server-side ONLY. Never put in a browser bundle, mobile
+  app, public repo, or any environment a user can inspect.
+- **Allowed endpoints:** every end-user endpoint, including admin
+  listings (\`/v1/auth/users\`, \`/v1/dashboard/*\` patterns through
+  appropriate flows).
+- **Forbidden:** including the literal string in client-side code.
+## Common leak vectors to watch out for
+- Hardcoding into Git history (rotate the key if it slipped — \`git\`
+  history is forever).
+- \`NEXT_PUBLIC_*\` / \`VITE_*\` / \`PUBLIC_*\` env vars: these get baked
+  into the client bundle. Only public keys belong here.
+- CI logs that echo env vars.
+- Browser DevTools "Network" tab: every request leaks its headers to
+  whoever has the device. With public keys + allowed-origins this is
+  fine; with secret keys it is a breach.`;
+    }
+    if (detected === "public") {
+        return `# Security guide for your **public** key (\`pk_live_*\`)
+Your configured key is a public key. The platform allows it in browser
+bundles and mobile apps **only if** you set its \`allowed_origins\` at
+creation. Verify that with the dashboard or with \`get_endpoint_details\`
+for \`POST /v1/dashboard/api-keys\`.
+## ✅ Where it's safe to put this key
+- A React/Vue/Svelte SPA bundle, served from one of the allowed origins.
+- A Next.js / Remix / SvelteKit app, in either client or server code.
+- A mobile app (React Native / Flutter / Swift / Kotlin).
+- An \`.env\` file committed to a private repo, prefixed
+  \`NEXT_PUBLIC_*\` / \`VITE_*\` / \`PUBLIC_*\` so the bundler exposes it.
+## ❌ Endpoints this key CAN'T call
+The backend will reject calls to admin / management endpoints with this
+key. Trying to do \`/v1/auth/users\` (the user list) or any \`/v1/dashboard/*\`
+endpoint with a public key returns 401/403. Use a secret key on a server
+for those.
+## Allowed endpoints (full list)
+- \`POST /v1/auth/register\`
+- \`POST /v1/auth/login\`
+- \`POST /v1/auth/refresh\`
+- \`POST /v1/auth/logout\`
+- \`GET  /v1/auth/me\`
+- \`POST /v1/auth/forgot-password\`
+- \`POST /v1/auth/reset-password\`
+- \`POST /v1/auth/verify-email\`
+- \`POST /v1/auth/resend-verification\`
+- \`GET  /v1/auth/providers\`
+- \`GET  /v1/auth/google/url\` (and equivalents per provider)
+## Allowed-origins rule of thumb
+- Always include every domain you serve the app from, including
+  \`http://localhost:3000\` for dev. Origins that aren't on the list
+  produce a 403 even if the key is correct.
+- Wildcards are not allowed. Listing the exact origins is the point.
+## Things that are still secret even with a public key
+- The end-user's **JWT** issued after \`/v1/auth/login\`. Treat it like a
+  session token: keep it in memory or HTTP-only cookies, never in
+  localStorage if XSS is a real threat for your app.
+## Recommended next step
+Run \`recommend_stack\` with the kind of app you want to build to get a
+matching framework + architecture. For a public key the answer is
+usually \`react / vue / svelte\` for SPA, or \`next / remix / sveltekit\`
+for an app that also needs SSR.`;
+    }
+    // secret
+    return `# Security guide for your **secret** key (\`sk_live_*\`)
+Your configured key has full end-user API access on behalf of the
+tenant. **It must never reach a browser, a mobile bundle, a public
+repo, or anywhere a user can inspect.**
+## ✅ Where it's safe to put this key
+- A server you run: Node.js / Python / Go / Rust / Ruby — anywhere the
+  source isn't shipped to clients.
+- A Next.js / Remix / SvelteKit app, **only inside server-only files**
+  (\`app/api/**\`, server components, route handlers, server actions,
+  \`+page.server.ts\`, route loaders). Pair with environment variables
+  read **without** a \`NEXT_PUBLIC_\` / \`VITE_\` / \`PUBLIC_\` prefix so
+  the bundler does not embed it.
+- Edge functions (Vercel Edge / Cloudflare Workers) where the secret
+  lives in the platform's secret store, not in code.
+- CI/CD secrets stores: GitHub Actions encrypted secrets, Doppler,
+  AWS Secrets Manager, etc.
+## ❌ Where it MUST NOT go
+- React/Vue/Svelte client components that the bundler ships to the browser.
+- \`NEXT_PUBLIC_*\`, \`VITE_*\`, \`PUBLIC_*\` env vars (they end up in the
+  bundle).
+- Mobile apps — the binary can be reverse-engineered, the key extracted.
+- Git history, including \`.env\` accidentally committed before
+  \`.gitignore\` was set up.
+- Browser DevTools / sw caches (don't forward it through service workers).
+- Logs that aren't access-controlled.
+## What this key can do
+- Every end-user-facing endpoint, including listings that public keys
+  can't touch (\`GET /v1/auth/users\`, \`GET /v1/auth/providers\`,
+  user-by-id lookups, billing operations on behalf of end-users, etc.).
+- Acts on behalf of the tenant — every call is attributed to the
+  organization the key is scoped to.
+## Architecture pattern that keeps it safe
+Don't expose this key to the client. Put a thin server in front and
+proxy the requests:
+\`\`\`
+[Browser app] → POST /api/login → [Your server] → POST /v1/auth/login → [Genlobe]
+                  (no key)            (X-API-Key: sk_live_…)
+\`\`\`
+Your server holds the key in env. The browser never sees it. The
+end-user JWT that comes back from \`/v1/auth/login\` is what your
+browser app holds for that session.
+## Common leak vectors (each one is a real incident pattern)
+- "Just for testing" hardcoded into a React component → committed →
+  pushed → key on GitHub forever (rotate immediately).
+- A \`fetch\` call inside \`useEffect\` that sends the secret in the
+  Authorization header — it shows in the user's Network tab. Move that
+  call to your server.
+- An LLM coding agent pasting the key into a comment to "remember" it.
+  Refuse — the key belongs in env.
+- Logging \`console.log(headers)\` in middleware on a public-facing app.
+## Recommended next step
+Run \`recommend_stack\` with your app_type to get a server-aware framework
+recommendation. For a secret key that almost always means **Next.js /
+Remix / SvelteKit / Nuxt**, all of which give you a clear server boundary
+where this key can live.`;
+}
+function STACK_RECOMMENDATION(appType, detected) {
+    const keyLine = detected === "secret"
+        ? "🔴 You have a **secret key** (\`sk_live_*\`). It must stay server-side."
+        : detected === "public"
+            ? "🟢 You have a **public key** (\`pk_live_*\`). It can ship to clients with allowed-origins set."
+            : "⚪ No key configured yet. Pick one first (`validate_credentials`).";
+    const sections = {
+        fullstack: detected === "secret" ? `## Recommendation: **Next.js (App Router)**
+A fullstack project with a secret key needs a clear server boundary.
+Next.js App Router is the simplest framework that gives you:
+- **Server Components** + **Server Actions** + **Route Handlers** where
+  the key lives in \`process.env.SAAS_API_KEY\` and never reaches the
+  client.
+- File-based routing for the user-facing pages.
+- Built-in support for env-based config without leaking it to the bundle.
+### Project layout
+\`\`\`
+app/
+├─ layout.tsx
+├─ page.tsx                         (RSC, talks to SaaS via server action)
+├─ (auth)/
+│  ├─ login/page.tsx                (client form → posts to server action)
+│  └─ register/page.tsx
+├─ api/
+│  ├─ auth/login/route.ts           (Route handler, sk_live_* used here)
+│  ├─ auth/register/route.ts
+│  └─ proxy/[...path]/route.ts      (catch-all server proxy if you need it)
+└─ lib/saas-client.ts               ('server-only', wraps fetch + sk_live)
+\`\`\`
+### Three rules that keep the key safe
+1. \`SAAS_API_KEY\` env var is **never** prefixed with \`NEXT_PUBLIC_\`.
+2. The wrapper file imports \`'server-only'\` at the top. If a client
+   component ever imports it, the build fails — that's the contract.
+3. The browser only ever talks to *your* \`/api/*\` routes, never to
+   \`api.your-saas.com\` directly.
+### Equivalents in other frameworks
+- **Remix** — \`loader\` and \`action\` functions are server-only by
+  design; same shape works.
+- **SvelteKit** — \`+page.server.ts\` / \`+server.ts\` files.
+- **Nuxt** — \`server/api/*.ts\` route files, \`useNitroApp\`.
+- **Astro** — server-rendered routes (\`output: 'server'\`).
+Pick the one your team is most comfortable with. Next.js is the most
+documented for this exact pattern.` : `## Recommendation: lighter SPA + your own backend
+A fullstack project with a public key is unusual — public keys are
+restricted to auth endpoints. If you want to read or write data beyond
+register/login/me, you'll need a secret key on the server.
+For now you have two paths:
+**A. Keep it client-only.** Use Vite + React/Vue/Svelte. Allowed origins
+on the public key restrict who can call. Limited to auth, but works for
+the "user signs up, signs in" surface.
+**B. Add a thin server.** Generate a secret key from the dashboard,
+stash it in a Next.js/Remix server, run \`recommend_stack\` again with
+the secret key configured. That moves you to the server-side pattern
+with full API access.`,
+        frontend_only: detected === "public" ? `## Recommendation: **Vite + React** (or Vue / Svelte / SolidJS)
+A frontend-only app with a public key is the textbook case. Use any
+SPA-style framework that lets you embed the key in the bundle.
+\`\`\`
+src/
+├─ App.tsx
+├─ pages/
+│  ├─ Login.tsx
+│  ├─ Register.tsx
+│  └─ Dashboard.tsx
+├─ lib/
+│  └─ api.ts            (fetch wrapper that adds X-API-Key)
+└─ main.tsx
+.env
+└─ VITE_API_KEY=pk_live_…
+└─ VITE_API_URL=https://api.your-saas.com
+\`\`\`
+### Three rules
+1. The key only goes into \`import.meta.env.VITE_API_KEY\` (Vite) or
+   \`process.env.NEXT_PUBLIC_API_KEY\` (Next.js client). Never paste the
+   raw string in a component.
+2. The deployed origin must be on the key's allowed-origins list, or
+   every request returns 403.
+3. The end-user JWT (the result of \`/v1/auth/login\`) is what your app
+   holds in memory or HTTP-only cookies — *not* the public key. JWTs
+   are scoped to the user; the public key is shared by everyone.
+If you ever need to call admin-style endpoints (list users, etc.), you
+need to upgrade to a secret key on a server (option B above).` : `## Recommendation: don't ship the secret key to the client
+Your key is secret. A frontend-only architecture cannot use it without
+leaking it. Two paths:
+**A. Generate a public key from the dashboard** for the frontend, keep
+the secret key for any server you might need later. This is the
+canonical setup. Re-run \`recommend_stack\` with \`app_type=frontend_only\`
+once you swap.
+**B. Add a small server** (Vercel Functions, Cloudflare Workers, a Node
+service) and proxy. Then call it "fullstack" and use the Next.js
+recommendation above.`,
+        backend_only: detected === "secret" ? `## Recommendation: any server runtime, secret in env
+A backend-only consumer (a worker, a webhook handler, a cron) is the
+simplest case. Any language works:
+- **Node** (\`fastify\`, \`express\`, \`hono\`)
+- **Python** (\`fastapi\`, \`flask\`)
+- **Go** (\`net/http\`, \`echo\`)
+- **Rust** (\`axum\`, \`actix-web\`)
+\`\`\`bash
+# .env (loaded via dotenv-cli, doppler, or your platform's secret store)
+SAAS_API_URL=https://api.your-saas.com
+SAAS_API_KEY=sk_live_…
+\`\`\`
+\`\`\`ts
+// minimal Node example
+const r = await fetch(\`\${process.env.SAAS_API_URL}/v1/auth/login\`, {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-API-Key': process.env.SAAS_API_KEY!,
+  },
+  body: JSON.stringify({ email, password }),
+});
+\`\`\`
+The secret never leaves the host process; rotate via the dashboard if
+the host or env is ever compromised.` : `A backend with a public key works only for auth endpoints. If your
+backend needs admin operations (list users, billing on behalf of a
+tenant), generate a secret key from the dashboard and re-run this tool.`,
+        mobile: detected === "public" ? `## Recommendation: native or React Native + public key in app config
+Mobile apps with a public key behave like SPAs. Bundle the key, set
+allowed-origins to whatever your auth callback host is.
+- **React Native / Expo** — \`react-native-config\` reads
+  \`SAAS_API_KEY\` from \`.env\` and exposes it to JS.
+- **Flutter** — \`flutter_dotenv\` or \`--dart-define\` flags.
+- **Swift / Kotlin** — \`xcconfig\` / \`local.properties\` + \`BuildConfig\`.
+Even though the key is in the binary, public keys are *designed* for
+this. The risk is identical to a website's public key.` : `## Recommendation: don't ship a secret key in a mobile binary
+Mobile apps cannot keep a secret. Reverse-engineering the binary is
+trivial. Two paths:
+**A. Switch to a public key** for the mobile client and keep the
+secret key on a server you control. Your server proxies the calls
+that need elevated permissions.
+**B. Architecture A is non-negotiable for production.** The only way
+to use a secret key safely from a mobile app is *not to use it from
+the mobile app*.`,
+        cli: detected === "secret" ? `## Recommendation: any language, secret in user's local env
+A CLI is essentially a backend running on the user's machine. Standard
+pattern:
+- Read \`SAAS_API_KEY\` from \`process.env\` (Node), \`os.environ\`
+  (Python), etc.
+- Print a clear error if missing: \`"Set SAAS_API_KEY (get one from
+  https://app.your-saas.com/api-keys)"\`.
+- For multi-tenant CLIs, store the key in OS keychain (\`keytar\` on
+  Node, \`keyring\` on Python) instead of plain \`.env\`.
+Frameworks: \`commander\` / \`oclif\` (Node), \`typer\` / \`click\`
+(Python), \`cobra\` (Go).` : `A CLI with a public key works only for auth flows. For most useful CLI
+behaviors (managing data, running admin commands) you want a secret key.`,
+        unsure: `## Pick the audience first, the stack second
+Tell me one of:
+- **fullstack** — one app that needs both UI and server logic
+- **frontend_only** — only the browser, no server you own
+- **backend_only** — server, worker, cron, webhook
+- **mobile** — iOS / Android app
+- **cli** — a command-line tool
+…then call \`recommend_stack\` again with \`app_type=<picked>\`. Each path
+has a different shape because of where the API key can safely live.`,
+    };
+    const body = sections[appType] ?? sections["unsure"];
+    return `# Stack recommendation\n\n${keyLine}\n\n${body}\n\n---\n\nRun \`get_security_guide\` for the full security cheat-sheet that matches your key type.`;
+}
 // =============================================================================
 // MCP Server Implementation
 // =============================================================================
 const server = new Server({
     name: "saas-multi-agent-api",
-    version: "2.2.0",
+    version: SERVER_VERSION,
 }, {
     capabilities: {
         tools: {},
@@ -2412,20 +2865,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         tools: [
             {
                 name: "get_api_overview",
-                description: `Get a high-level overview of the Multi-tenant SaaS API.
-IMPORTANT: This API has TWO types of endpoints:
-1. TENANT/DASHBOARD endpoints - For tenant admins (NOT for end-user frontends)
-2. END-USER endpoints - For building frontend applications
-KEY FEATURES:
-- User authentication (login, register, password reset)
-- Organizations and team management
-- Subscriptions and billing (Stripe)
-- AI Agents: Chat with AI agents created by the tenant
-- External Agents: Track usage from external agent integrations (e.g., N8N)
-- Usage tracking
+                description: `Get a high-level overview of the Multi-tenant SaaS API.
+IMPORTANT: This API has TWO types of endpoints:
+1. TENANT/DASHBOARD endpoints - For tenant admins (NOT for end-user frontends)
+2. END-USER endpoints - For building frontend applications
+KEY FEATURES:
+- User authentication (login, register, password reset)
+- Organizations and team management
+- Subscriptions and billing (Stripe)
+- AI Agents: Chat with AI agents created by the tenant
+- External Agents: Track usage from external agent integrations (e.g., N8N)
+- Usage tracking
 Call this first to understand the API architecture and authentication model.`,
                 inputSchema: {
                     type: "object",
@@ -2435,12 +2888,12 @@ Call this first to understand the API architecture and authentication model.`,
             },
             {
                 name: "get_end_user_endpoints",
-                description: `Get detailed documentation for END-USER API endpoints.
-Use this when building a frontend for end-users. These endpoints use:
-- API Key (X-API-Key header) - required for ALL requests
-- JWT token (Authorization: Bearer) - required AFTER login
+                description: `Get detailed documentation for END-USER API endpoints.
+Use this when building a frontend for end-users. These endpoints use:
+- API Key (X-API-Key header) - required for ALL requests
+- JWT token (Authorization: Bearer) - required AFTER login
 Categories: authentication, organizations, subscriptions, billing, usage, agents, users, plans, ai, entities, departments, external_agents`,
                 inputSchema: {
                     type: "object",
@@ -2465,15 +2918,15 @@ Categories: authentication, organizations, subscriptions, billing, usage, agents
             },
             {
                 name: "get_sdk_template",
-                description: `Get a complete TypeScript/JavaScript SDK template for the API.
-This template includes:
-- Typed interfaces for all responses
-- Auth methods (login, register, refresh, logout)
-- Organization methods
-- Subscription methods
-- Usage methods
+                description: `Get a complete TypeScript/JavaScript SDK template for the API.
+This template includes:
+- Typed interfaces for all responses
+- Auth methods (login, register, refresh, logout)
+- Organization methods
+- Subscription methods
+- Usage methods
 You can use this as a starting point for your frontend.`,
                 inputSchema: {
                     type: "object",
@@ -2525,15 +2978,15 @@ You can use this as a starting point for your frontend.`,
             },
             {
                 name: "get_authentication_flow",
-                description: `Get a step-by-step guide for implementing authentication in your frontend.
-Covers:
-- Registration flow (with conditional email verification)
-- Login flow
-- Token refresh
-- Password reset
-- Email verification flow
-- Google OAuth flow
+                description: `Get a step-by-step guide for implementing authentication in your frontend.
+Covers:
+- Registration flow (with conditional email verification)
+- Login flow
+- Token refresh
+- Password reset
+- Email verification flow
+- Google OAuth flow
 - Logout`,
                 inputSchema: {
                     type: "object",
@@ -2543,14 +2996,14 @@ Covers:
             },
             {
                 name: "get_common_patterns",
-                description: `Get common implementation patterns for frontend development.
-Includes:
-- Token storage best practices
-- Auto token refresh
-- Error handling
-- API request wrapper
-- OAuth callback handling
+                description: `Get common implementation patterns for frontend development.
+Includes:
+- Token storage best practices
+- Auto token refresh
+- Error handling
+- API request wrapper
+- OAuth callback handling
 - Environment variables`,
                 inputSchema: {
                     type: "object",
@@ -2558,6 +3011,66 @@ Includes:
                     required: [],
                 },
             },
+            {
+                name: "validate_credentials",
+                description: `Verify the SAAS_API_KEY currently configured by hitting the live API.
+Returns the detected key type (public pk_live_* or secret sk_live_*),
+whether the key authenticates correctly, the API URL it points at, and
+the kind of operations the key is allowed to perform. Run this first
+when starting a new project so the agent knows what's safe to build.`,
+                inputSchema: { type: "object", properties: {}, required: [] },
+            },
+            {
+                name: "list_end_users",
+                description: `List the tenant's end-users via GET /v1/auth/users. Requires a
+secret API key (sk_live_*). Useful when scaffolding admin views or
+debugging a signup flow. Returns an array of {id, email, display_name,
+is_active, created_at}.`,
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        skip: { type: "number", description: "Pagination offset (default 0)" },
+                        limit: { type: "number", description: "Page size (default 20, max 100)" },
+                    },
+                    required: [],
+                },
+            },
+            {
+                name: "list_oauth_providers",
+                description: `List the OAuth providers (Google, GitHub, etc.) the tenant has
+configured for end-user social login. Useful when wiring up a "Sign in
+with Google" button — if the provider isn't in the list, the button
+won't work. Calls GET /v1/auth/providers.`,
+                inputSchema: { type: "object", properties: {}, required: [] },
+            },
+            {
+                name: "get_security_guide",
+                description: `Get key-type-specific security best practices. Reads SAAS_API_KEY
+to detect public (pk_live_*) vs secret (sk_live_*) and returns the
+matching guide: where it's safe to put the key, common leak vectors,
+allowed-origins setup, and what NOT to do. Always consult this before
+generating production code.`,
+                inputSchema: { type: "object", properties: {}, required: [] },
+            },
+            {
+                name: "recommend_stack",
+                description: `Recommend a stack and high-level architecture given the configured
+API key type and the kind of app the developer wants to build. Picks
+between Next.js / Remix / SvelteKit (server-side) for secret keys vs
+React/Vue SPA for public keys, and explains why. Use this whenever the
+developer says "I want to build X" before writing code.`,
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        app_type: {
+                            type: "string",
+                            enum: ["fullstack", "frontend_only", "backend_only", "mobile", "cli", "unsure"],
+                            description: "What kind of app are you building?",
+                        },
+                    },
+                    required: ["app_type"],
+                },
+            },
         ],
     };
 });
@@ -2571,30 +3084,40 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     content: [
                         {
                             type: "text",
-                            text: `# Multi-tenant SaaS API Overview
-**API URL:** ${API_URL}
-**Version:** 2.1.0
-${API_OVERVIEW.description}
-## Quick Links
-- Swagger UI: ${API_URL}/docs
-- ReDoc: ${API_URL}/redoc
-- OpenAPI JSON: ${API_URL}/v1/developer/openapi.json
-## Getting Started
-1. Get your API key from the tenant dashboard
-2. Use \`pk_live_*\` key for frontend development
-3. Include \`X-API-Key\` header in ALL requests
-4. After login, include \`Authorization: Bearer <token>\` for authenticated requests
-## Important Notes
-⚠️ **When building a frontend for end-users:**
-- ONLY use endpoints from the "End-user" category
-- DO NOT use /v1/tenant-auth/* or /v1/dashboard/* endpoints
+                            text: `# Multi-tenant SaaS API Overview
+**API URL:** ${API_URL}
+**Version:** ${SERVER_VERSION}
+${API_OVERVIEW.description}
+## Quick Links
+- Swagger UI: ${API_URL}/docs
+- ReDoc: ${API_URL}/redoc
+- OpenAPI JSON: ${API_URL}/v1/developer/openapi.json
+## Recommended first calls (vibecoding flow)
+Before generating any code for the user, run these in order:
+1. **\`validate_credentials\`** — confirms the configured API key works and tells you whether it's a public (\`pk_live_*\`) or secret (\`sk_live_*\`) key. The rest of your decisions depend on the answer.
+2. **\`get_security_guide\`** — returns the safe-usage rules for the *detected* key type (where it can run, what it can call, leak vectors).
+3. **\`recommend_stack\`** — given the kind of app the user wants (frontend_only, fullstack, backend_service, etc.), returns the framework + project layout that won't leak the key.
+Skipping these is how secret keys end up shipped to a browser bundle. Don't skip them.
+## Getting Started (manual)
+1. Get your API key from the tenant dashboard
+2. Use \`pk_live_*\` key for frontend-only apps; use \`sk_live_*\` only on a server (Next.js route handler, backend, etc.)
+3. Include \`X-API-Key\` header in ALL requests
+4. After login, include \`Authorization: Bearer <token>\` for authenticated requests
+## Important Notes
+⚠️ **When building a frontend for end-users:**
+- ONLY use endpoints from the "End-user" category
+- DO NOT use /v1/tenant-auth/* or /v1/dashboard/* endpoints
 - Those are for tenant admin dashboards, not end-user apps`,
                         },
                     ],
@@ -2610,115 +3133,115 @@ ${API_OVERVIEW.description}
                     content: [
                         {
                             type: "text",
-                            text: `# End-User API Endpoints${category ? ` - ${category}` : ''}
-These endpoints are for building frontend applications for end-users.
-${JSON.stringify(endpoints, null, 2)}
-## Quick Reference
-### Authentication (No JWT required)
-- POST /v1/auth/register - Register new user
-- POST /v1/auth/login - Login user
-- POST /v1/auth/refresh - Refresh access token
-- POST /v1/auth/forgot-password - Request password reset
-- POST /v1/auth/reset-password - Reset password
-- POST /v1/auth/verify-email - Verify email (with API Key)
-- POST /v1/auth/verify-email-with-token - Verify email with token only (no API Key)
-- POST /v1/auth/resend-verification - Resend verification email
-- GET /v1/auth/providers - List enabled OAuth providers (e.g. Google)
-- GET /v1/auth/google/url?redirect_uri=... - Get Google OAuth URL
-- GET /v1/auth/google/callback - OAuth callback (redirects with tokens in URL fragment #)
-### Authenticated Endpoints (JWT required)
-- GET /v1/auth/me - Get current user
-- POST /v1/auth/logout - Logout
-- POST /v1/auth/change-password - Change password (authenticated)
-- GET /v1/organizations/my-organizations - Get user's organizations
-- POST /v1/organizations - Create organization
-- GET /v1/organizations/{id}/departments - List departments
-- GET /v1/organizations/{id}/members - List members
-- PUT /v1/organizations/{id}/members/{user_id} - Update member role
-- DELETE /v1/organizations/{id}/members/{user_id} - Remove member
-- POST /v1/organizations/{id}/invite - Invite member
-- POST /v1/organizations/accept-invitation - Accept invitation
-- POST /v1/organizations/reject-invitation - Reject invitation
-- GET /v1/organizations/invitations/pending?email= - Check pending invitations
-- GET /v1/organizations/invitations/{token} - Get invitation details
-- POST /v1/organizations/{id}/set-default - Set default org
-- GET /v1/organizations/{id}/subscription - Get org subscription
-- POST /v1/organizations/{id}/subscription/{plan_id} - Subscribe to plan
-- DELETE /v1/organizations/{id}/subscription - Cancel subscription
-- GET /v1/organizations/{id}/usage - Get org usage
-### Plans (JWT required)
-- GET /v1/plans - List all plans (paginated)
-- GET /v1/plans/active - List active plans
-- GET /v1/plans/free - List free plans
-- GET /v1/plans/{plan_id} - Get plan details
-### Subscriptions (JWT required)
-- GET /v1/subscriptions/plans - List plans
-- GET /v1/subscriptions/plans/{plan_id} - Get plan by ID
-- GET /v1/subscriptions/current - Get current subscription
-- POST /v1/subscriptions/subscriptions - Create subscription
-- GET /v1/subscriptions/subscriptions/{id} - Get subscription by ID
-- PUT /v1/subscriptions/subscriptions/{id} - Update subscription
-- DELETE /v1/subscriptions/subscriptions/{id} - Cancel subscription
-- POST /v1/subscriptions/checkout - Start checkout
-- GET /v1/subscriptions/users/{user_id}/usage - Get user plan usage
-- GET /v1/subscriptions/users/{user_id}/usage/limits - Check user limits
-- PUT /v1/subscriptions/users/{user_id}/plan/{plan_id} - Assign plan
-- POST /v1/subscriptions/organizations/{org_id}/resume - Resume org subscription (sk_live_*)
-- GET /v1/subscriptions/organizations/{org_id}/invoices - Get org invoices (sk_live_*)
-- DELETE /v1/subscriptions/organizations/{org_id}/subscription - Cancel org subscription (sk_live_*)
-### Billing (sk_live_* ONLY)
-- GET /v1/billing/available-plans - List available plans
-- POST /v1/billing/create-checkout-session - Create checkout session
-- POST /v1/billing/change-plan - Change plan (upgrade/downgrade)
-- POST /v1/billing/cancel-subscription - Cancel subscription
-- GET /v1/billing/billing-history-org/{id} - Billing history
-### Users
-- POST /v1/users - Create user (sk_live_* + JWT)
-- GET /v1/users - List users (sk_live_* only, paginated)
-- GET /v1/users/stats - User stats (sk_live_* only)
-- GET /v1/users/{id} - Get user (self or sk_live_*)
-- PUT /v1/users/{id} - Update user
-- PUT /v1/users/{id}/settings - Update settings
-- POST /v1/users/{id}/deactivate - Deactivate user (soft delete)
-- POST /v1/users/{id}/activate - Activate user (sk_live_* only)
-- DELETE /v1/users/{id} - Delete user (sk_live_* only, soft delete)
-### Usage (JWT required)
-- GET /v1/api/usage/current - Current usage stats
-- GET /v1/api/usage/history - Usage history (limit/offset pagination)
-- GET /v1/api/usage/entity-usage - Entity usage stats
-- GET /v1/usage/stats - Comprehensive usage statistics
-- POST /v1/usage/check - Check if usage allowed (without consuming)
-- POST /v1/usage/consume - Consume usage tokens/messages
-### AI Agents (JWT required)
-- GET /v1/user/agents/available - List available agents
-- GET /v1/user/agents/{agent_id} - Get agent details
-- POST /v1/user/agents/{agent_id}/chat - Chat with an agent
-- GET /v1/user/agents/{agent_id}/history - Get conversation history
-### Custom Entities (API Key + JWT + X-Organization-Id)
-- GET /v1/entity/schemas - List schemas
-- POST /v1/entity/schemas - Create schema
-- GET /v1/entity/schemas/{id} - Get schema
-- PUT /v1/entity/schemas/{id} - Update schema
-- DELETE /v1/entity/schemas/{id} - Delete schema
-- POST /v1/entity/records - Create record
-- GET /v1/entity/records/{id} - Get record
-- PUT /v1/entity/records/{id} - Update record
-- DELETE /v1/entity/records/{id} - Delete record
-- POST /v1/entity/records/search - Search records with filters
-### Departments
+                            text: `# End-User API Endpoints${category ? ` - ${category}` : ''}
+These endpoints are for building frontend applications for end-users.
+${JSON.stringify(endpoints, null, 2)}
+## Quick Reference
+### Authentication (No JWT required)
+- POST /v1/auth/register - Register new user
+- POST /v1/auth/login - Login user
+- POST /v1/auth/refresh - Refresh access token
+- POST /v1/auth/forgot-password - Request password reset
+- POST /v1/auth/reset-password - Reset password
+- POST /v1/auth/verify-email - Verify email (with API Key)
+- POST /v1/auth/verify-email-with-token - Verify email with token only (no API Key)
+- POST /v1/auth/resend-verification - Resend verification email
+- GET /v1/auth/providers - List enabled OAuth providers (e.g. Google)
+- GET /v1/auth/google/url?redirect_uri=... - Get Google OAuth URL
+- GET /v1/auth/google/callback - OAuth callback (redirects with tokens in URL fragment #)
+### Authenticated Endpoints (JWT required)
+- GET /v1/auth/me - Get current user
+- POST /v1/auth/logout - Logout
+- POST /v1/auth/change-password - Change password (authenticated)
+- GET /v1/organizations/my-organizations - Get user's organizations
+- POST /v1/organizations - Create organization
+- GET /v1/organizations/{id}/departments - List departments
+- GET /v1/organizations/{id}/members - List members
+- PUT /v1/organizations/{id}/members/{user_id} - Update member role
+- DELETE /v1/organizations/{id}/members/{user_id} - Remove member
+- POST /v1/organizations/{id}/invite - Invite member
+- POST /v1/organizations/accept-invitation - Accept invitation
+- POST /v1/organizations/reject-invitation - Reject invitation
+- GET /v1/organizations/invitations/pending?email= - Check pending invitations
+- GET /v1/organizations/invitations/{token} - Get invitation details
+- POST /v1/organizations/{id}/set-default - Set default org
+- GET /v1/organizations/{id}/subscription - Get org subscription
+- POST /v1/organizations/{id}/subscription/{plan_id} - Subscribe to plan
+- DELETE /v1/organizations/{id}/subscription - Cancel subscription
+- GET /v1/organizations/{id}/usage - Get org usage
+### Plans (JWT required)
+- GET /v1/plans - List all plans (paginated)
+- GET /v1/plans/active - List active plans
+- GET /v1/plans/free - List free plans
+- GET /v1/plans/{plan_id} - Get plan details
+### Subscriptions (JWT required)
+- GET /v1/subscriptions/plans - List plans
+- GET /v1/subscriptions/plans/{plan_id} - Get plan by ID
+- GET /v1/subscriptions/current - Get current subscription
+- POST /v1/subscriptions/subscriptions - Create subscription
+- GET /v1/subscriptions/subscriptions/{id} - Get subscription by ID
+- PUT /v1/subscriptions/subscriptions/{id} - Update subscription
+- DELETE /v1/subscriptions/subscriptions/{id} - Cancel subscription
+- POST /v1/subscriptions/checkout - Start checkout
+- GET /v1/subscriptions/users/{user_id}/usage - Get user plan usage
+- GET /v1/subscriptions/users/{user_id}/usage/limits - Check user limits
+- PUT /v1/subscriptions/users/{user_id}/plan/{plan_id} - Assign plan
+- POST /v1/subscriptions/organizations/{org_id}/resume - Resume org subscription (sk_live_*)
+- GET /v1/subscriptions/organizations/{org_id}/invoices - Get org invoices (sk_live_*)
+- DELETE /v1/subscriptions/organizations/{org_id}/subscription - Cancel org subscription (sk_live_*)
+### Billing (sk_live_* ONLY)
+- GET /v1/billing/available-plans - List available plans
+- POST /v1/billing/create-checkout-session - Create checkout session
+- POST /v1/billing/change-plan - Change plan (upgrade/downgrade)
+- POST /v1/billing/cancel-subscription - Cancel subscription
+- GET /v1/billing/billing-history-org/{id} - Billing history
+### Users
+- POST /v1/users - Create user (sk_live_* + JWT)
+- GET /v1/users - List users (sk_live_* only, paginated)
+- GET /v1/users/stats - User stats (sk_live_* only)
+- GET /v1/users/{id} - Get user (self or sk_live_*)
+- PUT /v1/users/{id} - Update user
+- PUT /v1/users/{id}/settings - Update settings
+- POST /v1/users/{id}/deactivate - Deactivate user (soft delete)
+- POST /v1/users/{id}/activate - Activate user (sk_live_* only)
+- DELETE /v1/users/{id} - Delete user (sk_live_* only, soft delete)
+### Usage (JWT required)
+- GET /v1/api/usage/current - Current usage stats
+- GET /v1/api/usage/history - Usage history (limit/offset pagination)
+- GET /v1/api/usage/entity-usage - Entity usage stats
+- GET /v1/usage/stats - Comprehensive usage statistics
+- POST /v1/usage/check - Check if usage allowed (without consuming)
+- POST /v1/usage/consume - Consume usage tokens/messages
+### AI Agents (JWT required)
+- GET /v1/user/agents/available - List available agents
+- GET /v1/user/agents/{agent_id} - Get agent details
+- POST /v1/user/agents/{agent_id}/chat - Chat with an agent
+- GET /v1/user/agents/{agent_id}/history - Get conversation history
+### Custom Entities (API Key + JWT + X-Organization-Id)
+- GET /v1/entity/schemas - List schemas
+- POST /v1/entity/schemas - Create schema
+- GET /v1/entity/schemas/{id} - Get schema
+- PUT /v1/entity/schemas/{id} - Update schema
+- DELETE /v1/entity/schemas/{id} - Delete schema
+- POST /v1/entity/records - Create record
+- GET /v1/entity/records/{id} - Get record
+- PUT /v1/entity/records/{id} - Update record
+- DELETE /v1/entity/records/{id} - Delete record
+- POST /v1/entity/records/search - Search records with filters
+### Departments
 - GET /v1/departments/{department_id} - Get department details`,
                         },
                     ],
@@ -2739,33 +3262,33 @@ ${JSON.stringify(endpoints, null, 2)}
                     content: [
                         {
                             type: "text",
-                            text: `# TypeScript/JavaScript SDK Template
-\`\`\`typescript
-${SDK_TEMPLATE_TYPESCRIPT}
-\`\`\`
-## Usage Example
-\`\`\`typescript
-import { ApiClient } from './api-client';
-const api = new ApiClient('pk_live_your_key', 'https://api.yoursaas.com');
-// Register
-const { user } = await api.auth.register('email@example.com', 'Password123', 'John');
-// Login
-const { access_token, user } = await api.auth.login('email@example.com', 'Password123');
-// Get organizations
-const { organizations } = await api.organizations.getMyOrganizations();
-// Create organization
-const org = await api.organizations.create('My Org', 'my-org');
-// Get subscription plans
-const plans = await api.subscriptions.getPlans();
+                            text: `# TypeScript/JavaScript SDK Template
+\`\`\`typescript
+${SDK_TEMPLATE_TYPESCRIPT}
+\`\`\`
+## Usage Example
+\`\`\`typescript
+import { ApiClient } from './api-client';
+const api = new ApiClient('pk_live_your_key', 'https://api.yoursaas.com');
+// Register
+const { user } = await api.auth.register('email@example.com', 'Password123', 'John');
+// Login
+const { access_token, user } = await api.auth.login('email@example.com', 'Password123');
+// Get organizations
+const { organizations } = await api.organizations.getMyOrganizations();
+// Create organization
+const org = await api.organizations.create('My Org', 'my-org');
+// Get subscription plans
+const plans = await api.subscriptions.getPlans();
 \`\`\``,
                         },
                     ],
@@ -2788,10 +3311,10 @@ const plans = await api.subscriptions.getPlans();
                         content: [
                             {
                                 type: "text",
-                                text: `Error fetching OpenAPI spec: ${error}
-The API might not be accessible. Try accessing ${API_URL}/docs directly.
+                                text: `Error fetching OpenAPI spec: ${error}
+The API might not be accessible. Try accessing ${API_URL}/docs directly.
 In the meantime, use the get_end_user_endpoints tool for endpoint documentation.`,
                             },
                         ],
@@ -2821,12 +3344,12 @@ In the meantime, use the get_end_user_endpoints tool for endpoint documentation.
                         content: [
                             {
                                 type: "text",
-                                text: `No endpoints found matching "${query}".
-Try searching for:
-- auth, login, register, password
-- organization, member, invite
-- subscription, plan, checkout
+                                text: `No endpoints found matching "${query}".
+Try searching for:
+- auth, login, register, password
+- organization, member, invite
+- subscription, plan, checkout
 - billing, usage`,
                             },
                         ],
@@ -2836,12 +3359,12 @@ Try searching for:
                     content: [
                         {
                             type: "text",
-                            text: `# Endpoints matching "${query}"
-${results.map(r => `## ${r.method} ${r.path}
-**Category:** ${r.category}
-**Summary:** ${r.summary}
-**Auth:** API Key: ${r.auth.api_key}, JWT: ${r.auth.jwt ? 'Required' : 'Not required'}
+                            text: `# Endpoints matching "${query}"
+${results.map(r => `## ${r.method} ${r.path}
+**Category:** ${r.category}
+**Summary:** ${r.summary}
+**Auth:** API Key: ${r.auth.api_key}, JWT: ${r.auth.jwt ? 'Required' : 'Not required'}
 `).join('\n')}`,
                         },
                     ],
@@ -2849,55 +3372,67 @@ ${results.map(r => `## ${r.method} ${r.path}
             }
             case "get_endpoint_details": {
                 const path = args.path;
-                const method = (args.method || "GET").toUpperCase();
-                // Search in embedded endpoints
+                const methodArg = args.method;
+                const method = methodArg ? methodArg.toUpperCase() : null;
+                const matches = [];
                 for (const [category, data] of Object.entries(END_USER_ENDPOINTS)) {
                     for (const endpoint of data.endpoints || []) {
-                        if (endpoint.path === path && endpoint.method === method) {
-                            return {
-                                content: [
-                                    {
-                                        type: "text",
-                                        text: `# ${method} ${path}
-**Category:** ${category}
-**Summary:** ${endpoint.summary}
-## Authentication
-- API Key: ${endpoint.auth.api_key}
-- JWT Token: ${endpoint.auth.jwt ? 'Required' : 'Not required'}
-${endpoint.request_body ? `## Request Body
-\`\`\`json
-${JSON.stringify(endpoint.request_body, null, 2)}
-\`\`\`` : ''}
-${endpoint.example_request ? `## Example Request
-\`\`\`json
-${endpoint.example_request}
-\`\`\`` : ''}
-${endpoint.response ? `## Response
-\`\`\`json
-${JSON.stringify(endpoint.response, null, 2)}
-\`\`\`` : ''}
-${endpoint.note ? `## Note
-${endpoint.note}` : ''}`,
-                                    },
-                                ],
-                            };
+                        if (endpoint.path === path && (method === null || endpoint.method === method)) {
+                            matches.push({ category, endpoint });
                         }
                     }
                 }
+                const renderEndpoint = (m) => {
+                    const ep = m.endpoint;
+                    return `# ${ep.method} ${ep.path}
+**Category:** ${m.category}
+**Summary:** ${ep.summary}
+## Authentication
+- API Key: ${ep.auth.api_key}
+- JWT Token: ${ep.auth.jwt ? 'Required' : 'Not required'}
+${ep.request_body ? `## Request Body
+\`\`\`json
+${JSON.stringify(ep.request_body, null, 2)}
+\`\`\`` : ''}
+${ep.example_request ? `## Example Request
+\`\`\`json
+${ep.example_request}
+\`\`\`` : ''}
+${ep.response ? `## Response
+\`\`\`json
+${JSON.stringify(ep.response, null, 2)}
+\`\`\`` : ''}
+${ep.note ? `## Note
+${ep.note}` : ''}`;
+                };
+                if (matches.length === 1) {
+                    return { content: [{ type: "text", text: renderEndpoint(matches[0]) }] };
+                }
+                if (matches.length > 1) {
+                    // When several methods share the path, render them all.
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: matches.map(renderEndpoint).join("\n\n---\n\n"),
+                            },
+                        ],
+                    };
+                }
                 return {
                     content: [
                         {
                             type: "text",
-                            text: `Endpoint "${method} ${path}" not found in end-user endpoints.
-Make sure you're using the correct path format (e.g., /v1/auth/login).
+                            text: `Endpoint "${method ? method + " " : ""}${path}" not found in end-user endpoints.
+Make sure you're using the correct path format (e.g., /v1/auth/login).
 Use search_endpoints tool to find available endpoints.`,
                         },
                     ],
@@ -2908,232 +3443,232 @@ Use search_endpoints tool to find available endpoints.`,
                     content: [
                         {
                             type: "text",
-                            text: `# Authentication Flow Guide
-## 1. Registration Flow
-\`\`\`typescript
-// 1. Register user
-const response = await fetch('/v1/auth/register', {
-  method: 'POST',
-  headers: {
-    'X-API-Key': 'pk_live_your_key',
-    'Content-Type': 'application/json',
-  },
-  body: JSON.stringify({
-    email: 'user@example.com',
-    password: 'SecurePass123', // min 8 chars, 1 upper, 1 lower, 1 digit
-    display_name: 'John Doe',  // optional
-  }),
-});
-const { access_token, refresh_token, user } = await response.json();
-// 2. Store tokens securely
-localStorage.setItem('access_token', access_token);
-localStorage.setItem('refresh_token', refresh_token);
-// User is now logged in
-\`\`\`
-## 2. Login Flow
-\`\`\`typescript
-const response = await fetch('/v1/auth/login', {
-  method: 'POST',
-  headers: {
-    'X-API-Key': 'pk_live_your_key',
-    'Content-Type': 'application/json',
-  },
-  body: JSON.stringify({
-    email: 'user@example.com',
-    password: 'SecurePass123',
-  }),
-});
-if (!response.ok) {
-  const error = await response.json();
-  // Handle error: error.detail contains the message
-  throw new Error(error.detail);
-}
-const { access_token, refresh_token, user } = await response.json();
-\`\`\`
-## 3. Token Refresh Flow
-\`\`\`typescript
-// Call this when access_token expires (expires_in seconds from login)
-const response = await fetch('/v1/auth/refresh', {
-  method: 'POST',
-  headers: {
-    'X-API-Key': 'pk_live_your_key',
-    'Content-Type': 'application/json',
-  },
-  body: JSON.stringify({
-    refresh_token: localStorage.getItem('refresh_token'),
-  }),
-});
-const { access_token } = await response.json();
-localStorage.setItem('access_token', access_token);
-\`\`\`
-## 4. Password Reset Flow
-\`\`\`typescript
-// Step 1: Request reset email
-await fetch('/v1/auth/forgot-password', {
-  method: 'POST',
-  headers: {
-    'X-API-Key': 'pk_live_your_key',
-    'Content-Type': 'application/json',
-  },
-  body: JSON.stringify({ email: 'user@example.com' }),
-});
-// Always succeeds (security)
-// Step 2: User clicks link in email with token
-// Step 3: Reset password with token
-await fetch('/v1/auth/reset-password', {
-  method: 'POST',
-  headers: {
-    'X-API-Key': 'pk_live_your_key',
-    'Content-Type': 'application/json',
-  },
-  body: JSON.stringify({
-    token: 'token-from-email-link',
-    new_password: 'NewSecurePass123',
-  }),
-});
-\`\`\`
-## 5. Change Password Flow (Authenticated)
-\`\`\`typescript
-await fetch('/v1/auth/change-password', {
-  method: 'POST',
-  headers: {
-    'X-API-Key': 'pk_live_your_key',
-    'Authorization': 'Bearer your_jwt_token',
-    'Content-Type': 'application/json',
-  },
-  body: JSON.stringify({
-    current_password: 'OldPass123!',
-    new_password: 'NewPass456!',
-  }),
-});
-\`\`\`
-## 6. Email Verification Flow
-\`\`\`typescript
-// Registration may require email verification depending on tenant config.
-// Check the register response for verification_required: true
-const registerResult = await response.json();
-if (registerResult.verification_required) {
-  // 1. Show "Check your email" message — NO tokens returned
-  // 2. User clicks link in email → opens /verify-email?token=xxx
-  // 3. Verify the email token
-  const verifyResponse = await fetch('/v1/auth/verify-email', {
-    method: 'POST',
-    headers: {
-      'X-API-Key': 'pk_live_your_key',
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify({ token: tokenFromUrl }),
-  });
-  // Returns: { message: "Email verified successfully" }
-  // 4. If token expired, user can request a new one
-  await fetch('/v1/auth/resend-verification', {
-    method: 'POST',
-    headers: {
-      'X-API-Key': 'pk_live_your_key',
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify({ email: 'user@example.com' }),
-  });
-  // Rate limited: 3/hour
-  // 5. After verification, user can login normally via /v1/auth/login
-} else {
-  // No verification required — tokens returned directly from register
-  localStorage.setItem('access_token', registerResult.access_token);
-  localStorage.setItem('refresh_token', registerResult.refresh_token);
-}
-\`\`\`
-## 7. Google OAuth Flow
-\`\`\`typescript
-// 1. Check if Google OAuth is enabled for this tenant
-const providersRes = await fetch('/v1/auth/providers', {
-  headers: { 'X-API-Key': 'pk_live_your_key' },
-});
-const { providers } = await providersRes.json();
-const googleEnabled = providers.some((p: any) => p.provider === 'google');
-// 2. Get Google authorization URL
-const redirectUri = window.location.origin + '/oauth/callback';
-const urlRes = await fetch(
-  \`/v1/auth/google/url?redirect_uri=\${encodeURIComponent(redirectUri)}\`,
-  { headers: { 'X-API-Key': 'pk_live_your_key' } }
-);
-const { authorization_url } = await urlRes.json();
-// 3. Redirect user to Google
-window.location.href = authorization_url;
-// 4. Google redirects to /v1/auth/google/callback (backend handles this)
-// 5. Backend redirects to YOUR redirect_uri with tokens in URL FRAGMENT (#)
-// 6. In your /oauth/callback page, read tokens from hash (NOT query params)
-const hash = window.location.hash.substring(1);
-const params = new URLSearchParams(hash);
-const accessToken = params.get('access_token');
-const refreshToken = params.get('refresh_token');
-const expiresIn = params.get('expires_in');
-// Also check query params for errors
-const urlParams = new URLSearchParams(window.location.search);
-const error = urlParams.get('error');
-if (error) {
-  console.error('OAuth failed:', urlParams.get('error_description'));
-}
-\`\`\`
-## 8. Authenticated Requests
-\`\`\`typescript
-// After login, include Authorization header
-const response = await fetch('/v1/auth/me', {
-  headers: {
-    'X-API-Key': 'pk_live_your_key',
-    'Authorization': \`Bearer \${localStorage.getItem('access_token')}\`,
-  },
-});
-const user = await response.json();
-\`\`\`
-## 9. Logout
-\`\`\`typescript
-await fetch('/v1/auth/logout', {
-  method: 'POST',
-  headers: {
-    'X-API-Key': 'pk_live_your_key',
-    'Authorization': \`Bearer \${localStorage.getItem('access_token')}\`,
-  },
-});
-localStorage.removeItem('access_token');
-localStorage.removeItem('refresh_token');
+                            text: `# Authentication Flow Guide
+## 1. Registration Flow
+\`\`\`typescript
+// 1. Register user
+const response = await fetch('/v1/auth/register', {
+  method: 'POST',
+  headers: {
+    'X-API-Key': 'pk_live_your_key',
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    email: 'user@example.com',
+    password: 'SecurePass123', // min 8 chars, 1 upper, 1 lower, 1 digit
+    display_name: 'John Doe',  // optional
+  }),
+});
+const { access_token, refresh_token, user } = await response.json();
+// 2. Store tokens securely
+localStorage.setItem('access_token', access_token);
+localStorage.setItem('refresh_token', refresh_token);
+// User is now logged in
+\`\`\`
+## 2. Login Flow
+\`\`\`typescript
+const response = await fetch('/v1/auth/login', {
+  method: 'POST',
+  headers: {
+    'X-API-Key': 'pk_live_your_key',
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    email: 'user@example.com',
+    password: 'SecurePass123',
+  }),
+});
+if (!response.ok) {
+  const error = await response.json();
+  // Handle error: error.detail contains the message
+  throw new Error(error.detail);
+}
+const { access_token, refresh_token, user } = await response.json();
+\`\`\`
+## 3. Token Refresh Flow
+\`\`\`typescript
+// Call this when access_token expires (expires_in seconds from login)
+const response = await fetch('/v1/auth/refresh', {
+  method: 'POST',
+  headers: {
+    'X-API-Key': 'pk_live_your_key',
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    refresh_token: localStorage.getItem('refresh_token'),
+  }),
+});
+const { access_token } = await response.json();
+localStorage.setItem('access_token', access_token);
+\`\`\`
+## 4. Password Reset Flow
+\`\`\`typescript
+// Step 1: Request reset email
+await fetch('/v1/auth/forgot-password', {
+  method: 'POST',
+  headers: {
+    'X-API-Key': 'pk_live_your_key',
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({ email: 'user@example.com' }),
+});
+// Always succeeds (security)
+// Step 2: User clicks link in email with token
+// Step 3: Reset password with token
+await fetch('/v1/auth/reset-password', {
+  method: 'POST',
+  headers: {
+    'X-API-Key': 'pk_live_your_key',
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    token: 'token-from-email-link',
+    new_password: 'NewSecurePass123',
+  }),
+});
+\`\`\`
+## 5. Change Password Flow (Authenticated)
+\`\`\`typescript
+await fetch('/v1/auth/change-password', {
+  method: 'POST',
+  headers: {
+    'X-API-Key': 'pk_live_your_key',
+    'Authorization': 'Bearer your_jwt_token',
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    current_password: 'OldPass123!',
+    new_password: 'NewPass456!',
+  }),
+});
+\`\`\`
+## 6. Email Verification Flow
+\`\`\`typescript
+// Registration may require email verification depending on tenant config.
+// Check the register response for verification_required: true
+const registerResult = await response.json();
+if (registerResult.verification_required) {
+  // 1. Show "Check your email" message — NO tokens returned
+  // 2. User clicks link in email → opens /verify-email?token=xxx
+  // 3. Verify the email token
+  const verifyResponse = await fetch('/v1/auth/verify-email', {
+    method: 'POST',
+    headers: {
+      'X-API-Key': 'pk_live_your_key',
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ token: tokenFromUrl }),
+  });
+  // Returns: { message: "Email verified successfully" }
+  // 4. If token expired, user can request a new one
+  await fetch('/v1/auth/resend-verification', {
+    method: 'POST',
+    headers: {
+      'X-API-Key': 'pk_live_your_key',
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ email: 'user@example.com' }),
+  });
+  // Rate limited: 3/hour
+  // 5. After verification, user can login normally via /v1/auth/login
+} else {
+  // No verification required — tokens returned directly from register
+  localStorage.setItem('access_token', registerResult.access_token);
+  localStorage.setItem('refresh_token', registerResult.refresh_token);
+}
+\`\`\`
+## 7. Google OAuth Flow
+\`\`\`typescript
+// 1. Check if Google OAuth is enabled for this tenant
+const providersRes = await fetch('/v1/auth/providers', {
+  headers: { 'X-API-Key': 'pk_live_your_key' },
+});
+const { providers } = await providersRes.json();
+const googleEnabled = providers.some((p: any) => p.provider === 'google');
+// 2. Get Google authorization URL
+const redirectUri = window.location.origin + '/oauth/callback';
+const urlRes = await fetch(
+  \`/v1/auth/google/url?redirect_uri=\${encodeURIComponent(redirectUri)}\`,
+  { headers: { 'X-API-Key': 'pk_live_your_key' } }
+);
+const { authorization_url } = await urlRes.json();
+// 3. Redirect user to Google
+window.location.href = authorization_url;
+// 4. Google redirects to /v1/auth/google/callback (backend handles this)
+// 5. Backend redirects to YOUR redirect_uri with tokens in URL FRAGMENT (#)
+// 6. In your /oauth/callback page, read tokens from hash (NOT query params)
+const hash = window.location.hash.substring(1);
+const params = new URLSearchParams(hash);
+const accessToken = params.get('access_token');
+const refreshToken = params.get('refresh_token');
+const expiresIn = params.get('expires_in');
+// Also check query params for errors
+const urlParams = new URLSearchParams(window.location.search);
+const error = urlParams.get('error');
+if (error) {
+  console.error('OAuth failed:', urlParams.get('error_description'));
+}
+\`\`\`
+## 8. Authenticated Requests
+\`\`\`typescript
+// After login, include Authorization header
+const response = await fetch('/v1/auth/me', {
+  headers: {
+    'X-API-Key': 'pk_live_your_key',
+    'Authorization': \`Bearer \${localStorage.getItem('access_token')}\`,
+  },
+});
+const user = await response.json();
+\`\`\`
+## 9. Logout
+\`\`\`typescript
+await fetch('/v1/auth/logout', {
+  method: 'POST',
+  headers: {
+    'X-API-Key': 'pk_live_your_key',
+    'Authorization': \`Bearer \${localStorage.getItem('access_token')}\`,
+  },
+});
+localStorage.removeItem('access_token');
+localStorage.removeItem('refresh_token');
 \`\`\``,
                         },
                     ],
@@ -3144,225 +3679,412 @@ localStorage.removeItem('refresh_token');
                     content: [
                         {
                             type: "text",
-                            text: `# Common Implementation Patterns
-## 1. API Request Wrapper
-\`\`\`typescript
-const API_URL = process.env.NEXT_PUBLIC_API_URL;
-const API_KEY = process.env.NEXT_PUBLIC_API_KEY; // pk_live_*
-interface RequestOptions {
-  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-  body?: any;
-  requiresAuth?: boolean;
-}
-async function apiRequest<T>(endpoint: string, options: RequestOptions = {}): Promise<T> {
-  const { method = 'GET', body, requiresAuth = false } = options;
-  const headers: Record<string, string> = {
-    'X-API-Key': API_KEY,
-    'Content-Type': 'application/json',
-  };
-  if (requiresAuth) {
-    const token = localStorage.getItem('access_token');
-    if (token) {
-      headers['Authorization'] = \`Bearer \${token}\`;
-    }
-  }
-  const response = await fetch(\`\${API_URL}\${endpoint}\`, {
-    method,
-    headers,
-    body: body ? JSON.stringify(body) : undefined,
-  });
-  if (response.status === 401 && requiresAuth) {
-    // Try to refresh token
-    const refreshed = await refreshToken();
-    if (refreshed) {
-      // Retry request with new token
-      headers['Authorization'] = \`Bearer \${localStorage.getItem('access_token')}\`;
-      const retryResponse = await fetch(\`\${API_URL}\${endpoint}\`, {
-        method,
-        headers,
-        body: body ? JSON.stringify(body) : undefined,
-      });
-      if (!retryResponse.ok) throw new Error('Request failed after refresh');
-      return retryResponse.json();
-    }
-    // Redirect to login
-    window.location.href = '/login';
-    throw new Error('Session expired');
-  }
-  if (!response.ok) {
-    const error = await response.json();
-    throw new Error(error.detail || 'Request failed');
-  }
-  return response.json();
-}
-\`\`\`
-## 2. Auto Token Refresh
-\`\`\`typescript
-async function refreshToken(): Promise<boolean> {
-  const refreshToken = localStorage.getItem('refresh_token');
-  if (!refreshToken) return false;
-  try {
-    const response = await fetch(\`\${API_URL}/v1/auth/refresh\`, {
-      method: 'POST',
-      headers: {
-        'X-API-Key': API_KEY,
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify({ refresh_token: refreshToken }),
-    });
-    if (!response.ok) return false;
-    const data = await response.json();
-    localStorage.setItem('access_token', data.access_token);
-    return true;
-  } catch {
-    return false;
-  }
-}
-\`\`\`
-## 3. React Hook Example
-\`\`\`typescript
-import { useState, useEffect } from 'react';
-function useAuth() {
-  const [user, setUser] = useState(null);
-  const [loading, setLoading] = useState(true);
-  useEffect(() => {
-    const token = localStorage.getItem('access_token');
-    if (!token) {
-      setLoading(false);
-      return;
-    }
-    apiRequest('/v1/auth/me', { requiresAuth: true })
-      .then(setUser)
-      .catch(() => {
-        localStorage.removeItem('access_token');
-        localStorage.removeItem('refresh_token');
-      })
-      .finally(() => setLoading(false));
-  }, []);
-  const login = async (email: string, password: string) => {
-    const data = await apiRequest('/v1/auth/login', {
-      method: 'POST',
-      body: { email, password },
-    });
-    localStorage.setItem('access_token', data.access_token);
-    localStorage.setItem('refresh_token', data.refresh_token);
-    setUser(data.user);
-    return data;
-  };
-  const logout = async () => {
-    await apiRequest('/v1/auth/logout', { method: 'POST', requiresAuth: true });
-    localStorage.removeItem('access_token');
-    localStorage.removeItem('refresh_token');
-    setUser(null);
-  };
-  return { user, loading, login, logout };
-}
-\`\`\`
-## 4. Error Handling
-\`\`\`typescript
-interface ApiError {
-  detail: string;
-  error?: string;
-  error_description?: string;
-}
-function handleApiError(error: ApiError): string {
-  // Common error messages
-  const errorMessages: Record<string, string> = {
-    'Invalid email or password': 'The email or password you entered is incorrect.',
-    'User already exists': 'An account with this email already exists.',
-    'Invalid token': 'Your session has expired. Please log in again.',
-    'Rate limit exceeded': 'Too many requests. Please try again later.',
-  };
-  return errorMessages[error.detail] || error.detail || 'An error occurred';
-}
-\`\`\`
-## 5. OAuth Callback Handling
-\`\`\`typescript
-// After Google OAuth, tokens arrive in the URL FRAGMENT (#), not query params (?)
-// This is because fragments are never sent to the server — they stay client-side only
-function parseOAuthCallback(): { access_token: string; refresh_token: string; expires_in: string } | null {
-  // Check for errors in query params first
-  const urlParams = new URLSearchParams(window.location.search);
-  const error = urlParams.get('error');
-  if (error) {
-    console.error('OAuth error:', urlParams.get('error_description'));
-    return null;
-  }
-  // Parse tokens from URL fragment
-  const hash = window.location.hash.substring(1); // Remove leading #
-  const params = new URLSearchParams(hash);
-  const access_token = params.get('access_token');
-  const refresh_token = params.get('refresh_token');
-  const expires_in = params.get('expires_in');
-  if (!access_token || !refresh_token) return null;
-  // Clean up the URL (remove fragment)
-  window.history.replaceState({}, '', window.location.pathname);
-  return { access_token, refresh_token, expires_in: expires_in || '3600' };
-}
-// Usage in your OAuth callback page:
-// const tokens = parseOAuthCallback();
-// if (tokens) {
-//   localStorage.setItem('access_token', tokens.access_token);
-//   localStorage.setItem('refresh_token', tokens.refresh_token);
-//   navigate('/dashboard');
-// }
-\`\`\`
-## 6. Environment Variables (Vite / React)
-\`\`\`env
-# .env
-VITE_API_URL=https://api.yoursaas.com
-VITE_API_KEY=pk_live_your_public_key_here
-\`\`\`
-## 7. Environment Variables (Next.js)
-\`\`\`env
-# .env.local
-NEXT_PUBLIC_API_URL=https://api.yoursaas.com
-NEXT_PUBLIC_API_KEY=pk_live_your_public_key_here
+                            text: `# Common Implementation Patterns
+## 1. API Request Wrapper
+\`\`\`typescript
+const API_URL = process.env.NEXT_PUBLIC_API_URL;
+const API_KEY = process.env.NEXT_PUBLIC_API_KEY; // pk_live_*
+interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  body?: any;
+  requiresAuth?: boolean;
+}
+async function apiRequest<T>(endpoint: string, options: RequestOptions = {}): Promise<T> {
+  const { method = 'GET', body, requiresAuth = false } = options;
+  const headers: Record<string, string> = {
+    'X-API-Key': API_KEY,
+    'Content-Type': 'application/json',
+  };
+  if (requiresAuth) {
+    const token = localStorage.getItem('access_token');
+    if (token) {
+      headers['Authorization'] = \`Bearer \${token}\`;
+    }
+  }
+  const response = await fetch(\`\${API_URL}\${endpoint}\`, {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (response.status === 401 && requiresAuth) {
+    // Try to refresh token
+    const refreshed = await refreshToken();
+    if (refreshed) {
+      // Retry request with new token
+      headers['Authorization'] = \`Bearer \${localStorage.getItem('access_token')}\`;
+      const retryResponse = await fetch(\`\${API_URL}\${endpoint}\`, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+      });
+      if (!retryResponse.ok) throw new Error('Request failed after refresh');
+      return retryResponse.json();
+    }
+    // Redirect to login
+    window.location.href = '/login';
+    throw new Error('Session expired');
+  }
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(error.detail || 'Request failed');
+  }
+  return response.json();
+}
+\`\`\`
+## 2. Auto Token Refresh
+\`\`\`typescript
+async function refreshToken(): Promise<boolean> {
+  const refreshToken = localStorage.getItem('refresh_token');
+  if (!refreshToken) return false;
+  try {
+    const response = await fetch(\`\${API_URL}/v1/auth/refresh\`, {
+      method: 'POST',
+      headers: {
+        'X-API-Key': API_KEY,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ refresh_token: refreshToken }),
+    });
+    if (!response.ok) return false;
+    const data = await response.json();
+    localStorage.setItem('access_token', data.access_token);
+    return true;
+  } catch {
+    return false;
+  }
+}
+\`\`\`
+## 3. React Hook Example
+\`\`\`typescript
+import { useState, useEffect } from 'react';
+function useAuth() {
+  const [user, setUser] = useState(null);
+  const [loading, setLoading] = useState(true);
+  useEffect(() => {
+    const token = localStorage.getItem('access_token');
+    if (!token) {
+      setLoading(false);
+      return;
+    }
+    apiRequest('/v1/auth/me', { requiresAuth: true })
+      .then(setUser)
+      .catch(() => {
+        localStorage.removeItem('access_token');
+        localStorage.removeItem('refresh_token');
+      })
+      .finally(() => setLoading(false));
+  }, []);
+  const login = async (email: string, password: string) => {
+    const data = await apiRequest('/v1/auth/login', {
+      method: 'POST',
+      body: { email, password },
+    });
+    localStorage.setItem('access_token', data.access_token);
+    localStorage.setItem('refresh_token', data.refresh_token);
+    setUser(data.user);
+    return data;
+  };
+  const logout = async () => {
+    await apiRequest('/v1/auth/logout', { method: 'POST', requiresAuth: true });
+    localStorage.removeItem('access_token');
+    localStorage.removeItem('refresh_token');
+    setUser(null);
+  };
+  return { user, loading, login, logout };
+}
+\`\`\`
+## 4. Error Handling
+\`\`\`typescript
+interface ApiError {
+  detail: string;
+  error?: string;
+  error_description?: string;
+}
+function handleApiError(error: ApiError): string {
+  // Common error messages
+  const errorMessages: Record<string, string> = {
+    'Invalid email or password': 'The email or password you entered is incorrect.',
+    'User already exists': 'An account with this email already exists.',
+    'Invalid token': 'Your session has expired. Please log in again.',
+    'Rate limit exceeded': 'Too many requests. Please try again later.',
+  };
+  return errorMessages[error.detail] || error.detail || 'An error occurred';
+}
+\`\`\`
+## 5. OAuth Callback Handling
+\`\`\`typescript
+// After Google OAuth, tokens arrive in the URL FRAGMENT (#), not query params (?)
+// This is because fragments are never sent to the server — they stay client-side only
+function parseOAuthCallback(): { access_token: string; refresh_token: string; expires_in: string } | null {
+  // Check for errors in query params first
+  const urlParams = new URLSearchParams(window.location.search);
+  const error = urlParams.get('error');
+  if (error) {
+    console.error('OAuth error:', urlParams.get('error_description'));
+    return null;
+  }
+  // Parse tokens from URL fragment
+  const hash = window.location.hash.substring(1); // Remove leading #
+  const params = new URLSearchParams(hash);
+  const access_token = params.get('access_token');
+  const refresh_token = params.get('refresh_token');
+  const expires_in = params.get('expires_in');
+  if (!access_token || !refresh_token) return null;
+  // Clean up the URL (remove fragment)
+  window.history.replaceState({}, '', window.location.pathname);
+  return { access_token, refresh_token, expires_in: expires_in || '3600' };
+}
+// Usage in your OAuth callback page:
+// const tokens = parseOAuthCallback();
+// if (tokens) {
+//   localStorage.setItem('access_token', tokens.access_token);
+//   localStorage.setItem('refresh_token', tokens.refresh_token);
+//   navigate('/dashboard');
+// }
+\`\`\`
+## 6. Environment Variables (Vite / React)
+\`\`\`env
+# .env
+VITE_API_URL=https://api.yoursaas.com
+VITE_API_KEY=pk_live_your_public_key_here
+\`\`\`
+## 7. Environment Variables (Next.js)
+\`\`\`env
+# .env.local
+NEXT_PUBLIC_API_URL=https://api.yoursaas.com
+NEXT_PUBLIC_API_KEY=pk_live_your_public_key_here
 \`\`\``,
                         },
                     ],
                 };
             }
+            case "validate_credentials": {
+                const detected = detectKeyType(API_KEY);
+                if (!detected.type) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `# Credentials check
+❌ **No SAAS_API_KEY configured.**
+Most authenticated tools (\`list_end_users\`, \`list_oauth_providers\`, etc.)
+will fail. Add the key to your MCP client config:
+\`\`\`json
+{
+  "mcpServers": {
+    "genlobe": {
+      "command": "node",
+      "args": ["…/dist/index.js"],
+      "env": {
+        "SAAS_API_URL": "${API_URL}",
+        "SAAS_API_KEY": "sk_live_…"
+      }
+    }
+  }
+}
+\`\`\`
+Then restart the MCP. Run \`get_security_guide\` for guidance on which key
+type to pick.`,
+                            },
+                        ],
+                    };
+                }
+                // Probe with a known sk_live-only endpoint. /v1/auth/users is a safe
+                // smoke test for secret keys; for public keys this will 401, which
+                // is itself useful information.
+                let probeResult;
+                try {
+                    const r = await fetch(`${API_URL}/v1/auth/users?limit=1`, {
+                        headers: { "X-API-Key": API_KEY },
+                    });
+                    probeResult = { ok: r.ok, status: r.status };
+                    if (!r.ok) {
+                        try {
+                            probeResult.detail = (await r.json()).detail;
+                        }
+                        catch { }
+                    }
+                }
+                catch (err) {
+                    probeResult = { ok: false, status: 0, detail: String(err) };
+                }
+                const lines = [
+                    `# Credentials check`,
+                    ``,
+                    `**Configured API URL:** \`${API_URL}\``,
+                    `**Detected key type:** ${detected.type === "public" ? "🟢 Public (`pk_live_*`)" : "🔴 Secret (`sk_live_*`)"}`,
+                    `**Key prefix:** \`${detected.prefix}\``,
+                    ``,
+                ];
+                if (detected.type === "secret") {
+                    if (probeResult.ok) {
+                        lines.push(`✅ Probe call \`GET /v1/auth/users\` succeeded — the key authenticates.`, ``, `**You can use this key for:** every end-user endpoint that accepts API key auth, including admin-style listings (users, orgs) and end-user signup/login on behalf of users.`, ``, `**You CANNOT use this key for:** anything that runs in a browser. Run \`get_security_guide\` before writing frontend code.`);
+                    }
+                    else {
+                        lines.push(`❌ Probe call \`GET /v1/auth/users\` failed: HTTP ${probeResult.status}${probeResult.detail ? ` — ${probeResult.detail}` : ""}.`, ``, `Possible causes: key revoked, wrong tenant, wrong API URL, network blocked, backend down.`);
+                    }
+                }
+                else {
+                    if (probeResult.status === 401 || probeResult.status === 403) {
+                        lines.push(`✅ Behavior matches a public key: \`/v1/auth/users\` returned HTTP ${probeResult.status} as expected. Public keys can only call auth endpoints (\`/v1/auth/register\`, \`/v1/auth/login\`, etc.).`, ``, `Run \`get_security_guide\` for the full list of allowed endpoints.`);
+                    }
+                    else if (probeResult.ok) {
+                        lines.push(`⚠️  Probe unexpectedly succeeded with what looks like a public key. Verify the prefix; if it really is a secret key the prefix detection is wrong.`);
+                    }
+                    else {
+                        lines.push(`❌ Probe failed unexpectedly: HTTP ${probeResult.status}${probeResult.detail ? ` — ${probeResult.detail}` : ""}.`);
+                    }
+                }
+                return { content: [{ type: "text", text: lines.join("\n") }] };
+            }
+            case "list_end_users": {
+                if (!API_KEY) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `❌ Cannot list end-users: SAAS_API_KEY is not configured. Add a secret key (\`sk_live_*\`) to the MCP env. Use \`validate_credentials\` to verify.`,
+                            },
+                        ],
+                    };
+                }
+                const skip = args.skip ?? 0;
+                const limit = args.limit ?? 20;
+                try {
+                    const r = await fetch(`${API_URL}/v1/auth/users?skip=${skip}&limit=${Math.min(limit, 100)}`, { headers: { "X-API-Key": API_KEY } });
+                    const body = await r.json();
+                    if (!r.ok) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `HTTP ${r.status} from /v1/auth/users — ${body.detail ?? JSON.stringify(body)}.\n\nIf the key is \`pk_live_*\`, this endpoint is restricted to secret keys. Run \`get_security_guide\` for details.`,
+                                },
+                            ],
+                        };
+                    }
+                    return {
+                        content: [{ type: "text", text: JSON.stringify(body, null, 2) }],
+                    };
+                }
+                catch (err) {
+                    return {
+                        content: [{ type: "text", text: `Network error: ${err}` }],
+                    };
+                }
+            }
+            case "list_oauth_providers": {
+                if (!API_KEY) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `❌ Cannot list providers: SAAS_API_KEY not configured.`,
+                            },
+                        ],
+                    };
+                }
+                try {
+                    const r = await fetch(`${API_URL}/v1/auth/providers`, {
+                        headers: { "X-API-Key": API_KEY },
+                    });
+                    const body = await r.json();
+                    if (!r.ok) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `HTTP ${r.status} from /v1/auth/providers — ${body.detail ?? JSON.stringify(body)}.`,
+                                },
+                            ],
+                        };
+                    }
+                    const providers = body.providers ?? [];
+                    if (providers.length === 0) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `No OAuth providers configured for this tenant. The "Sign in with Google" / GitHub / etc. buttons would not work — only email/password login is wired up. Configure providers from the tenant dashboard before generating social-login UIs.`,
+                                },
+                            ],
+                        };
+                    }
+                    const list = providers.map(p => `- **${p.name}** (\`${p.provider}\`)`).join("\n");
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `# OAuth providers configured for this tenant\n\n${list}\n\nWire each one with \`GET /v1/auth/{provider}/url\` to get the authorization URL.`,
+                            },
+                        ],
+                    };
+                }
+                catch (err) {
+                    return {
+                        content: [{ type: "text", text: `Network error: ${err}` }],
+                    };
+                }
+            }
+            case "get_security_guide": {
+                const detected = detectKeyType(API_KEY);
+                return {
+                    content: [{ type: "text", text: SECURITY_GUIDE(detected.type) }],
+                };
+            }
+            case "recommend_stack": {
+                const appType = args.app_type;
+                const detected = detectKeyType(API_KEY);
+                return {
+                    content: [
+                        { type: "text", text: STACK_RECOMMENDATION(appType, detected.type) },
+                    ],
+                };
+            }
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
@@ -3381,10 +4103,14 @@ NEXT_PUBLIC_API_KEY=pk_live_your_public_key_here
 });
 // Start the server
 async function main() {
-    console.error(`🚀 Multi-tenant SaaS API MCP Server v2.1.0`);
+    console.error(`🚀 Multi-tenant SaaS API MCP Server v${SERVER_VERSION}`);
     console.error(`📡 API URL: ${API_URL}`);
-    console.error(`🔑 API Key: ${API_KEY ? "Configured" : "Not configured"}`);
-    console.error(`\nAvailable tools:`);
+    console.error(`🔑 API Key: ${API_KEY ? "Configured" : "Not configured (set SAAS_API_KEY to enable authenticated calls)"}`);
+    console.error(`\n👉 Recommended first calls (vibecoding flow):`);
+    console.error(`  1. validate_credentials  — verify key + detect type (pk_live_* vs sk_live_*)`);
+    console.error(`  2. get_security_guide    — safe-usage rules for the detected key type`);
+    console.error(`  3. recommend_stack       — pick a framework that won't leak your key`);
+    console.error(`\nReference tools:`);
     console.error(`  - get_api_overview: Understand the API architecture`);
     console.error(`  - get_end_user_endpoints: Get endpoint documentation`);
     console.error(`  - get_sdk_template: Get TypeScript SDK template`);
@@ -3393,6 +4119,9 @@ async function main() {
     console.error(`  - search_endpoints: Search for endpoints`);
     console.error(`  - get_endpoint_details: Get specific endpoint info`);
     console.error(`  - get_openapi_spec: Get full OpenAPI spec`);
+    console.error(`\nAuthenticated helpers:`);
+    console.error(`  - list_end_users         (sk_live_* required)`);
+    console.error(`  - list_oauth_providers   (any key)`);
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }