@genlobe/mcp-server 3.4.0 → 3.5.1

package/README.md

@@ -74,6 +74,7 @@ Edit `claude_desktop_config.json`:
 |---|---|---|
 | `SAAS_API_URL` | no | Defaults to `https://api-core.genlobe.ai`. Override only if you point at a local or on-prem backend. |
 | `SAAS_API_KEY` | optional | Your Genlobe API key. Accepts both `pk_live_*` (public) and `sk_live_*` (secret). Without it, only the offline documentation tools work — the four live tools (`validate_credentials`, `list_end_users`, `list_oauth_providers`, `get_openapi_spec`) need it. |
+| `SAAS_FRONTEND_URL` | no | Dashboard URL used by the redirect-URL tools (`get_stripe_config_url`, `get_agent_secrets_url`, `get_plan_management_url`). Resolution order: (1) this variable if set; (2) derived from `SAAS_API_URL` by swapping the leading `api.` / `api-core.` sub-domain for `app.`; (3) `https://app.genlobe.ai`. |
 
 `API_URL` and `API_KEY` (without the `SAAS_` prefix) are accepted as aliases for backward compatibility.
 
@@ -81,14 +82,15 @@ Edit `claude_desktop_config.json`:
 
 ## Tools
 
-14 tools, in three groups.
+18 tools, in four groups.
 
 ### Documentation (offline, no API key needed)
 
 | Tool | Returns |
 |---|---|
 | `get_api_overview` | High-level architecture, auth model, key concepts, recommended call order. **Start here.** |
-| `get_end_user_endpoints` | Reference for every end-user endpoint, filterable by category (`authentication`, `organizations`, `subscriptions`, `billing`, `usage`, `agents`, `users`, `plans`, `ai`, `entities`, `departments`, `files`, `external_agents`). |
+| `list_endpoint_categories` | Bare list of end-user endpoint categories plus a one-line summary of each. ~30 tokens. Call this once when you don't already know what's available; then use `get_end_user_endpoints({ category })` for the actual docs. |
+| `get_end_user_endpoints` | Reference for end-user endpoints in ONE category. Pass `category` (one of `authentication`, `organizations`, `subscriptions`, `billing`, `usage`, `agents`, `users`, `plans`, `ai`, `entities`, `departments`, `files`, `external_agents`). The `billing` category now also covers the Organization-admin read-only surface (`/v1/organization-admin/{org_id}/plans`, `/v1/organization-admin/{org_id}/config/stripe`, `/v1/organization-admin/{org_id}/audit`). Calling without a category returns the full catalog — use sparingly. |
 | `get_request_headers` | The exact HTTP headers required for end-user requests, with examples. |
 | `get_authentication_flow` | Step-by-step register → login → refresh → logout, including token storage and refresh-on-401 patterns. |
 | `get_common_patterns` | Pagination, error handling, optimistic updates, file upload, RAG queries, agent execution. |
@@ -96,6 +98,18 @@ Edit `claude_desktop_config.json`:
 | `search_endpoints` | Keyword search across path, summary, and description. |
 | `get_endpoint_details` | Full request/response schema for a specific `(method, path)`. |
 
+### Redirect-URL tools (no secrets ever returned by the MCP)
+
+These tools return a Dashboard URL the human developer should visit to set or rotate a secret. The MCP NEVER accepts or returns raw secret values; instead it points the agent at the right page so the human pastes the key in the browser. See the "MCP server invariants" section in the root `CLAUDE.md` for the pattern.
+
+All three return `{ url, reason, next_action: { type: "open_in_browser", url } }` and do no network calls — they are pure URL computation against the configured `SAAS_FRONTEND_URL`.
+
+| Tool | Returns |
+|---|---|
+| `get_stripe_config_url({ org_id })` | `${frontend_url}/org-admin/{org_id}/integrations/stripe` — page where the Organization Owner sets / rotates the org's Stripe `secret_key`, `publishable_key`, `webhook_secret`. Pair it with `GET /v1/organization-admin/{org_id}/config/stripe` (returned masked) to detect whether Stripe is already configured. |
+| `get_agent_secrets_url({ agent_id })` | `${frontend_url}/dashboard/agents/{agent_id}/secrets` — page where the Tenant rotates / sets an Agent's provider keys (OpenAI / Anthropic / etc.) and webhook secrets. |
+| `get_plan_management_url({ org_id })` | `${frontend_url}/org-admin/{org_id}/plans` — page where the Organization Owner creates / edits / deletes Plans. Write operations are not exposed via MCP because the plan-sync flow needs the encrypted Stripe `secret_key`. |
+
 ### Live (require `SAAS_API_KEY`)
 
 | Tool | Does |
