@genlobe/mcp-server 2.2.0

package/dist/index.js

@@ -0,0 +1,3402 @@
+#!/usr/bin/env node
+/**
+ * MCP Server for Multi-tenant SaaS API
+ *
+ * This server provides AI assistants with comprehensive API documentation
+ * and tools to understand how to build frontends using this API.
+ *
+ * The API has TWO types of endpoints:
+ * 1. TENANT/DASHBOARD endpoints - For tenant admins (JWT auth from dashboard login)
+ * 2. END-USER endpoints - For end-users of tenants (API Key + optional JWT)
+ *
+ * When building a frontend for END-USERS of a tenant, you should ONLY use
+ * the End-user endpoints, NOT the Tenant/Dashboard endpoints.
+ *
+ * Usage:
+ *   npx @multiagent/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";
+// =============================================================================
+// Configuration
+// =============================================================================
+const API_URL = process.env.SAAS_API_URL || process.env.API_URL || "https://api.example.com";
+const API_KEY = process.env.SAAS_API_KEY || process.env.API_KEY || "";
+// Cache for API responses
+const cache = new Map();
+const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+// =============================================================================
+// API Documentation - Embedded for reliability
+// =============================================================================
+/**
+ * CRITICAL: This embedded documentation ensures AI assistants have accurate
+ * information even if the API is not accessible.
+ */
+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
+`,
+    base_url: API_URL,
+    documentation_urls: {
+        swagger: `${API_URL}/docs`,
+        redoc: `${API_URL}/redoc`,
+        openapi: `${API_URL}/v1/developer/openapi.json`
+    }
+};
+// =============================================================================
+// End-User Endpoints (for building frontends)
+// =============================================================================
+const END_USER_ENDPOINTS = {
+    authentication: {
+        description: "User authentication endpoints - login, register, password reset. Protected by rate limiting.",
+        endpoints: [
+            {
+                method: "POST",
+                path: "/v1/auth/register",
+                summary: "Register a new user",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: false },
+                rate_limit: "3 per hour per IP (blocked 30 min after exceeding)",
+                request_body: {
+                    email: "string (required) - valid email",
+                    password: "string (required) - min 8 chars, 1 uppercase, 1 lowercase, 1 digit",
+                    display_name: "string (optional)",
+                    locale: "string (optional, default: 'en')",
+                    return_to: "string (optional) - frontend URL for email verification redirect (e.g. https://app.example.com/verify-email)"
+                },
+                response: "CONDITIONAL - depends on tenant email verification setting",
+                response_when_no_verification: {
+                    access_token: "string - JWT access token (expires in 1 hour)",
+                    refresh_token: "string - JWT refresh token",
+                    token_type: "Bearer",
+                    expires_in: "number - seconds until expiration",
+                    user: {
+                        id: "uuid",
+                        email: "string",
+                        display_name: "string | null",
+                        avatar_url: "string | null",
+                        is_active: "boolean",
+                        created_at: "ISO datetime"
+                    }
+                },
+                response_when_verification_required: {
+                    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"
+}`
+            },
+            {
+                method: "POST",
+                path: "/v1/auth/login",
+                summary: "Login with email and password",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: false },
+                rate_limit: "10 per 15 min per IP (blocked 15 min after exceeding)",
+                request_body: {
+                    email: "string (required)",
+                    password: "string (required)"
+                },
+                response: "Same as register",
+                example_request: `{
+  "email": "user@example.com",
+  "password": "SecurePass123"
+}`
+            },
+            {
+                method: "POST",
+                path: "/v1/auth/refresh",
+                summary: "Refresh access token using refresh token",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: false },
+                request_body: {
+                    refresh_token: "string (required)"
+                },
+                response: "Same as login (with same refresh_token returned)"
+            },
+            {
+                method: "GET",
+                path: "/v1/auth/me",
+                summary: "Get current authenticated user info",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: {
+                    id: "uuid",
+                    email: "string",
+                    display_name: "string | null",
+                    avatar_url: "string | null",
+                    is_active: "boolean",
+                    created_at: "ISO datetime"
+                }
+            },
+            {
+                method: "POST",
+                path: "/v1/auth/logout",
+                summary: "Logout (invalidates token on client side)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: { message: "Successfully logged out" }
+            },
+            {
+                method: "POST",
+                path: "/v1/auth/forgot-password",
+                summary: "Request password reset email",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: false },
+                rate_limit: "3 per hour per IP (blocked 30 min after exceeding)",
+                request_body: {
+                    email: "string (required)"
+                },
+                response: { message: "Password reset email sent" },
+                note: "Always returns success even if email doesn't exist (security)"
+            },
+            {
+                method: "POST",
+                path: "/v1/auth/reset-password",
+                summary: "Reset password using token from email",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: false },
+                request_body: {
+                    token: "string (required) - from email link",
+                    new_password: "string (required) - same requirements as register"
+                }
+            },
+            {
+                method: "POST",
+                path: "/v1/auth/change-password",
+                summary: "Change password for authenticated user",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                rate_limit: "5 per hour per user (blocked 30 min after exceeding)",
+                request_body: {
+                    current_password: "string (required)",
+                    new_password: "string (required) - same requirements as register"
+                },
+                response: { message: "Password changed successfully" }
+            },
+            {
+                method: "POST",
+                path: "/v1/auth/verify-email",
+                summary: "Verify end-user email with token (requires API Key)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: false },
+                request_body: {
+                    token: "string (required) - from verification email link"
+                },
+                response: { message: "Email verified successfully" },
+                note: "Use when the verification link is opened in a context that has the tenant API key (e.g. end-user app)."
+            },
+            {
+                method: "POST",
+                path: "/v1/auth/verify-email-with-token",
+                summary: "Verify end-user email with token only (no API Key)",
+                auth: { api_key: "none", jwt: false },
+                rate_limit: "20 per hour per IP",
+                request_body: {
+                    token: "string (required) - from verification email link"
+                },
+                response: { message: "Email verified successfully" },
+                note: "Use when the verification link is opened from a page without API key (e.g. dashboard domain). Rate limited by IP."
+            },
+            {
+                method: "POST",
+                path: "/v1/auth/resend-verification",
+                summary: "Resend verification email for end-user",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: false },
+                rate_limit: "3 per hour per IP (blocked 30 min after exceeding)",
+                request_body: {
+                    email: "string (required) - valid email address"
+                },
+                response: { message: "Verification email sent" },
+                note: "Always returns success even if email doesn't exist (security). Rate limited to prevent abuse."
+            },
+            {
+                method: "GET",
+                path: "/v1/auth/providers",
+                summary: "List enabled OAuth providers for this tenant",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: false },
+                response: {
+                    providers: "[ { provider: 'google', name: 'Google' }, ... ]"
+                },
+                note: "Use on login page to show/hide 'Login with Google' button. Only returns providers with is_enabled in tenant config."
+            },
+            {
+                method: "GET",
+                path: "/v1/auth/google/url",
+                summary: "Get Google OAuth authorization URL",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: false },
+                query_params: {
+                    redirect_uri: "string (required) - frontend URL where Google redirects after auth (must match tenant config)"
+                },
+                response: { authorization_url: "string - redirect user to this URL" }
+            },
+            {
+                method: "GET",
+                path: "/v1/auth/google/callback",
+                summary: "Google OAuth callback (called by Google, not by your frontend)",
+                auth: { api_key: "none", jwt: false },
+                query_params: {
+                    code: "from Google",
+                    state: "from Google (HMAC-signed, contains tenant_id + redirect_uri)"
+                },
+                response: "Redirects to frontend redirect_uri with tokens in URL fragment (#): access_token, refresh_token, expires_in. Errors redirect with ?error=oauth_failed&error_description=..."
+            }
+        ]
+    },
+    organizations: {
+        description: "Organization management - create orgs, manage members, invitations, subscriptions, usage",
+        endpoints: [
+            {
+                method: "GET",
+                path: "/v1/organizations/my-organizations",
+                summary: "Get all organizations the current user belongs to",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: {
+                    organizations: [
+                        {
+                            id: "uuid",
+                            name: "string",
+                            slug: "string",
+                            description: "string | null",
+                            logo_url: "string | null",
+                            role: "owner | admin | member | developer",
+                            created_at: "ISO datetime"
+                        }
+                    ]
+                }
+            },
+            {
+                method: "POST",
+                path: "/v1/organizations",
+                summary: "Create a new organization (user becomes owner)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: {
+                    name: "string (required)",
+                    slug: "string (required) - URL-friendly identifier",
+                    description: "string (optional)"
+                },
+                example_request: `{
+  "name": "My Company",
+  "slug": "my-company",
+  "description": "Our awesome company"
+}`
+            },
+            {
+                method: "GET",
+                path: "/v1/organizations/{organization_id}",
+                summary: "Get organization details (must be a member)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true }
+            },
+            {
+                method: "PUT",
+                path: "/v1/organizations/{organization_id}",
+                summary: "Update organization (owner/admin only)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: {
+                    name: "string (optional)",
+                    description: "string (optional)",
+                    logo_url: "string (optional)"
+                }
+            },
+            {
+                method: "GET",
+                path: "/v1/organizations/{organization_id}/departments",
+                summary: "List organization departments",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true }
+            },
+            {
+                method: "GET",
+                path: "/v1/organizations/{organization_id}/members",
+                summary: "List all members of the organization",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: [
+                    {
+                        user_id: "uuid",
+                        email: "string",
+                        display_name: "string | null",
+                        role: "owner | admin | member | developer",
+                        joined_at: "ISO datetime"
+                    }
+                ]
+            },
+            {
+                method: "PUT",
+                path: "/v1/organizations/{organization_id}/members/{user_id}",
+                summary: "Update member role (owner/admin only)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: {
+                    role: "admin | member | developer (required)"
+                }
+            },
+            {
+                method: "DELETE",
+                path: "/v1/organizations/{organization_id}/members/{user_id}",
+                summary: "Remove a member from the organization (owner/admin only)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true }
+            },
+            {
+                method: "POST",
+                path: "/v1/organizations/{organization_id}/members/{user_id}/deactivate",
+                summary: "Deactivate an organization member",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true }
+            },
+            {
+                method: "POST",
+                path: "/v1/organizations/{organization_id}/invite",
+                summary: "Invite a user to the organization (owner/admin only)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: {
+                    email: "string (required)",
+                    role: "admin | member | developer (required)"
+                }
+            },
+            {
+                method: "POST",
+                path: "/v1/organizations/{organization_id}/invitations/{invitation_id}/resend",
+                summary: "Resend an organization invitation",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true }
+            },
+            {
+                method: "DELETE",
+                path: "/v1/organizations/{organization_id}/invitations/{invitation_id}",
+                summary: "Cancel/delete an organization invitation",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true }
+            },
+            {
+                method: "POST",
+                path: "/v1/organizations/accept-invitation",
+                summary: "Accept an organization invitation",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: {
+                    token: "string (required) - from invitation email"
+                }
+            },
+            {
+                method: "POST",
+                path: "/v1/organizations/reject-invitation",
+                summary: "Reject an organization invitation (public, no auth required)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: false },
+                request_body: {
+                    token: "string (required) - from invitation email"
+                }
+            },
+            {
+                method: "GET",
+                path: "/v1/organizations/invitations/pending",
+                summary: "Get pending invitations for an email",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: false },
+                query_params: {
+                    email: "string (required) - email to check"
+                }
+            },
+            {
+                method: "GET",
+                path: "/v1/organizations/invitations/{invitation_token}",
+                summary: "Get invitation details by token (public)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: false }
+            },
+            {
+                method: "POST",
+                path: "/v1/organizations/{organization_id}/set-default",
+                summary: "Set default organization for the current user",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true }
+            },
+            // Organization subscription management
+            {
+                method: "GET",
+                path: "/v1/organizations/{organization_id}/subscription",
+                summary: "Get organization's current subscription with plan details",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: "SubscriptionWithPlanResponse - includes subscription + embedded plan object",
+                note: "Requires BILLING_READ permission. Returns null if no active subscription."
+            },
+            {
+                method: "POST",
+                path: "/v1/organizations/{organization_id}/subscription/{plan_id}",
+                summary: "Subscribe organization to a plan",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: "SubscriptionResponse",
+                note: "Requires BILLING_MANAGE permission (owner/admin)."
+            },
+            {
+                method: "PUT",
+                path: "/v1/organizations/{organization_id}/subscription",
+                summary: "Update organization subscription",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: {
+                    plan_id: "uuid (optional)",
+                    billing_cycle: "string (optional) - 'monthly' or 'yearly'",
+                    subscription_metadata: "object (optional)"
+                },
+                response: "SubscriptionResponse",
+                note: "Requires BILLING_MANAGE permission."
+            },
+            {
+                method: "DELETE",
+                path: "/v1/organizations/{organization_id}/subscription",
+                summary: "Cancel organization subscription",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                query_params: {
+                    cancel_at_period_end: "boolean (default: true) - If true, access continues until period end"
+                },
+                response: {
+                    message: "string",
+                    subscription: "SubscriptionResponse"
+                },
+                note: "Requires BILLING_MANAGE permission."
+            },
+            // Organization usage
+            {
+                method: "GET",
+                path: "/v1/organizations/{organization_id}/usage",
+                summary: "Get organization usage statistics",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: {
+                    usage_stats: "object - Aggregated usage for the organization"
+                },
+                note: "Requires ORG_READ permission. Must be a member of the organization."
+            },
+            {
+                method: "GET",
+                path: "/v1/organizations/{organization_id}/usage/user/{target_user_id}",
+                summary: "Get usage statistics for a specific user in the organization",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: {
+                    usage: "object - User's usage within this organization"
+                },
+                note: "Requires MEMBERS_READ permission."
+            },
+            {
+                method: "POST",
+                path: "/v1/organizations/{organization_id}/usage/check",
+                summary: "Check if organization would exceed usage limits",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                query_params: {
+                    additional_messages: "number (default: 0) - Additional messages to check",
+                    additional_tokens: "number (default: 0) - Additional tokens to check"
+                },
+                response: {
+                    would_exceed: "boolean - Whether limits would be exceeded",
+                    limits: "object - Current limit details"
+                },
+                note: "Pre-validate before making API calls. Requires ORG_READ permission."
+            }
+        ]
+    },
+    subscriptions: {
+        description: "Subscription and billing management with Stripe",
+        endpoints: [
+            {
+                method: "GET",
+                path: "/v1/subscriptions/plans",
+                summary: "List all available subscription plans",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: [
+                    {
+                        id: "uuid",
+                        name: "string",
+                        description: "string",
+                        price_monthly: "number",
+                        price_yearly: "number",
+                        currency: "string (e.g., 'usd')",
+                        features: "array of strings",
+                        is_active: "boolean",
+                        is_free: "boolean",
+                        max_cost_usd_per_month: "number | null - Maximum AI usage cost per month",
+                        max_messages_per_month: "number | null - Maximum AI requests per month",
+                        max_tokens_per_month: "number | null - DEPRECATED: Use max_cost_usd_per_month",
+                        stripe_product_id: "string",
+                        stripe_price_id_monthly: "string",
+                        stripe_price_id_yearly: "string",
+                        created_at: "ISO datetime",
+                        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"
+  }
+]`
+            },
+            {
+                method: "GET",
+                path: "/v1/subscriptions/current",
+                summary: "Get current user's active subscription",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: {
+                    id: "uuid",
+                    plan_id: "uuid",
+                    organization_id: "uuid",
+                    tenant_id: "uuid",
+                    stripe_customer_id: "string",
+                    stripe_subscription_id: "string",
+                    billing_cycle: "monthly | yearly",
+                    status: "active | cancelled | past_due | incomplete | trialing | unpaid",
+                    current_period_start: "ISO datetime",
+                    current_period_end: "ISO datetime",
+                    cancel_at_period_end: "boolean",
+                    canceled_at: "ISO datetime | null",
+                    trial_start: "ISO datetime | null",
+                    trial_end: "ISO datetime | null",
+                    subscription_metadata: "object - custom metadata",
+                    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"
+}`,
+                note: "Does NOT include plan_name or price. Use plan_id to fetch plan details if needed."
+            },
+            {
+                method: "POST",
+                path: "/v1/subscriptions/checkout",
+                summary: "Create Stripe checkout session for subscription",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: {
+                    plan_id: "uuid (required)",
+                    success_url: "string (required) - URL to redirect after success",
+                    cancel_url: "string (required) - URL to redirect on cancel",
+                    organization_id: "uuid (optional) - for org subscriptions"
+                },
+                response: {
+                    checkout_url: "string - Stripe checkout URL",
+                    session_id: "string"
+                }
+            },
+            {
+                method: "GET",
+                path: "/v1/subscriptions/plans/{plan_id}",
+                summary: "Get plan details by ID",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: "PlanResponse (same as /v1/subscriptions/plans list item)",
+                note: "Tenant-isolated: plan must belong to tenant or be a global plan."
+            },
+            {
+                method: "POST",
+                path: "/v1/subscriptions/subscriptions",
+                summary: "Create a new subscription",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: {
+                    plan_id: "uuid (required)",
+                    organization_id: "uuid (required)",
+                    billing_cycle: "string (default: 'monthly') - 'monthly' or 'yearly'",
+                    subscription_metadata: "object (optional) - custom metadata"
+                },
+                response: "SubscriptionResponse (same as /v1/subscriptions/current)"
+            },
+            {
+                method: "GET",
+                path: "/v1/subscriptions/subscriptions/{subscription_id}",
+                summary: "Get subscription details by ID",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: "SubscriptionResponse",
+                note: "User must own the subscription."
+            },
+            {
+                method: "PUT",
+                path: "/v1/subscriptions/subscriptions/{subscription_id}",
+                summary: "Update a subscription",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: {
+                    plan_id: "uuid (optional)",
+                    billing_cycle: "string (optional) - 'monthly' or 'yearly'",
+                    subscription_metadata: "object (optional)"
+                },
+                response: "SubscriptionResponse",
+                note: "User must own the subscription."
+            },
+            {
+                method: "DELETE",
+                path: "/v1/subscriptions/subscriptions/{subscription_id}",
+                summary: "Cancel/delete a subscription",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                query_params: {
+                    cancel_at_period_end: "boolean (default: true) - if true, access continues until period end"
+                },
+                response: "SubscriptionResponse",
+                note: "Returns 403 if user doesn't own the subscription."
+            },
+            {
+                method: "GET",
+                path: "/v1/subscriptions/users/{user_id}/usage",
+                summary: "Get user plan usage statistics",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: {
+                    id: "uuid",
+                    organization_id: "uuid",
+                    user_id: "uuid",
+                    plan_id: "uuid | null",
+                    period_start: "ISO datetime",
+                    period_end: "ISO datetime",
+                    messages_count: "number",
+                    tokens_count: "number",
+                    usage_metadata: "object",
+                    created_at: "ISO datetime",
+                    updated_at: "ISO datetime"
+                },
+                note: "User can only access own usage. Returns 404 if no active plan."
+            },
+            {
+                method: "GET",
+                path: "/v1/subscriptions/users/{user_id}/usage/limits",
+                summary: "Check user usage limits",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: {
+                    limits: "object with plan limit details"
+                },
+                note: "User can only check own limits."
+            },
+            {
+                method: "PUT",
+                path: "/v1/subscriptions/users/{user_id}/plan/{plan_id}",
+                summary: "Assign a plan to a user",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: {
+                    success: "boolean",
+                    user_id: "uuid",
+                    plan_id: "uuid"
+                },
+                note: "User can only assign plans to themselves. Typically done via subscriptions."
+            },
+            {
+                method: "POST",
+                path: "/v1/subscriptions/organizations/{organization_id}/resume",
+                summary: "Resume a cancelled organization subscription",
+                auth: { api_key: "sk_live_* ONLY", jwt: false },
+                query_params: {
+                    user_id: "uuid (required) - User requesting the resume"
+                },
+                response: "SubscriptionResponse"
+            },
+            {
+                method: "GET",
+                path: "/v1/subscriptions/organizations/{organization_id}/invoices",
+                summary: "Get organization invoices from Stripe",
+                auth: { api_key: "sk_live_* ONLY", jwt: false },
+                query_params: {
+                    user_id: "uuid (required) - User requesting invoices"
+                },
+                response: "array of Stripe invoice objects"
+            },
+            {
+                method: "DELETE",
+                path: "/v1/subscriptions/organizations/{organization_id}/subscription",
+                summary: "Cancel organization subscription",
+                auth: { api_key: "sk_live_* ONLY", jwt: false },
+                query_params: {
+                    user_id: "uuid (required)",
+                    cancel_at_period_end: "boolean (default: true)"
+                },
+                response: "SubscriptionResponse"
+            }
+        ]
+    },
+    billing: {
+        description: "Billing operations - checkout, plan changes, cancellation. All endpoints require SECRET key (sk_live_*) only.",
+        endpoints: [
+            {
+                method: "GET",
+                path: "/v1/billing/available-plans",
+                summary: "List available billing plans for upgrade/downgrade",
+                auth: { api_key: "sk_live_* ONLY", jwt: false },
+                response: {
+                    success: "boolean",
+                    plans: "array of plan objects with: id (uuid), name (string), price_cents (int), price_display (string), currency (string), features (array), is_free (boolean), stripe_price_id (string | null)"
+                }
+            },
+            {
+                method: "POST",
+                path: "/v1/billing/create-checkout-session",
+                summary: "Create Stripe checkout session for billing",
+                auth: { api_key: "sk_live_* ONLY", jwt: false },
+                request_body: {
+                    user_id: "uuid (required) - End-user ID",
+                    organization_id: "uuid (required) - Organization to subscribe",
+                    plan_id: "uuid (required) - Target plan",
+                    success_url: "string (required) - Redirect URL after successful checkout",
+                    cancel_url: "string (required) - Redirect URL on cancel"
+                },
+                response: {
+                    checkout_url: "string - Stripe hosted checkout URL",
+                    session_id: "string - Stripe session ID",
+                    plan_name: "string - Name of selected plan",
+                    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"
+}`
+            },
+            {
+                method: "POST",
+                path: "/v1/billing/change-plan",
+                summary: "Change current subscription plan (upgrade/downgrade)",
+                auth: { api_key: "sk_live_* ONLY", jwt: false },
+                request_body: {
+                    subscription_id: "uuid (required) - Current subscription ID",
+                    new_plan_id: "uuid (required) - Target plan ID"
+                },
+                response: {
+                    success: "boolean",
+                    message: "string",
+                    plan_name: "string",
+                    subscription_id: "uuid | null",
+                    stripe_subscription_id: "string | null",
+                    status: "string | null",
+                    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"
+}`
+            },
+            {
+                method: "POST",
+                path: "/v1/billing/cancel-subscription",
+                summary: "Cancel current subscription",
+                auth: { api_key: "sk_live_* ONLY", jwt: false },
+                query_params: {
+                    subscription_id: "uuid (required) - Subscription to cancel",
+                    cancel_at_period_end: "boolean (default: true) - If true, access continues until period end"
+                },
+                response: {
+                    success: "boolean",
+                    message: "string",
+                    cancel_at_period_end: "boolean"
+                }
+            },
+            {
+                method: "GET",
+                path: "/v1/billing/billing-history-org/{organization_id}",
+                summary: "Get billing history (Stripe invoices) for organization",
+                auth: { api_key: "sk_live_* ONLY", jwt: false },
+                query_params: {
+                    limit: "number (default: 20) - Number of invoices to return"
+                },
+                response: {
+                    success: "boolean",
+                    organization_id: "string",
+                    invoices: "array of Stripe invoice objects",
+                    total_invoices: "number"
+                },
+                note: "Returns 404 if organization not found or doesn't belong to tenant."
+            }
+        ]
+    },
+    usage: {
+        description: "Usage tracking and limits. Endpoints map to /v1/api/usage/* (current/history) and /v1/usage/* (stats/check/consume).",
+        endpoints: [
+            {
+                method: "GET",
+                path: "/v1/api/usage/current",
+                summary: "Get current usage statistics for authenticated user",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                query_params: {
+                    organization_id: "uuid (required) - Organization ID to check usage for"
+                },
+                response: {
+                    period_start: "ISO datetime",
+                    period_end: "ISO datetime",
+                    plan_name: "string",
+                    plan_id: "uuid",
+                    usage: {
+                        messages: {
+                            current: "number - Messages used in current period",
+                            max: "number | 'unlimited' - Maximum allowed messages",
+                            remaining: "number | 'unlimited' - Remaining messages",
+                            percentage: "number - Usage percentage (0-100)"
+                        },
+                        cost_usd: {
+                            current: "number - Current AI cost in USD",
+                            max: "number | 'unlimited' - Maximum allowed cost",
+                            remaining: "number | 'unlimited' - Remaining budget",
+                            percentage: "number - Usage percentage (0-100)"
+                        },
+                        tokens: {
+                            total: "number - Total tokens used",
+                            input: "number - Input tokens",
+                            output: "number - Output tokens"
+                        }
+                    },
+                    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
+}`
+            },
+            {
+                method: "GET",
+                path: "/v1/api/usage/history",
+                summary: "Get usage history",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                query_params: {
+                    organization_id: "uuid (required) - Organization ID",
+                    limit: "number (default: 20) - Number of records to return",
+                    offset: "number (default: 0) - Pagination offset"
+                },
+                response: "array of usage records with period dates, usage counts, and metadata"
+            },
+            {
+                method: "GET",
+                path: "/v1/api/usage/entity-usage",
+                summary: "Get custom entity usage statistics",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                query_params: {
+                    organization_id: "uuid (required) - Organization ID"
+                },
+                response: "object with entity usage statistics (schemas count, records count, etc.)"
+            },
+            {
+                method: "GET",
+                path: "/v1/usage/stats",
+                summary: "Get comprehensive usage statistics for user and organization",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                query_params: {
+                    organization_id: "uuid (required) - Organization ID to check usage for"
+                },
+                response: {
+                    period_start: "string | null",
+                    period_end: "string | null",
+                    plan_name: "string | null",
+                    plan_id: "string | null",
+                    usage: "object - Usage stats by type",
+                    error: "string | null"
+                }
+            },
+            {
+                method: "POST",
+                path: "/v1/usage/check",
+                summary: "Check if usage is allowed without consuming",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: {
+                    tokens: "number (required, gt 0) - Amount to check",
+                    usage_type: "string (default: 'tokens') - 'tokens' or 'messages'",
+                    user_id: "uuid (required) - Must match authenticated user",
+                    organization_id: "uuid (required)"
+                },
+                response: {
+                    allowed: "boolean",
+                    current_usage: "number",
+                    max_limit: "number | 'unlimited'",
+                    remaining: "number | 'unlimited'",
+                    requested: "number | null",
+                    error: "string | null"
+                }
+            },
+            {
+                method: "POST",
+                path: "/v1/usage/consume",
+                summary: "Consume usage tokens/messages",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: {
+                    tokens: "number (required, gt 0) - Amount to consume",
+                    usage_type: "string (default: 'tokens') - 'tokens' or 'messages'",
+                    user_id: "uuid (required) - Must match authenticated user",
+                    organization_id: "uuid (required)"
+                },
+                response: {
+                    success: "boolean",
+                    consumed: "number | object | null",
+                    usage_type: "string | null",
+                    allowed: "boolean",
+                    limits: "object - Current limits state",
+                    error: "string | null"
+                },
+                note: "Returns 402 Payment Required if usage limits exceeded."
+            }
+        ]
+    },
+    agents: {
+        description: "AI Agents - Interact with AI agents created by the tenant",
+        endpoints: [
+            {
+                method: "GET",
+                path: "/v1/user/agents/available",
+                summary: "List available agents for end-users",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                query_params: {
+                    skip: "number (default: 0)",
+                    limit: "number (default: 50, max: 100)"
+                },
+                response: [
+                    {
+                        id: "uuid",
+                        tenant_id: "uuid",
+                        name: "string",
+                        description: "string | null",
+                        system_prompt: "string",
+                        response_type: "text | audio | video",
+                        rag_provider: "NONE | GOOGLE_FILE_SEARCH",
+                        is_active: "boolean",
+                        rag_config: "object | null",
+                        mcp_servers: "array of MCP server configs",
+                        created_by: "uuid",
+                        created_at: "ISO datetime",
+                        updated_at: "ISO datetime"
+                    }
+                ],
+                note: "Returns only active agents that the tenant has made available"
+            },
+            {
+                method: "GET",
+                path: "/v1/user/agents/{agent_id}",
+                summary: "Get agent details by ID",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: "AgentResponse (same as list)"
+            },
+            {
+                method: "POST",
+                path: "/v1/user/agents/{agent_id}/chat",
+                summary: "Chat with an agent (execute)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                rate_limit: "60 per minute per user",
+                request_body: {
+                    messages: "array (optional) - Chat messages [{'role': 'user', 'content': '...'}]",
+                    input: "string (optional) - Alternative to messages for single input",
+                    conversation_id: "uuid (optional) - Conversation ID for persistent history. If provided, previous messages are auto-injected and new messages are saved.",
+                    model: "string (optional) - LLM model override",
+                    temperature: "number (optional)",
+                    max_tokens: "number (optional)",
+                    use_tools: "boolean (default: true) - Enable agent tools",
+                    use_rag: "boolean (default: true) - Enable RAG retrieval"
+                },
+                response: {
+                    id: "uuid - Execution ID",
+                    agent_id: "uuid",
+                    tenant_id: "uuid",
+                    user_id: "uuid - Your user ID",
+                    organization_id: "uuid - Your organization ID",
+                    input_text: "string - User input",
+                    output_text: "string - Agent response",
+                    tokens_used: "number",
+                    execution_time_ms: "number",
+                    status: "SUCCESS | FAILED | PENDING",
+                    error_message: "string | null",
+                    execution_metadata: "object | null",
+                    created_at: "ISO datetime"
+                },
+                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"
+}`,
+                note: "Usage is tracked against your plan limits. Use /v1/api/usage/current to check remaining usage."
+            },
+            {
+                method: "GET",
+                path: "/v1/user/agents/{agent_id}/history",
+                summary: "Get your conversation history with an agent",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                query_params: {
+                    skip: "number (default: 0)",
+                    limit: "number (default: 20, max: 50)"
+                },
+                response: "Array of AgentExecutionResponse (same structure as chat response)",
+                note: "Returns only YOUR past interactions with this agent"
+            },
+            {
+                method: "POST",
+                path: "/v1/user/agents/{agent_id}/conversations",
+                summary: "Create a new conversation session with an agent",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: {
+                    title: "string (optional) - Conversation title"
+                },
+                response: {
+                    id: "uuid",
+                    tenant_id: "uuid",
+                    user_id: "uuid",
+                    agent_id: "uuid",
+                    title: "string | null",
+                    status: "ACTIVE | ENDED",
+                    created_at: "ISO datetime",
+                    updated_at: "ISO datetime"
+                },
+                note: "Use the returned conversation ID in the chat endpoint's conversation_id field to persist messages"
+            },
+            {
+                method: "GET",
+                path: "/v1/user/agents/{agent_id}/conversations",
+                summary: "List your conversations with an agent",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                query_params: {
+                    skip: "number (default: 0)",
+                    limit: "number (default: 20, max: 50)"
+                },
+                response: "Array of ConversationResponse (same as create response)"
+            },
+            {
+                method: "GET",
+                path: "/v1/user/agents/{agent_id}/conversations/{conversation_id}",
+                summary: "Get a conversation with all messages",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: {
+                    id: "uuid",
+                    tenant_id: "uuid",
+                    user_id: "uuid",
+                    agent_id: "uuid",
+                    title: "string | null",
+                    status: "ACTIVE | ENDED",
+                    created_at: "ISO datetime",
+                    updated_at: "ISO datetime",
+                    messages: "Array of { id, role, content, tokens_used, message_metadata, created_at }"
+                }
+            },
+            {
+                method: "DELETE",
+                path: "/v1/user/agents/{agent_id}/conversations/{conversation_id}",
+                summary: "End a conversation (soft close)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: "204 No Content",
+                note: "Marks the conversation as ENDED. No new messages can be added."
+            }
+        ],
+        important_notes: [
+            "All agent endpoints require end-user authentication (API Key + JWT)",
+            "Usage is tracked for billing against your subscription plan",
+            "Agents with tools may take longer to respond as tools are executed",
+            "RAG-enabled agents include context from knowledge bases in responses",
+            "Use conversations to maintain chat history across multiple requests - create a conversation, then pass its ID to the chat endpoint"
+        ]
+    },
+    users: {
+        description: "User management - CRUD, settings, activation/deactivation. Dual auth: sk_live_* for admin ops, pk_live_* + JWT for self-service.",
+        endpoints: [
+            {
+                method: "POST",
+                path: "/v1/users",
+                summary: "Create a new user (admin, JWT required)",
+                auth: { api_key: "sk_live_* ONLY", jwt: true },
+                request_body: {
+                    sub: "string (required) - Unique user identifier",
+                    email: "string (optional) - valid email",
+                    display_name: "string (optional, max 100)",
+                    avatar_url: "string (optional)",
+                    locale: "string (optional, default: 'en')",
+                    tenant_id: "uuid (optional)",
+                    is_email_verified: "boolean (default: false)",
+                    status: "string (default: 'pending')",
+                    is_active: "boolean (default: true)"
+                },
+                response: {
+                    id: "uuid",
+                    email: "string",
+                    display_name: "string | null",
+                    avatar_url: "string | null",
+                    locale: "string",
+                    is_active: "boolean",
+                    tenant_id: "uuid",
+                    sub: "string",
+                    is_email_verified: "boolean",
+                    status: "string",
+                    current_plan_id: "uuid | null",
+                    default_organization_id: "uuid | null",
+                    created_at: "ISO datetime",
+                    updated_at: "ISO datetime",
+                    settings: "UserSettingsResponse | null"
+                }
+            },
+            {
+                method: "GET",
+                path: "/v1/users",
+                summary: "List all users (SECRET KEY ONLY)",
+                auth: { api_key: "sk_live_* ONLY", jwt: false },
+                query_params: {
+                    page: "number (default: 1)",
+                    per_page: "number (default: 20, max: 100)",
+                    include_inactive: "boolean (default: false)"
+                },
+                response: {
+                    users: "array of UserResponse",
+                    total: "number",
+                    page: "number",
+                    per_page: "number",
+                    has_next: "boolean",
+                    has_prev: "boolean"
+                },
+                note: "Returns only users belonging to the secret key's tenant."
+            },
+            {
+                method: "GET",
+                path: "/v1/users/stats",
+                summary: "Get user statistics (SECRET KEY ONLY)",
+                auth: { api_key: "sk_live_* ONLY", jwt: false },
+                response: {
+                    total_users: "number",
+                    active_users: "number",
+                    inactive_users: "number"
+                }
+            },
+            {
+                method: "GET",
+                path: "/v1/users/{user_id}",
+                summary: "Get user by ID (sk_live_* or self with pk_live_*)",
+                auth: { api_key: "pk_live_* (self) or sk_live_*", jwt: "optional" },
+                query_params: {
+                    include_settings: "boolean (default: false) - Include user settings in response"
+                },
+                response: {
+                    id: "uuid",
+                    email: "string",
+                    display_name: "string | null",
+                    avatar_url: "string | null",
+                    locale: "string",
+                    is_active: "boolean",
+                    tenant_id: "uuid",
+                    sub: "string",
+                    is_email_verified: "boolean",
+                    status: "string",
+                    current_plan_id: "uuid | null",
+                    default_organization_id: "uuid | null",
+                    created_at: "ISO datetime",
+                    updated_at: "ISO datetime",
+                    settings: "UserSettingsResponse | null (only if include_settings=true)"
+                },
+                note: "With sk_live_*: can view any user in tenant. With pk_live_* + JWT: can only view own profile (returns 404 for other users)."
+            },
+            {
+                method: "PUT",
+                path: "/v1/users/{user_id}",
+                summary: "Update user profile",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: {
+                    display_name: "string (optional, max 100)",
+                    avatar_url: "string (optional)",
+                    locale: "string (optional)"
+                },
+                response: "UserResponse (same fields as GET)",
+                note: "With sk_live_*: can update any user. With pk_live_* + JWT: can only update own profile."
+            },
+            {
+                method: "PUT",
+                path: "/v1/users/{user_id}/settings",
+                summary: "Update user settings",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: "UserSettingsUpdate object (extensible, currently empty placeholder for future settings)",
+                response: "UserWithSettingsResponse (UserResponse + settings object)",
+                note: "With sk_live_*: can update any user's settings. With pk_live_* + JWT: can only update own settings."
+            },
+            {
+                method: "POST",
+                path: "/v1/users/{user_id}/deactivate",
+                summary: "Deactivate a user (soft delete)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: "UserResponse",
+                note: "Sets is_active=false. With sk_live_*: can deactivate any user. With pk_live_* + JWT: can deactivate own account."
+            },
+            {
+                method: "POST",
+                path: "/v1/users/{user_id}/activate",
+                summary: "Activate a user (SECRET KEY ONLY)",
+                auth: { api_key: "sk_live_* ONLY", jwt: false },
+                response: "UserResponse",
+                note: "Sets is_active=true. Admin operation only."
+            },
+            {
+                method: "DELETE",
+                path: "/v1/users/{user_id}",
+                summary: "Delete a user (SECRET KEY ONLY, soft delete)",
+                auth: { api_key: "sk_live_* ONLY", jwt: false },
+                response: "204 No Content",
+                note: "Performs soft delete (deactivation). Returns 404 if user not found."
+            }
+        ]
+    },
+    plans: {
+        description: "Plan listing - browse available subscription plans. All endpoints require JWT authentication.",
+        endpoints: [
+            {
+                method: "GET",
+                path: "/v1/plans",
+                summary: "List all plans (paginated)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                query_params: {
+                    skip: "number (default: 0) - Pagination offset",
+                    limit: "number (default: 100, max: 1000) - Items per page",
+                    include_inactive: "boolean (default: false) - Include deactivated plans"
+                },
+                response: {
+                    plans: "array of PlanResponse",
+                    total: "number",
+                    page: "number",
+                    per_page: "number",
+                    has_next: "boolean",
+                    has_prev: "boolean"
+                }
+            },
+            {
+                method: "GET",
+                path: "/v1/plans/active",
+                summary: "List active plans only",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: "array of PlanResponse",
+                note: "Useful for displaying plan options on pricing pages."
+            },
+            {
+                method: "GET",
+                path: "/v1/plans/free",
+                summary: "List free plans only",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: "array of PlanResponse",
+                note: "Useful for signup flows — auto-assign a free plan."
+            },
+            {
+                method: "GET",
+                path: "/v1/plans/{plan_id}",
+                summary: "Get plan details by ID",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: {
+                    id: "uuid",
+                    name: "string",
+                    description: "string | null",
+                    price_monthly: "number",
+                    price_yearly: "number",
+                    currency: "string (default: 'USD')",
+                    max_messages_per_month: "number | null",
+                    max_cost_usd_per_month: "number | null",
+                    features: "array of strings",
+                    is_free: "boolean",
+                    is_active: "boolean",
+                    stripe_product_id: "string | null",
+                    stripe_price_id_monthly: "string | null",
+                    stripe_price_id_yearly: "string | null",
+                    created_at: "ISO datetime",
+                    updated_at: "ISO datetime"
+                },
+                note: "Returns 404 if plan not found."
+            }
+        ]
+    },
+    ai: {
+        description: "AI services (LLM completions)",
+        endpoints: [
+            {
+                method: "POST",
+                path: "/v1/ai/completions",
+                summary: "Generate AI completion (streaming supported)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: {
+                    model: "string (e.g., 'gpt-4', 'claude-3-opus')",
+                    messages: [
+                        { role: "system | user | assistant", content: "string" }
+                    ],
+                    max_tokens: "number (optional)",
+                    temperature: "number (optional, 0-2)",
+                    stream: "boolean (optional)"
+                }
+            }
+        ]
+    },
+    entities: {
+        description: "Entity management (Custom Data) - define schemas and manage records. Two contexts: End-User API (API Key + JWT + X-Organization-Id) and Dashboard (Tenant JWT).",
+        endpoints: [
+            // ── End-User Schema Endpoints ──
+            {
+                method: "GET",
+                path: "/v1/entity/schemas",
+                summary: "List all entity schemas in the organization",
+                auth: { api_key: "sk_live_*", jwt: true, headers: "X-Organization-Id required" },
+                query_params: {
+                    page: "number (default 1)",
+                    size: "number (default 20, max 100)"
+                }
+            },
+            {
+                method: "POST",
+                path: "/v1/entity/schemas",
+                summary: "Create a new entity schema",
+                auth: { api_key: "sk_live_*", jwt: true, headers: "X-Organization-Id required" },
+                request_body: {
+                    name: "string (required) - unique per organization",
+                    slug: "string (required) - unique per organization, lowercase/hyphens only",
+                    description: "string (optional)",
+                    fields_definition: "object (required) - field definitions with type, required, constraints"
+                },
+                notes: "Supported field types: string, integer, float, boolean, datetime, text, enum, email, url, phone. Returns 409 if name or slug already exists."
+            },
+            {
+                method: "GET",
+                path: "/v1/entity/schemas/{schema_id}",
+                summary: "Get a specific schema by ID",
+                auth: { api_key: "sk_live_*", jwt: true, headers: "X-Organization-Id required" }
+            },
+            {
+                method: "PUT",
+                path: "/v1/entity/schemas/{schema_id}",
+                summary: "Update an existing schema",
+                auth: { api_key: "sk_live_*", jwt: true, headers: "X-Organization-Id required" },
+                request_body: {
+                    name: "string (optional)",
+                    slug: "string (optional)",
+                    description: "string (optional)",
+                    fields_definition: "object (optional) - version auto-increments if changed",
+                    is_active: "boolean (optional)"
+                }
+            },
+            {
+                method: "DELETE",
+                path: "/v1/entity/schemas/{schema_id}",
+                summary: "Delete a schema (may fail if records exist)",
+                auth: { api_key: "sk_live_*", jwt: true, headers: "X-Organization-Id required" }
+            },
+            // ── End-User Record Endpoints ──
+            {
+                method: "POST",
+                path: "/v1/entity/records",
+                summary: "Create a new entity record",
+                auth: { api_key: "sk_live_* or pk_live_*", jwt: true, headers: "X-Organization-Id required" },
+                request_body: {
+                    schema_id: "uuid (required)",
+                    data: "object (required) - validated against schema fields_definition"
+                },
+                notes: "Sets created_by_id to the authenticated end-user."
+            },
+            {
+                method: "GET",
+                path: "/v1/entity/records/{record_id}",
+                summary: "Get a specific record by ID",
+                auth: { api_key: "sk_live_* or pk_live_*", jwt: true, headers: "X-Organization-Id required" }
+            },
+            {
+                method: "PUT",
+                path: "/v1/entity/records/{record_id}",
+                summary: "Update a record",
+                auth: { api_key: "sk_live_* or pk_live_*", jwt: true, headers: "X-Organization-Id required" },
+                request_body: {
+                    data: "object (required) - validated against schema fields_definition"
+                },
+                notes: "Sets updated_by_id to the authenticated end-user."
+            },
+            {
+                method: "DELETE",
+                path: "/v1/entity/records/{record_id}",
+                summary: "Delete a record",
+                auth: { api_key: "sk_live_* or pk_live_*", jwt: true, headers: "X-Organization-Id required" }
+            },
+            {
+                method: "POST",
+                path: "/v1/entity/records/search",
+                summary: "Advanced search for entity records with filters and ordering",
+                auth: { api_key: "sk_live_*", jwt: true, headers: "X-Organization-Id required" },
+                request_body: {
+                    schema_id: "uuid (optional) - filter by schema",
+                    query: "object (optional) - filters: {field: value} for equality, {field: {operator: 'gt', value: 100}} for operators"
+                },
+                query_params: {
+                    page: "number (default 1)",
+                    size: "number (default 20, max 100)",
+                    order_by: "string (default 'created_at')",
+                    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"] }
+  }
+}`
+            }
+        ]
+    },
+    departments: {
+        description: "Department management within organizations",
+        endpoints: [
+            {
+                method: "GET",
+                path: "/v1/departments/{department_id}",
+                summary: "Get department details by ID",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: false },
+                query_params: {
+                    user_id: "uuid (required) - User ID for membership verification"
+                },
+                response: {
+                    id: "uuid",
+                    organization_id: "uuid",
+                    name: "string",
+                    description: "string | null",
+                    is_default: "boolean",
+                    is_active: "boolean",
+                    settings: "object",
+                    created_at: "ISO datetime",
+                    updated_at: "ISO datetime"
+                },
+                note: "User must be a member of the organization this department belongs to."
+            }
+        ]
+    },
+    files: {
+        description: "End-user Drive - private file storage with folders. Users can upload/manage their own files and access shared tenant files (read-only). Shared files are controlled by the tenant's is_shared flag — only files explicitly marked as shared are visible to end-users.",
+        endpoints: [
+            {
+                method: "POST",
+                path: "/v1/user/files",
+                summary: "Upload a file to user's Drive",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                query_params: {
+                    description: "string (optional) - File description",
+                    folder_id: "uuid (optional) - Target folder ID (null = root)"
+                },
+                request_body: "multipart/form-data with 'file' field",
+                response: {
+                    message: "string",
+                    file: {
+                        id: "uuid",
+                        user_id: "uuid",
+                        tenant_id: "uuid",
+                        folder_id: "uuid | null",
+                        filename: "string",
+                        original_filename: "string",
+                        file_size: "integer",
+                        content_type: "string",
+                        storage_provider: "string",
+                        description: "string | null",
+                        extra_metadata: "object | null",
+                        created_at: "ISO datetime",
+                        updated_at: "ISO datetime"
+                    }
+                }
+            },
+            {
+                method: "GET",
+                path: "/v1/user/files",
+                summary: "List user's files with optional folder filter",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                query_params: {
+                    folder_id: "uuid (optional) - Filter by folder (null = root files)",
+                    skip: "integer (default: 0)",
+                    limit: "integer (default: 20, max: 100)"
+                },
+                response: {
+                    files: "UserFileResponse[]",
+                    total: "integer",
+                    skip: "integer",
+                    limit: "integer"
+                }
+            },
+            {
+                method: "GET",
+                path: "/v1/user/files/shared",
+                summary: "List shared tenant Drive files (read-only)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                query_params: {
+                    skip: "integer (default: 0)",
+                    limit: "integer (default: 20, max: 100)"
+                },
+                response: {
+                    files: "TenantFileResponse[]",
+                    total: "integer",
+                    skip: "integer",
+                    limit: "integer"
+                },
+                note: "Only returns files explicitly marked as shared by the tenant (is_shared=true). Files are private by default."
+            },
+            {
+                method: "GET",
+                path: "/v1/user/files/shared/{file_id}/download",
+                summary: "Download a shared tenant file",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: "Binary file content with Content-Disposition header",
+                note: "Returns 404 if the file is not marked as shared by the tenant."
+            },
+            {
+                method: "GET",
+                path: "/v1/user/files/{file_id}",
+                summary: "Get own file metadata",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: "UserFileResponse"
+            },
+            {
+                method: "GET",
+                path: "/v1/user/files/{file_id}/download",
+                summary: "Download own file",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: "Binary file content with Content-Disposition header"
+            },
+            {
+                method: "DELETE",
+                path: "/v1/user/files/{file_id}",
+                summary: "Delete own file",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: "204 No Content"
+            },
+            {
+                method: "PATCH",
+                path: "/v1/user/files/{file_id}/move",
+                summary: "Move file to folder (or root)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: {
+                    folder_id: "uuid | null - Target folder (null = move to root)"
+                },
+                response: "UserFileResponse"
+            },
+            {
+                method: "POST",
+                path: "/v1/user/files/folders",
+                summary: "Create a folder in user's Drive",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: {
+                    name: "string (required, max 255 chars)",
+                    parent_id: "uuid (optional) - Parent folder for nesting"
+                },
+                response: {
+                    id: "uuid",
+                    tenant_id: "uuid",
+                    user_id: "uuid",
+                    parent_id: "uuid | null",
+                    name: "string",
+                    path: "string - materialized path e.g. /Documents/Reports",
+                    created_at: "ISO datetime",
+                    updated_at: "ISO datetime"
+                }
+            },
+            {
+                method: "GET",
+                path: "/v1/user/files/folders",
+                summary: "List folders (root or children of parent)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                query_params: {
+                    parent_id: "uuid (optional) - List children of this folder (null = root)"
+                },
+                response: {
+                    folders: "FolderResponse[]"
+                }
+            },
+            {
+                method: "PATCH",
+                path: "/v1/user/files/folders/{folder_id}",
+                summary: "Rename a folder",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: {
+                    name: "string (required, max 255 chars)"
+                },
+                response: "FolderResponse"
+            },
+            {
+                method: "DELETE",
+                path: "/v1/user/files/folders/{folder_id}",
+                summary: "Delete an empty folder (409 if non-empty)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: "204 No Content",
+                note: "Folder must be empty (no files or subfolders). Move or delete contents first."
+            }
+        ]
+    },
+    external_agents: {
+        description: "External agent call tracking. Used by external agents (e.g., N8N workflows) to report their usage back to the platform for analytics and cost tracking.",
+        endpoints: [
+            {
+                method: "POST",
+                path: "/v1/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",
+                path_params: {
+                    agent_id: "uuid (required) - The external agent ID"
+                },
+                request_body: {
+                    user_id: "uuid (optional) - End-user who triggered the call. Defaults to authenticated user",
+                    organization_id: "uuid (optional) - Organization context. Defaults to user's default organization",
+                    input_tokens: "integer (optional, default: 0) - Number of input tokens consumed",
+                    output_tokens: "integer (optional, default: 0) - Number of output tokens consumed",
+                    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",
+                    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"
+                },
+                response: {
+                    id: "uuid",
+                    external_agent_id: "uuid",
+                    tenant_id: "uuid",
+                    user_id: "uuid | null",
+                    organization_id: "uuid | null",
+                    input_tokens: "integer",
+                    output_tokens: "integer",
+                    total_tokens: "integer",
+                    cost_usd: "number",
+                    duration_ms: "integer",
+                    status: "string - SUCCESS or ERROR",
+                    error_message: "string | null",
+                    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."
+            }
+        ]
+    }
+};
+// =============================================================================
+// 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 };
+`;
+// =============================================================================
+// 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) |
+`;
+// =============================================================================
+// API Client
+// =============================================================================
+async function fetchFromApi(endpoint) {
+    const cacheKey = endpoint;
+    const cached = cache.get(cacheKey);
+    if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
+        return cached.data;
+    }
+    const headers = {
+        "Content-Type": "application/json",
+    };
+    if (API_KEY) {
+        headers["X-API-Key"] = API_KEY;
+    }
+    try {
+        const response = await fetch(`${API_URL}${endpoint}`, { headers });
+        if (!response.ok) {
+            throw new Error(`API request failed: ${response.status} ${response.statusText}`);
+        }
+        const data = await response.json();
+        cache.set(cacheKey, { data, timestamp: Date.now() });
+        return data;
+    }
+    catch (error) {
+        if (cached) {
+            console.error(`API fetch failed, using cached data: ${error}`);
+            return cached.data;
+        }
+        throw error;
+    }
+}
+// =============================================================================
+// MCP Server Implementation
+// =============================================================================
+const server = new Server({
+    name: "saas-multi-agent-api",
+    version: "2.2.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        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
+
+Call this first to understand the API architecture and authentication model.`,
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                    required: [],
+                },
+            },
+            {
+                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
+
+Categories: authentication, organizations, subscriptions, billing, usage, agents, users, plans, ai, entities, departments, external_agents`,
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        category: {
+                            type: "string",
+                            description: "Filter by category. Leave empty for all endpoints.",
+                            enum: ["authentication", "organizations", "subscriptions", "billing", "usage", "agents", "users", "plans", "ai", "entities", "departments", "files", "external_agents"],
+                        },
+                    },
+                    required: [],
+                },
+            },
+            {
+                name: "get_request_headers",
+                description: "Get detailed information about required HTTP headers for API requests.",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                    required: [],
+                },
+            },
+            {
+                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
+
+You can use this as a starting point for your frontend.`,
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                    required: [],
+                },
+            },
+            {
+                name: "get_openapi_spec",
+                description: "Get the complete OpenAPI specification (JSON) from the live API. Use this for detailed schema information.",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                    required: [],
+                },
+            },
+            {
+                name: "search_endpoints",
+                description: "Search for endpoints by keyword. Searches path, summary, and description.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        query: {
+                            type: "string",
+                            description: "Search keyword (e.g., 'login', 'organization', 'checkout')",
+                        },
+                    },
+                    required: ["query"],
+                },
+            },
+            {
+                name: "get_endpoint_details",
+                description: "Get detailed information about a specific endpoint including request/response schemas.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        path: {
+                            type: "string",
+                            description: "The endpoint path (e.g., '/v1/auth/login')",
+                        },
+                        method: {
+                            type: "string",
+                            description: "HTTP method",
+                            enum: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+                        },
+                    },
+                    required: ["path"],
+                },
+            },
+            {
+                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
+- Logout`,
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                    required: [],
+                },
+            },
+            {
+                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
+- Environment variables`,
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                    required: [],
+                },
+            },
+        ],
+    };
+});
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "get_api_overview": {
+                return {
+                    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
+- Those are for tenant admin dashboards, not end-user apps`,
+                        },
+                    ],
+                };
+            }
+            case "get_end_user_endpoints": {
+                const category = args.category;
+                let endpoints = END_USER_ENDPOINTS;
+                if (category && category in END_USER_ENDPOINTS) {
+                    endpoints = { [category]: END_USER_ENDPOINTS[category] };
+                }
+                return {
+                    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
+- GET /v1/departments/{department_id} - Get department details`,
+                        },
+                    ],
+                };
+            }
+            case "get_request_headers": {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: REQUEST_HEADERS,
+                        },
+                    ],
+                };
+            }
+            case "get_sdk_template": {
+                return {
+                    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();
+\`\`\``,
+                        },
+                    ],
+                };
+            }
+            case "get_openapi_spec": {
+                try {
+                    const spec = await fetchFromApi("/v1/developer/openapi.json");
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify(spec, null, 2),
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                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.`,
+                            },
+                        ],
+                    };
+                }
+            }
+            case "search_endpoints": {
+                const query = (args.query || "").toLowerCase();
+                const results = [];
+                // Search in embedded endpoints
+                for (const [category, data] of Object.entries(END_USER_ENDPOINTS)) {
+                    for (const endpoint of data.endpoints || []) {
+                        const searchText = `${endpoint.path} ${endpoint.summary} ${endpoint.method}`.toLowerCase();
+                        if (searchText.includes(query)) {
+                            results.push({
+                                category,
+                                method: endpoint.method,
+                                path: endpoint.path,
+                                summary: endpoint.summary,
+                                auth: endpoint.auth,
+                            });
+                        }
+                    }
+                }
+                if (results.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `No endpoints found matching "${query}".
+
+Try searching for:
+- auth, login, register, password
+- organization, member, invite
+- subscription, plan, checkout
+- billing, usage`,
+                            },
+                        ],
+                    };
+                }
+                return {
+                    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'}
+`).join('\n')}`,
+                        },
+                    ],
+                };
+            }
+            case "get_endpoint_details": {
+                const path = args.path;
+                const method = (args.method || "GET").toUpperCase();
+                // Search in embedded endpoints
+                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}` : ''}`,
+                                    },
+                                ],
+                            };
+                        }
+                    }
+                }
+                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).
+
+Use search_endpoints tool to find available endpoints.`,
+                        },
+                    ],
+                };
+            }
+            case "get_authentication_flow": {
+                return {
+                    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');
+\`\`\``,
+                        },
+                    ],
+                };
+            }
+            case "get_common_patterns": {
+                return {
+                    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
+\`\`\``,
+                        },
+                    ],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Start the server
+async function main() {
+    console.error(`🚀 Multi-tenant SaaS API MCP Server v2.1.0`);
+    console.error(`📡 API URL: ${API_URL}`);
+    console.error(`🔑 API Key: ${API_KEY ? "Configured" : "Not configured"}`);
+    console.error(`\nAvailable 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`);
+    console.error(`  - get_authentication_flow: Auth implementation guide`);
+    console.error(`  - get_common_patterns: Best practices and patterns`);
+    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`);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});