@@ -122,12 +136,15 @@ Edit `claude_desktop_config.json`:
 3. recommend_stack            → pick a framework that won't leak the key
 4. get_api_overview           → understand the API at a high level
 5. get_authentication_flow    → wire up register / login / refresh
-6. get_end_user_endpoints     → see what's available for the feature you're building
-7. get_sdk_template           → start writing real code
+6. list_endpoint_categories   → see which endpoint categories exist
+7. get_end_user_endpoints     → drill into one category at a time
+8. get_sdk_template           → start writing real code
 ```
 
 For targeted questions ("how do I list organizations?"), `search_endpoints` + `get_endpoint_details` is faster than scrolling through `get_end_user_endpoints`.
 
+When the developer needs to set or rotate a secret (Stripe key, Agent provider key, webhook secret), call the matching `get_*_url` tool — the MCP returns a Dashboard URL the human visits to paste the key. Inline secret input through the MCP is not supported by design.
+
 ---
 
 ## Support

package/dist/index.js

@@ -36,6 +36,45 @@ const SERVER_VERSION = pkg.version;
 // a local backend in development.
 const API_URL = process.env.SAAS_API_URL || process.env.API_URL || "https://api-core.genlobe.ai";
 const API_KEY = process.env.SAAS_API_KEY || process.env.API_KEY || "";
+// Frontend URL used by the redirect-URL tools (get_stripe_config_url,
+// get_agent_secrets_url, get_plan_management_url). Resolution order:
+//   1. SAAS_FRONTEND_URL env var (e.g. https://app.genlobe.ai)
+//   2. Derive from SAAS_API_URL by swapping the leading "api." / "api-core."
+//      sub-domain for "app." — works for the public prod + staging
+//      environments out of the box.
+//   3. Default https://app.genlobe.ai.
+//
+// The MCP NEVER returns secret values to the agent; instead it returns
+// these URLs so the human developer can paste the secret in the Dashboard.
+// See "MCP server invariants" in the root CLAUDE.md.
+function resolveFrontendUrl() {
+    const explicit = process.env.SAAS_FRONTEND_URL;
+    if (explicit)
+        return explicit.replace(/\/+$/, "");
+    const derived = API_URL.replace(/^(https?:\/\/)(api-core\.|api\.)/, "$1app.");
+    if (derived !== API_URL)
+        return derived.replace(/\/+$/, "");
+    // Localhost API → keep the convention of port 3000/3001 for the dashboards
+    // by NOT pretending to know which one. Fall back to the documented default.
+    return "https://app.genlobe.ai";
+}
+const FRONTEND_URL = resolveFrontendUrl();
+// Canonical structured rejection payload for any future tool that might
+// receive secret-shaped input. The MCP NEVER accepts raw secrets inline —
+// the agent must follow `next_action.url` and the human pastes the secret
+// in the dashboard. Documented in the root CLAUDE.md "MCP server invariants".
+//
+// Not wired into any current tool (none of them accept secret-shaped input
+// today), but kept here so future maintainers have a single canonical
+// shape to reuse rather than re-invent.
+function rejectSecretInline(secretType, reason, redirectUrl) {
+    return {
+        error: "blocked_by_security_policy",
+        reason,
+        secret_type: secretType,
+        next_action: { type: "redirect", url: redirectUrl },
+    };
+}
 // Cache for API responses
 const cache = new Map();
 const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
@@ -163,7 +202,7 @@ const END_USER_ENDPOINTS = {
                 method: "POST",
                 path: "/v1/auth/register",
                 summary: "Register a new user",
-                auth: { api_key: "pk_live_* or sk_live_*", jwt: false },
+                auth: { api_key: "pk_live_* or sk_live_* (REQUIRED)", jwt: false, headers: "X-Organization-Id required when the API key is root-scoped (org_id NULL on the key). Ignored when the key is already scoped to a specific Organization — the key wins." },
                 rate_limit: "3 per hour per IP (blocked 30 min after exceeding)",
                 request_body: {
                     email: "string (required) - valid email",
@@ -829,7 +868,7 @@ const END_USER_ENDPOINTS = {
         ]
     },
     billing: {
-        description: "Billing operations. Two flavors:\n\n- **Tier 1 (legacy / platform-level)**: endpoints under /v1/billing/* use the platform's Stripe and a SECRET key (sk_live_*) only. They were originally for Genlobe → Tenant billing and a since-superseded Tier 2 prototype; keep using them for tenant-internal flows.\n\n- **Tier 3 (Organization → end-user, Epic #209)**: each Organization runs its OWN Stripe (BYO key). End-users subscribe via /v1/organizations/{org_id}/billing/* (api key + JWT + active OrganizationMember). The Org's plan catalog is read via the public /v1/organizations/{org_id}/plans (api key only — no JWT). See the master spec at specs/features/billing/three-tier-billing.spec.md.",
+        description: "Billing operations. Three flavors:\n\n- **Tier 1 (legacy / platform-level)**: endpoints under /v1/billing/* use the platform's Stripe and a SECRET key (sk_live_*) only. They were originally for Genlobe → Tenant billing and a since-superseded Tier 2 prototype; keep using them for tenant-internal flows.\n\n- **Tier 3 — end-user surface (Epic #209)**: each Organization runs its OWN Stripe (BYO key). End-users subscribe via /v1/organizations/{org_id}/billing/* (api key + JWT + active OrganizationMember). The Org's plan catalog is read via the public /v1/organizations/{org_id}/plans (api key only — no JWT). See the master spec at specs/features/billing/three-tier-billing.spec.md.\n\n- **Tier 3 — Organization-admin surface (Phase 1, this MCP)**: /v1/organization-admin/{org_id}/* — read-only inspection of plans, masked Stripe config, and billing audit log. Auth: end-user JWT + `require_org_admin` (role IN owner/admin). Secret-setting paths (POST/PATCH/DELETE on config/stripe, plan CRUD) are NOT exposed via MCP — use the `get_stripe_config_url({ org_id })` / `get_plan_management_url({ org_id })` tools so the human pastes secrets in the Dashboard.",
         endpoints: [
             {
                 method: "GET",
@@ -1007,6 +1046,81 @@ const END_USER_ENDPOINTS = {
                     "403": "Caller is not an active OrganizationMember of the path's org.",
                     "404": "Caller has no Subscription for this Organization yet."
                 }
+            },
+            // ---------------------------------------------------------------
+            // Organization-admin read-only endpoints (BILL-4 / BILL-9, Epic
+            // #209). Auth: end-user JWT + `require_org_admin` (the caller must
+            // be an OrganizationMember of the path's org with role IN ('owner',
+            // 'admin')). These are the surfaces an Org Owner uses to inspect
+            // billing state from the MCP without touching any secret. The
+            // secret-setting paths (POST/PATCH/DELETE on config/stripe + plan
+            // CRUD that needs a Stripe key) are intentionally NOT exposed here
+            // — they go through the redirect-URL tools (`get_stripe_config_url`,
+            // `get_plan_management_url`) so the human pastes the secret in the
+            // Dashboard. See "MCP server invariants" in the root CLAUDE.md.
+            // ---------------------------------------------------------------
+            {
+                method: "GET",
+                path: "/v1/organization-admin/{organization_id}/plans",
+                summary: "List the Organization's plans (admin view — includes inactive / un-synced plans)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true, require_org_admin: true },
+                response: {
+                    items: "array of OrganizationPlan (see GET /v1/organizations/{organization_id}/plans for the field list — same shape). Unlike the public endpoint this one also returns plans with is_active=false and plans that don't have a stripe_price_id yet.",
+                    total: "number"
+                },
+                errors: {
+                    "403": "Caller is not an OrganizationMember with role owner/admin of the path's org (rejects TenantMember JWT)."
+                },
+                note: "The admin variant of GET /v1/organizations/{organization_id}/plans. Use this when an Org Owner needs to see every plan they have, including drafts. No secret material is returned."
+            },
+            {
+                method: "GET",
+                path: "/v1/organization-admin/{organization_id}/plans/{plan_id}",
+                summary: "Read one plan (admin view)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true, require_org_admin: true },
+                response: "OrganizationPlan (full shape — id, organization_id, name, slug, description, price_amount, currency, billing_interval, features, limits, stripe_product_id, stripe_price_id, stripe_price_id_yearly, is_active, created_at, updated_at).",
+                errors: {
+                    "403": "Caller is not an OrganizationMember with role owner/admin of the path's org.",
+                    "404": "Plan not found OR plan.organization_id != path organization_id (collapsed to 404 to avoid cross-org existence leaks)."
+                }
+            },
+            {
+                method: "GET",
+                path: "/v1/organization-admin/{organization_id}/config/stripe",
+                summary: "Read the Organization's MASKED Stripe config status (no secrets returned)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true, require_org_admin: true },
+                response: {
+                    organization_id: "uuid",
+                    publishable_key: "string | null — Stripe publishable key (pk_live_* / pk_test_*), safe to expose.",
+                    secret_key_display: "string | null — masked tail of the secret key, e.g. 'sk_live_****Pnxs'. Display-only — the actual key is never returned.",
+                    has_webhook_secret: "boolean — true if a webhook_secret is persisted.",
+                    is_active: "boolean — true once secret_key + webhook_secret are both present."
+                },
+                note: "Use this to detect whether the Org has Stripe configured before sending users into a checkout flow that would 409. To SET or ROTATE the Stripe credentials, call the MCP tool `get_stripe_config_url({ org_id })` and have the human paste the keys in the Dashboard — the MCP does NOT accept raw secrets inline.",
+                errors: {
+                    "403": "Caller is not an OrganizationMember with role owner/admin of the path's org."
+                }
+            },
+            {
+                method: "GET",
+                path: "/v1/organization-admin/{organization_id}/audit",
+                summary: "Paginated billing audit log for the Organization",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true, require_org_admin: true },
+                query_params: {
+                    limit: "integer (default 100, 1 ≤ limit ≤ 500)",
+                    offset: "integer (default 0, ≥ 0)",
+                    action_prefix: "string (optional) — filter by action prefix, e.g. 'config.stripe' or 'webhook.security'."
+                },
+                response: {
+                    items: "array of BillingAuditLogEntry: { id (uuid), organization_id (uuid), actor_user_id (uuid | null), actor_role (string), action (string, e.g. 'config.stripe.set'), target_type (string | null), target_id (string | null), before_json (any | null), after_json (any | null), note (string | null), created_at (ISO datetime) }. Reverse-chronological.",
+                    total: "number",
+                    limit: "integer (echo)",
+                    offset: "integer (echo)"
+                },
+                note: "Audit entries are pre-masked at write time — `before_json` / `after_json` for config.stripe.* contain `secret_key_display` ('sk_live_****Pnxs'), never the raw key.",
+                errors: {
+                    "403": "Caller is not an OrganizationMember with role owner/admin of the path's org."
+                }
             }
         ]
     },
@@ -1660,12 +1774,24 @@ const END_USER_ENDPOINTS = {
                 method: "POST",
                 path: "/v1/entity/records",
                 summary: "Create a new entity record",
-                auth: { api_key: "sk_live_* or pk_live_*", jwt: false, headers: "X-Organization-Id required when key is not organization-scoped" },
+                auth: { api_key: "sk_live_* or pk_live_*", jwt: "optional (required for pk_live_*)", headers: "X-Organization-Id required when key is not organization-scoped" },
                 request_body: {
                     schema_id: "uuid (required)",
                     data: "object (required) - validated against schema fields_definition"
                 },
-                notes: "Two modes: (1) sk_live_* without JWT -> tenant-scoped record, created_by_id is NULL (e.g. catalog/blog/global config). (2) API key + end-user JWT -> user-scoped record, created_by_id = user.id. The endpoint accepts both shapes; ownership is determined by whether a JWT is present."
+                notes: "Three modes (#178 + #350): (1) sk_live_* alone -> tenant-scoped record, created_by_id is NULL (catalog/blog/global config). (2) sk_live_* + end-user JWT -> user-scoped record, created_by_id = user.id (server-side caller acting on behalf of a user). (3) pk_live_* + end-user JWT -> user-scoped record, created_by_id = user.id (canonical 'two-phase' frontend pattern: pk in the browser, JWT after login). pk_live_* WITHOUT a JWT is rejected with 401 — a public key alone is anonymous and can't be the creator of a record."
+            },
+            {
+                method: "GET",
+                path: "/v1/entity/records/mine",
+                summary: "List records authored by the current end-user (\"my data\")",
+                auth: { api_key: "sk_live_* or pk_live_*", jwt: true, headers: "X-Organization-Id required when key is not organization-scoped" },
+                query_params: {
+                    schema_id: "uuid (required) - schema whose records to list",
+                    page: "number (default 1)",
+                    size: "number (default 20, max 100)"
+                },
+                notes: "Returns ONLY records where created_by_id = current_user.id, regardless of the user's role inside the Org (members and elevated roles alike). Natural path for end-user 'my data' queries (my chats, my orders, my notes). Use this instead of POST /v1/entity/records/search with manual created_by_id filters — the row-level scope (ADR-0007) is enforced server-side, frontend MUST NOT be the filter. Requires an end-user JWT; tenant-scoped (sk_live_* alone) callers get 401 — they should use POST /v1/entity/records/search."
             },
             {
                 method: "GET",
@@ -3091,25 +3217,91 @@ Call this first to understand the API architecture and authentication model.`,
             },
             {
                 name: "get_end_user_endpoints",
-                description: `Get detailed documentation for END-USER API endpoints.
+                description: `Get detailed documentation for END-USER API endpoints, filtered to ONE category.
 
 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`,
+PREFER passing a single category. The output is focused on that category + a
+one-line pointer to the others. Calling without a category dumps the entire
+catalog (every endpoint of every category) and is rarely what you want — it
+burns context quickly.
+
+If you don't know which categories exist yet, call list_endpoint_categories()
+first.
+
+Categories: authentication, organizations, subscriptions, billing (includes Tier-3 admin read-only endpoints), usage, agents, users, plans, ai, entities, departments, files, external_agents.
+
+The 'billing' category now covers both the end-user surface
+(/v1/organizations/{org_id}/billing/*) and the Organization-admin read-only
+surface (/v1/organization-admin/{org_id}/{plans, config/stripe, audit}).
+Secret-setting paths (config/stripe POST/PATCH/DELETE, plan CRUD that needs
+the Stripe key) go through get_stripe_config_url / get_plan_management_url —
+the MCP never accepts raw secrets inline.`,
                 inputSchema: {
                     type: "object",
                     properties: {
                         category: {
                             type: "string",
-                            description: "Filter by category. Leave empty for all endpoints.",
+                            description: "Filter by category (strongly recommended). Leave empty only when you explicitly want the full catalog.",
                             enum: ["authentication", "organizations", "subscriptions", "billing", "usage", "agents", "users", "plans", "ai", "entities", "departments", "files", "external_agents"],
                         },
                     },
                     required: [],
                 },
             },
+            {
+                name: "list_endpoint_categories",
+                description: `Return the bare list of available end-user endpoint categories plus a one-line summary of each. Cheap call (~30 tokens). Use this once if you don't already know what's available; then call get_end_user_endpoints({ category }) for the actual endpoint docs of the category you care about. This replaces the old per-call "Quick Reference" dump that get_end_user_endpoints used to print at the bottom of every response.`,
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                    required: [],
+                },
+            },
+            {
+                name: "get_stripe_config_url",
+                description: `Return the Dashboard URL where the Organization Owner sets or rotates the Organization's Stripe credentials (secret_key, publishable_key, webhook_secret). The MCP NEVER accepts raw secrets through tool input — this redirect URL is the canonical way to set them. Pure URL computation; no network call. Pair it with GET /v1/organization-admin/{org_id}/config/stripe to detect whether the Organization has Stripe configured already.`,
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        org_id: {
+                            type: "string",
+                            description: "The Organization id (UUID) whose Stripe config the owner wants to manage.",
+                        },
+                    },
+                    required: ["org_id"],
+                },
+            },
+            {
+                name: "get_agent_secrets_url",
+                description: `Return the Dashboard URL where the Tenant rotates / sets an Agent's provider keys (OpenAI / Anthropic / etc.) and webhook secrets. The MCP NEVER accepts raw secrets through tool input — this redirect URL is the canonical way to set them. Pure URL computation; no network call.`,
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        agent_id: {
+                            type: "string",
+                            description: "The Agent id (UUID) whose secrets the developer wants to manage.",
+                        },
+                    },
+                    required: ["agent_id"],
+                },
+            },
+            {
+                name: "get_plan_management_url",
+                description: `Return the Dashboard URL where the Organization Owner creates / edits / deletes Plans (Tier-3, BYO-Stripe). Write operations are NOT exposed via MCP because plan sync needs the Organization's Stripe secret_key; the MCP only exposes the read paths (GET /v1/organization-admin/{org_id}/plans, GET /v1/organization-admin/{org_id}/plans/{plan_id}) for inspection. Pure URL computation; no network call.`,
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        org_id: {
+                            type: "string",
+                            description: "The Organization id (UUID) whose plan catalog the owner wants to manage.",
+                        },
+                    },
+                    required: ["org_id"],
+                },
+            },
             {
                 name: "get_request_headers",
                 description: "Get detailed information about required HTTP headers for API requests.",
@@ -3327,125 +3519,130 @@ Skipping these is how secret keys end up shipped to a browser bundle. Don't skip
                 };
             }
             case "get_end_user_endpoints": {
+                // Phase-1 P0 (#347): focused output. Return ONLY the requested category
+                // plus a one-line pointer to the other categories. The previous
+                // implementation dumped a global Quick Reference of every category
+                // at the bottom of every per-category call — that burned thousands
+                // of tokens of agent context for no benefit (see CHANGELOG 3.5.0).
                 const category = args.category;
-                let endpoints = END_USER_ENDPOINTS;
+                const allCategories = Object.keys(END_USER_ENDPOINTS);
                 if (category && category in END_USER_ENDPOINTS) {
-                    endpoints = { [category]: END_USER_ENDPOINTS[category] };
+                    const focused = { [category]: END_USER_ENDPOINTS[category] };
+                    const otherCategories = allCategories.filter((c) => c !== category);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `# End-User API Endpoints — ${category}
+
+These endpoints are for building frontend applications for end-users.
+
+${JSON.stringify(focused, null, 2)}
+
+---
+For other categories, call get_end_user_endpoints again with category=${otherCategories.join(" | ")}.
+Use list_endpoint_categories() if you just want the bare list of available categories.`,
+                            },
+                        ],
+                    };
                 }
+                // No category filter → return everything. This is the explicit
+                // "give me the whole catalog" path; the focused path above is
+                // what the agent should use on every other call.
                 return {
                     content: [
                         {
                             type: "text",
-                            text: `# End-User API Endpoints${category ? ` - ${category}` : ''}
+                            text: `# End-User API Endpoints — ALL categories
 
 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`,
+${JSON.stringify(END_USER_ENDPOINTS, null, 2)}
+
+---
+Tip: subsequent calls should pass a single category (one of: ${allCategories.join(", ")}) so the output stays focused on what the agent is working on.`,
+                        },
+                    ],
+                };
+            }
+            case "list_endpoint_categories": {
+                // Lightweight helper (#347): give the agent just the category names
+                // so it can target subsequent get_end_user_endpoints calls without
+                // having to first download the whole catalog. ~30 tokens.
+                const categories = Object.keys(END_USER_ENDPOINTS);
+                const summaries = {};
+                for (const c of categories) {
+                    const data = END_USER_ENDPOINTS[c];
+                    summaries[c] = (data && typeof data.description === "string")
+                        ? data.description.split("\n")[0]
+                        : "";
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `# End-User Endpoint Categories
+
+${categories.length} categories available. Call get_end_user_endpoints({ category }) with one of them.
+
+${JSON.stringify({ categories, summaries }, null, 2)}`,
+                        },
+                    ],
+                };
+            }
+            case "get_stripe_config_url": {
+                const orgId = args.org_id;
+                if (!orgId) {
+                    throw new Error("get_stripe_config_url requires org_id");
+                }
+                const url = `${FRONTEND_URL}/org-admin/${encodeURIComponent(orgId)}/integrations/stripe`;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                url,
+                                reason: "Stripe secrets (secret_key, webhook_secret) must be set via the Organization Owner Dashboard, not inline through the MCP. The human developer pastes the keys; the MCP NEVER accepts or returns secret material.",
+                                next_action: { type: "open_in_browser", url },
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "get_agent_secrets_url": {
+                const agentId = args.agent_id;
+                if (!agentId) {
+                    throw new Error("get_agent_secrets_url requires agent_id");
+                }
+                const url = `${FRONTEND_URL}/dashboard/agents/${encodeURIComponent(agentId)}/secrets`;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                url,
+                                reason: "Agent provider keys (OpenAI / Anthropic / etc.) and webhook secrets must be set or rotated via the Tenant Dashboard, not inline through the MCP. The human developer pastes the keys; the MCP NEVER accepts or returns secret material.",
+                                next_action: { type: "open_in_browser", url },
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "get_plan_management_url": {
+                const orgId = args.org_id;
+                if (!orgId) {
+                    throw new Error("get_plan_management_url requires org_id");
+                }
+                const url = `${FRONTEND_URL}/org-admin/${encodeURIComponent(orgId)}/plans`;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                url,
+                                reason: "Plan create / update / delete (and the Stripe-product sync they trigger) needs the Organization's Stripe secret_key, which lives encrypted in OrganizationConfig and is never exposed to the agent. Use the Dashboard for write operations; the MCP exposes the read paths (GET /v1/organization-admin/{org_id}/plans, GET /v1/organization-admin/{org_id}/plans/{plan_id}) for inspection.",
+                                next_action: { type: "open_in_browser", url },
+                            }, null, 2),
                         },
                     ],
                 };
@@ -4319,6 +4516,7 @@ type to pick.`,
 async function main() {
     console.error(`🚀 Multi-tenant SaaS API MCP Server v${SERVER_VERSION}`);
     console.error(`📡 API URL: ${API_URL}`);
+    console.error(`🖥  Frontend URL (for redirect-URL tools): ${FRONTEND_URL}`);
     console.error(`🔑 API Key: ${API_KEY ? "Configured" : "Not configured (set SAAS_API_KEY to enable authenticated calls)"}`);
     console.error(`\n👉 Recommended first calls (vibecoding flow):`);
     console.error(`  1. validate_credentials  — verify key + detect type (pk_live_* vs sk_live_*)`);
@@ -4326,13 +4524,18 @@ async function main() {
     console.error(`  3. recommend_stack       — pick a framework that won't leak your key`);
     console.error(`\nReference tools:`);
     console.error(`  - get_api_overview: Understand the API architecture`);
-    console.error(`  - get_end_user_endpoints: Get endpoint documentation`);
+    console.error(`  - list_endpoint_categories: List endpoint categories (cheap)`);
+    console.error(`  - get_end_user_endpoints: Get endpoint documentation (one category at a time)`);
     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`);
+    console.error(`\nRedirect-URL tools (no secrets ever returned by the MCP):`);
+    console.error(`  - get_stripe_config_url   — Dashboard URL to set/rotate the Org's Stripe keys`);
+    console.error(`  - get_agent_secrets_url   — Dashboard URL to rotate an Agent's secrets`);
+    console.error(`  - get_plan_management_url — Dashboard URL to create/edit Plans`);
     console.error(`\nAuthenticated helpers:`);
     console.error(`  - list_end_users         (sk_live_* required)`);
     console.error(`  - list_oauth_providers   (any key)`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genlobe/mcp-server",
-  "version": "3.4.0",
+  "version": "3.5.1",
   "description": "MCP Server for GenLobe SaaS API - Provides AI assistants with comprehensive API documentation for building frontend applications",
   "main": "dist/index.js",
   "bin": {