@genlobe/mcp-server 3.5.1 → 3.6.1

package/README.md

@@ -82,7 +82,7 @@ Edit `claude_desktop_config.json`:
 
 ## Tools
 
-18 tools, in four groups.
+19 tools, in four groups.
 
 ### Documentation (offline, no API key needed)
 
@@ -90,7 +90,8 @@ Edit `claude_desktop_config.json`:
 |---|---|
 | `get_api_overview` | High-level architecture, auth model, key concepts, recommended call order. **Start here.** |
 | `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_end_user_endpoints` | Reference for end-user endpoints in ONE category. Pass `category` (one of `authentication`, `organizations`, `subscriptions`, `billing`, `organization_admin`, `usage`, `agents`, `users`, `plans`, `ai`, `entities`, `departments`, `files`, `external_agents`). The `billing` category covers Tier-3 admin read-only billing endpoints (`/v1/organization-admin/{org_id}/{plans, config/stripe, audit, subscriptions}`); the new `organization_admin` category covers the non-billing Org Owner Dashboard surfaces (members, customers, agents, knowledge bases, agent-change notifications, Stripe webhook audit). Calling without a category returns the full catalog — use sparingly. |
+| `get_reserved_schema_slugs` | Returns the 53 slugs the Custom Entities subsystem refuses at `POST /v1/entity/schemas` (ADR-0011 — they collide with native DB tables: `users`, `conversations`, `agents`, …). Pure data, no network call. Use it to pre-validate before issuing the POST and avoid a `400` round-trip. |
 | `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. |

package/dist/index.js

@@ -192,6 +192,82 @@ The \`sk_live_*\` key never reaches the browser. It lives only on the tenant's o
     }
 };
 // =============================================================================
+// Reserved schema slugs (ADR-0011)
+// =============================================================================
+//
+// Mirrors `RESERVED_SCHEMA_SLUGS` in
+// `src/tenants/services/custom_data_schema_service.py`. The backend is the
+// authoritative source — this list is documentation-only and is exposed
+// through the `get_reserved_schema_slugs` tool so agents can pre-validate
+// before POSTing to /v1/entity/schemas.
+//
+// When the backend list changes (a new native __tablename__ is added),
+// this constant MUST be updated in the same MCP PR.
+const RESERVED_SCHEMA_SLUGS = Object.freeze([
+    // --- Alembic / Postgres internals -------------------------------------
+    "alembic_version",
+    // --- Tenants domain ---------------------------------------------------
+    "tenants",
+    "tenant_members",
+    "tenant_configs",
+    "tenant_password_reset_tokens",
+    "api_keys",
+    "email_logs",
+    "email_domains",
+    "email_verification_codes",
+    "custom_data_schemas",
+    "custom_data_records",
+    // --- Organizations domain --------------------------------------------
+    "organizations",
+    "organization_members",
+    "organization_configs",
+    "organization_invitations",
+    "departments",
+    "permissions",
+    "role_permissions",
+    // --- Users / Auth -----------------------------------------------------
+    "users",
+    "user_settings",
+    "password_reset_tokens",
+    // --- Subscriptions / Billing -----------------------------------------
+    "plans",
+    "tenant_plans",
+    "organization_plans",
+    "subscriptions",
+    "tenant_subscriptions",
+    "tenant_usages",
+    "tenant_usage_details",
+    "organization_usage_details",
+    "plan_usages",
+    "usage_logs",
+    "billing_audit_log",
+    "billing_meters",
+    "processed_stripe_events",
+    // --- AI domain --------------------------------------------------------
+    "agents",
+    "agent_executions",
+    "agent_tools",
+    "tool_executions",
+    "tool_secrets",
+    "external_agents",
+    "external_agent_calls",
+    "conversations",
+    "conversation_messages",
+    "knowledge_bases",
+    "documents",
+    "document_chunks",
+    // --- Files / Drive ---------------------------------------------------
+    "tenant_files",
+    "user_files",
+    "folders",
+    // --- Workflows (no Python model; defined only in migration) ---------
+    "workflows",
+    "workflow_executions",
+    "node_executions",
+    // --- Admin domain ----------------------------------------------------
+    "admin_audit_logs",
+]);
+// =============================================================================
 // End-User Endpoints (for building frontends)
 // =============================================================================
 const END_USER_ENDPOINTS = {
@@ -223,7 +299,8 @@ const END_USER_ENDPOINTS = {
                         display_name: "string | null",
                         avatar_url: "string | null",
                         is_active: "boolean",
-                        created_at: "ISO datetime"
+                        created_at: "ISO datetime",
+                        profile_data: "object — Tenant-defined free-form metadata for this user. Defaults to {} when empty (never null). Mutate via PATCH /v1/users/me/profile-data. ADR-0010."
                     }
                 },
                 response_when_verification_required: {
@@ -275,7 +352,8 @@ const END_USER_ENDPOINTS = {
                     display_name: "string | null",
                     avatar_url: "string | null",
                     is_active: "boolean",
-                    created_at: "ISO datetime"
+                    created_at: "ISO datetime",
+                    profile_data: "object — Tenant-defined free-form metadata. Defaults to {} when empty (never null). ADR-0010."
                 }
             },
             {
@@ -1101,29 +1179,217 @@ const END_USER_ENDPOINTS = {
                     "403": "Caller is not an OrganizationMember with role owner/admin of the path's org."
                 }
             },
+            // ---------------------------------------------------------------
+            // Org-admin Subscription list (Tier-3, end-user subscriptions view).
+            // Distinct from the END-USER read at GET /v1/organizations/{id}/billing/subscription
+            // (which returns ONLY the caller's own subscription). This one is
+            // the dashboard's "list of paying customers" surface.
+            // ---------------------------------------------------------------
             {
                 method: "GET",
-                path: "/v1/organization-admin/{organization_id}/audit",
-                summary: "Paginated billing audit log for the Organization",
+                path: "/v1/organization-admin/{organization_id}/subscriptions",
+                summary: "List end-user subscriptions for the Organization (admin)",
                 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'."
+                    status: "string (optional) — comma-separated subscription statuses to filter (e.g. 'active,trialing,past_due'). Omit for all."
                 },
                 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)"
+                    items: "array of SubscriptionResponse — every Subscription row scoped to this Organization, sorted newest-first.",
+                    total: "number"
                 },
-                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.",
+                note: "Active statuses for the 'paying customers' count are: active, trialing, past_due. canceled / incomplete_expired / stripe_disconnected do NOT count as active.",
                 errors: {
                     "403": "Caller is not an OrganizationMember with role owner/admin of the path's org."
                 }
             }
         ]
     },
+    organization_admin: {
+        description: "Organization Owner / Admin surface that an agent uses while BUILDING the Tenant's product — team management (`members`), AI resource management (`agents` visibility, `knowledge-bases` + `documents` CRUD). Excludes observability endpoints (audit log, webhook delivery history, admin notifications, customer CRM list) — those live in the dashboards for humans, not in the MCP. Auth pattern across all of these: pk_live_*/sk_live_* + end-user JWT + `require_org_admin` (OrganizationMember.role IN owner/admin). For billing-specific admin endpoints (Tier-3 plans, Stripe config status) see the `billing` category. Secret-setting paths go through redirect-URL tools (`get_stripe_config_url`, `get_plan_management_url`, `get_agent_secrets_url`).",
+        endpoints: [
+            {
+                method: "GET",
+                path: "/v1/organization-admin/{organization_id}/members",
+                summary: "List active members of the Organization (admin view)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true, require_org_admin: true },
+                response: {
+                    items: "array of OrganizationMemberResponse: { user_id (uuid), email (string), display_name (string | null), avatar_url (string | null), role ('owner'|'admin'|'member'|'developer'), is_active (boolean), joined_at (ISO datetime) }",
+                    total: "number"
+                },
+                note: "Subset of /v1/organizations/{org_id}/members but enforces require_org_admin (rejects TenantMember JWT). Use this when building the Org Owner dashboard's Members page.",
+                errors: {
+                    "403": "Caller is not an OrganizationMember with role owner/admin of the path's org."
+                }
+            },
+            {
+                method: "PATCH",
+                path: "/v1/organization-admin/{organization_id}/members/{member_user_id}/role",
+                summary: "Update a member's role within the Organization",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true, require_org_admin: true },
+                request_body: {
+                    role: "string (required) — one of 'owner', 'admin', 'member', 'developer'."
+                },
+                response: "OrganizationMemberResponse — the updated member row.",
+                notes: "Service-level guards: only owners can promote to owner; admins cannot touch owners; the last active owner cannot be demoted (returns 400).",
+                errors: {
+                    "400": "Last-owner demotion guard / target not a member.",
+                    "403": "Insufficient role for the requested transition (e.g. admin trying to touch an owner).",
+                    "404": "Member not found in this organization."
+                }
+            },
+            {
+                method: "DELETE",
+                path: "/v1/organization-admin/{organization_id}/members/{member_user_id}",
+                summary: "Remove a member from the Organization",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true, require_org_admin: true },
+                response: "204 No Content",
+                notes: "Service-level guards: only owners can remove other owners; the last active owner cannot be removed.",
+                errors: {
+                    "400": "Last-owner removal guard.",
+                    "403": "Insufficient role for removal (e.g. admin trying to remove an owner).",
+                    "404": "Member not found in this organization."
+                }
+            },
+            {
+                method: "GET",
+                path: "/v1/organization-admin/{organization_id}/agents",
+                summary: "List agents visible to the Organization (Hybrid Catalog — ADR-0006 v2)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true, require_org_admin: true },
+                query_params: {
+                    include_catalog: "boolean (default true) — when true, includes public agents from the Tenant's root Organization (the catalog). When false, returns only agents owned by this Organization.",
+                    skip: "integer (default 0, ≥ 0)",
+                    limit: "integer (default 100, 1 ≤ limit ≤ 200)"
+                },
+                response: {
+                    items: "array of AgentResponse: { id, tenant_id, organization_id, is_public, forked_from_agent_id, name, description, system_prompt, response_type, rag_provider, rag_role, is_active, rag_config, mcp_servers, created_by, created_at, updated_at }",
+                    total: "number"
+                },
+                note: "Visibility rules (ADR-0006 v2 Hybrid Catalog): agents where organization_id == this Org UNION (if include_catalog=true) agents where is_public=true AND organization_id is the Tenant's root Organization. To customize a catalog agent, the Org forks it via POST /v1/agents/{id}/fork (Tenant Dashboard endpoint — not exposed to end-users in the MCP).",
+                errors: {
+                    "403": "Caller is not an OrganizationMember with role owner/admin of the path's org."
+                }
+            },
+            // ---------------------------------------------------------------
+            // Knowledge Base management (per-Org, ADR-0006 v2 §rag_role).
+            // Org-scoped CRUD on KnowledgeBase + Document. Replaces the legacy
+            // single-store rag_config.store_id path (closes cross-org RAG leak G5).
+            // ---------------------------------------------------------------
+            {
+                method: "POST",
+                path: "/v1/organization-admin/{organization_id}/knowledge-bases",
+                summary: "Create a KnowledgeBase in the caller's Organization",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true, require_org_admin: true },
+                request_body: {
+                    name: "string (optional, max 200)",
+                    description: "string (optional)",
+                    role_tag: "string (optional, max 100) — Declarative tag matched against Agent.rag_role at runtime. When an Agent is invoked, the runtime looks up a KB in the caller's Org with role_tag == agent.rag_role and uses its vector store.",
+                    vector_store_config: "object (optional) — provider-specific vector-store settings (e.g. OpenAI File Search store id).",
+                    embedding_config: "object (optional) — provider-specific embedding settings."
+                },
+                response: {
+                    id: "uuid",
+                    organization_id: "uuid",
+                    name: "string | null",
+                    description: "string | null",
+                    role_tag: "string | null",
+                    is_active: "boolean",
+                    is_processing: "boolean"
+                },
+                notes: "KBs are per-Organization (KnowledgeBase.organization_id REQUIRED). Agents bind to per-Org KBs via the `rag_role` tag — the Agent declares `rag_role='support'` and the runtime finds the calling Org's KB with `role_tag='support'`. Multiple Orgs can have a KB with the same `role_tag`; each Org sees only its own."
+            },
+            {
+                method: "GET",
+                path: "/v1/organization-admin/{organization_id}/knowledge-bases",
+                summary: "List KnowledgeBases in the caller's Organization",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true, require_org_admin: true },
+                query_params: {
+                    include_inactive: "boolean (default false)",
+                    skip: "integer (default 0, ≥ 0)",
+                    limit: "integer (default 100, 1 ≤ limit ≤ 200)"
+                },
+                response: "Array of KnowledgeBaseResponse (same shape as POST response)."
+            },
+            {
+                method: "GET",
+                path: "/v1/organization-admin/{organization_id}/knowledge-bases/{kb_id}",
+                summary: "Get a KnowledgeBase by ID",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true, require_org_admin: true },
+                response: "KnowledgeBaseResponse",
+                errors: {
+                    "404": "KB not found OR kb.organization_id != path organization_id."
+                }
+            },
+            {
+                method: "PATCH",
+                path: "/v1/organization-admin/{organization_id}/knowledge-bases/{kb_id}",
+                summary: "Update a KnowledgeBase (partial)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true, require_org_admin: true },
+                request_body: {
+                    name: "string (optional)",
+                    description: "string (optional)",
+                    role_tag: "string (optional)",
+                    vector_store_config: "object (optional)",
+                    embedding_config: "object (optional)",
+                    is_active: "boolean (optional)"
+                },
+                response: "KnowledgeBaseResponse"
+            },
+            {
+                method: "DELETE",
+                path: "/v1/organization-admin/{organization_id}/knowledge-bases/{kb_id}",
+                summary: "Soft delete a KnowledgeBase (is_active=false). Documents survive for audit.",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true, require_org_admin: true },
+                response: "204 No Content"
+            },
+            {
+                method: "POST",
+                path: "/v1/organization-admin/{organization_id}/knowledge-bases/{kb_id}/documents",
+                summary: "Upload a document to a KnowledgeBase",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true, require_org_admin: true },
+                request_body: "multipart/form-data with `file` (single file). File size hard cap: 100MB (413 if exceeded).",
+                response: {
+                    id: "integer",
+                    knowledge_base_id: "uuid",
+                    organization_id: "uuid",
+                    filename: "string",
+                    file_size: "integer (bytes)",
+                    content_type: "string",
+                    status: "string — UPLOADED initially; worker layer transitions to PROCESSING/READY/FAILED.",
+                    error_message: "string | null"
+                },
+                notes: "The controller only records metadata; the worker layer consumes Document rows with status=UPLOADED and pushes to the storage provider. Cross-Org uploads (kb.organization_id != caller's Org) return 404, never 403.",
+                errors: {
+                    "400": "Empty file or missing filename.",
+                    "413": "File size exceeds 100MB."
+                }
+            },
+            {
+                method: "GET",
+                path: "/v1/organization-admin/{organization_id}/knowledge-bases/{kb_id}/documents",
+                summary: "List documents in a KnowledgeBase",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true, require_org_admin: true },
+                query_params: {
+                    skip: "integer (default 0, ≥ 0)",
+                    limit: "integer (default 100, 1 ≤ limit ≤ 200)"
+                },
+                response: "Array of DocumentResponse."
+            },
+            {
+                method: "GET",
+                path: "/v1/organization-admin/{organization_id}/knowledge-bases/{kb_id}/documents/{document_id}",
+                summary: "Get a document by ID",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true, require_org_admin: true },
+                response: "DocumentResponse"
+            },
+            {
+                method: "DELETE",
+                path: "/v1/organization-admin/{organization_id}/knowledge-bases/{kb_id}/documents/{document_id}",
+                summary: "Delete a document from a KnowledgeBase",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true, require_org_admin: true },
+                response: "204 No Content"
+            }
+        ]
+    },
     usage: {
         description: "Usage tracking and limits. Endpoints map to /v1/api/usage/* (current/history) and /v1/usage/* (stats/check/consume).",
         endpoints: [
@@ -1467,8 +1733,26 @@ const END_USER_ENDPOINTS = {
         ]
     },
     users: {
-        description: "User management - CRUD, settings, activation/deactivation. Dual auth: sk_live_* for admin ops, pk_live_* + JWT for self-service.",
+        description: "User management - CRUD, settings, activation/deactivation, and Tenant-defined `profile_data` extensions (ADR-0010). Dual auth: sk_live_* for admin ops, pk_live_* + JWT for self-service.",
         endpoints: [
+            {
+                method: "PATCH",
+                path: "/v1/users/me/profile-data",
+                summary: "Merge keys into the authenticated user's profile_data (ADR-0010)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: {
+                    profile_data: "object (required) — Top-level keys to merge into the existing profile_data JSONB. Keys present here overwrite same-named keys; keys absent are preserved. To clear a key, send it with value `null`. To clear the whole document, a future DELETE endpoint will be added (not implemented yet)."
+                },
+                response: "UserResponse — the updated row, including the merged profile_data. Same shape as GET /v1/users/{user_id}.",
+                notes: "Merge semantics, NOT replace. The target user_id is taken from the decoded JWT — there is no body/path parameter that can redirect the write, so a user can ONLY edit their own profile_data. There is no admin-override path on this endpoint by design (use PUT /v1/users/{user_id} with sk_live_* if a Tenant admin needs to mutate someone else's row; that endpoint does NOT touch profile_data today). The platform does NOT validate against any schema — the Tenant owns the shape end-to-end. PII warning: do NOT store unencrypted PII (passwords, SSNs, card numbers); the column is plaintext at rest and ships on every /me call. Tenants needing per-Org-scoped or schema-validated user metadata can layer a custom entity (e.g. `user_profiles`) on top.",
+                example_request: `{
+  "profile_data": {
+    "phone": "+1-555-0123",
+    "preferences": { "theme": "dark", "lang": "en" },
+    "premium_tier": "gold"
+  }
+}`
+            },
             {
                 method: "POST",
                 path: "/v1/users",
@@ -1498,6 +1782,7 @@ const END_USER_ENDPOINTS = {
                     status: "string",
                     current_plan_id: "uuid | null",
                     default_organization_id: "uuid | null",
+                    profile_data: "object — Tenant-defined free-form metadata (ADR-0010). Defaults to {} when empty (POST does NOT seed this — mutate via PATCH /v1/users/me/profile-data afterward).",
                     created_at: "ISO datetime",
                     updated_at: "ISO datetime",
                     settings: "UserSettingsResponse | null"
@@ -1555,6 +1840,7 @@ const END_USER_ENDPOINTS = {
                     status: "string",
                     current_plan_id: "uuid | null",
                     default_organization_id: "uuid | null",
+                    profile_data: "object — Tenant-defined free-form metadata (ADR-0010). Defaults to {} when empty.",
                     created_at: "ISO datetime",
                     updated_at: "ISO datetime",
                     settings: "UserSettingsResponse | null (only if include_settings=true)"
@@ -1695,7 +1981,7 @@ const END_USER_ENDPOINTS = {
         ]
     },
     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).",
+        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). Phase 3 additions: `reference` field type + cross-schema `join` clauses (ADR-0009), and reserved-slug enforcement (ADR-0011). Use `get_reserved_schema_slugs()` to pre-validate slugs.",
         endpoints: [
             // ── End-User Schema Endpoints ──
             {
@@ -1729,7 +2015,8 @@ const END_USER_ENDPOINTS = {
                     enum: '{"type":"enum","required":true,"values":["draft","published","archived"]}     // KEY IS "values", NOT "choices" — Genlobe rejects "choices" with 400.',
                     email: '{"type":"email","required":true,"max_length":255}',
                     url: '{"type":"url","required":false,"max_length":2048}',
-                    phone: '{"type":"phone","required":false,"max_length":20}'
+                    phone: '{"type":"phone","required":false,"max_length":20}',
+                    reference: '{"type":"reference","target_schema_slug":"users","required":true,"on_delete":"set_null"}     // ADR-0009. target_schema_slug must be lowercase letters/numbers/hyphens and reference an existing schema slug in the same Org — use the literal "users" for the native users table. on_delete is one of "set_null" (default), "restrict", or "cascade". Self-references (target_schema_slug == this schema\'s slug) are rejected with 400.'
                 },
                 example_request: `{
   "name": "Blog Post",
@@ -1739,10 +2026,11 @@ const END_USER_ENDPOINTS = {
     "title":  {"type": "string",  "required": true,  "max_length": 255},
     "body":   {"type": "text",    "required": true},
     "status": {"type": "enum",    "required": true,  "values": ["draft", "published", "archived"]},
-    "views":  {"type": "integer", "required": false, "min": 0}
+    "views":  {"type": "integer", "required": false, "min": 0},
+    "author": {"type": "reference", "target_schema_slug": "users", "required": true, "on_delete": "restrict"}
   }
 }`,
-                notes: "Returns 409 if name or slug already exists. Common pitfall: the enum field uses 'values' (an array) — 'choices' is rejected with a 400 that names this directly. The validator runs at field level, so all errors come back together in `detail.errors[]`."
+                notes: "Returns 409 if name or slug already exists. Returns 400 if the slug collides with a native DB table (e.g. `users`, `conversations`, `agents`, `subscriptions`, ...) — ADR-0011 reserves 53 such slugs (case-insensitive). Call `get_reserved_schema_slugs()` to get the full list and pre-validate before POSTing. Common pitfall: the enum field uses 'values' (an array) — 'choices' is rejected with a 400 that names this directly. Reference fields (ADR-0009) are validated app-side (no SQL FK from JSONB) — `target_schema_slug` MUST point at an existing schema in the same Organization, or the literal `users` for the native users table. The validator runs at field level, so all errors come back together in `detail.errors[]`."
             },
             {
                 method: "GET",
@@ -1818,11 +2106,12 @@ const END_USER_ENDPOINTS = {
             {
                 method: "POST",
                 path: "/v1/entity/records/search",
-                summary: "Advanced search for entity records with filters and ordering",
+                summary: "Advanced search for entity records with filters, ordering, and cross-schema joins (ADR-0009)",
                 auth: { api_key: "sk_live_* or pk_live_*", jwt: false, headers: "X-Organization-Id required when key is not organization-scoped" },
                 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: "object (optional) - filters: {field: value} for equality, {field: {operator: 'gt', value: 100}} for operators",
+                    join: "array (optional, ADR-0009) — Cross-schema inner-join clauses against reference fields. Each item: { 'field': string (reference field on source schema), 'target_schema_slug': string (must match the field's declared target; use 'users' for the native users table), 'where': object (optional, JSONB equality predicates applied to the target's data; empty means 'just confirm the target exists') }. Multiple clauses are AND-ed. Inner-join only — no left/right. The target's fields are NOT returned to the caller; joins are filter-only. `where` does NOT support nested joins. Implemented as one EXISTS sub-select per clause (no N+1)."
                 },
                 query_params: {
                     page: "number (default 1)",
@@ -1830,14 +2119,21 @@ const END_USER_ENDPOINTS = {
                     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",
+                notes: "Supported operators in `query`: eq, ne, gt, gte, lt, lte, like, ilike, in, not_in. Row-level scope (ADR-0007): regular end-users (role=member) only see records where created_by_id = current_user.id; OrgAdmin and TenantMember bypass via include_all=true (audit-logged). Use the simpler GET /v1/entity/records/mine for the common 'my data' query.",
                 example_request: `{
   "schema_id": "550e8400-e29b-41d4-a716-446655440000",
   "query": {
     "price": { "operator": "gt", "value": 100 },
     "category": "electronics",
     "status": { "operator": "in", "value": ["active", "pending"] }
-  }
+  },
+  "join": [
+    {
+      "field": "author",
+      "target_schema_slug": "users",
+      "where": { "is_active": true }
+    }
+  ]
 }`
             }
         ]
@@ -3231,21 +3527,26 @@ 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.
+Categories: authentication, organizations, subscriptions, billing (incl. Tier-3 admin read-only endpoints + subscriptions list), organization_admin (non-billing Org Owner Dashboard surfaces — members, customers, agents, KB, notifications, webhook audit), usage, agents, users (incl. PATCH /users/me/profile-data — ADR-0010), plans, ai, entities (Phase 3: reference fields + cross-schema join — ADR-0009; reserved slugs — ADR-0011), departments, files, external_agents.
 
-The 'billing' category now covers both the end-user surface
+The 'billing' category 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}).
+billing surface (/v1/organization-admin/{org_id}/{plans, config/stripe, audit, subscriptions}).
 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.`,
+the MCP never accepts raw secrets inline.
+
+The 'organization_admin' category covers the non-billing admin surfaces:
+members CRUD, customers list, agents visibility (Hybrid Catalog — ADR-0006 v2),
+KnowledgeBase + Documents CRUD (per-Org via rag_role), agent-change
+notifications, and the Stripe webhook event audit log.`,
                 inputSchema: {
                     type: "object",
                     properties: {
                         category: {
                             type: "string",
                             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"],
+                            enum: ["authentication", "organizations", "subscriptions", "billing", "organization_admin", "usage", "agents", "users", "plans", "ai", "entities", "departments", "files", "external_agents"],
                         },
                     },
                     required: [],
@@ -3302,6 +3603,15 @@ the MCP never accepts raw secrets inline.`,
                     required: ["org_id"],
                 },
             },
+            {
+                name: "get_reserved_schema_slugs",
+                description: `Return the full list of schema slugs the Custom Entities subsystem reserves (ADR-0011). These slugs collide with native DB tables (e.g. \`users\`, \`conversations\`, \`agents\`, \`subscriptions\`, \`alembic_version\`, ...) and CANNOT be used as a custom data schema slug — the server rejects them at \`POST /v1/entity/schemas\` with a 400. Comparison is case-insensitive and ignores surrounding whitespace. Call this tool BEFORE issuing a \`POST /v1/entity/schemas\` so the agent can refuse client-side instead of round-tripping a 400. Pure data; no network call.`,
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                    required: [],
+                },
+            },
             {
                 name: "get_request_headers",
                 description: "Get detailed information about required HTTP headers for API requests.",
@@ -3647,6 +3957,29 @@ ${JSON.stringify({ categories, summaries }, null, 2)}`,
                     ],
                 };
             }
+            case "get_reserved_schema_slugs": {
+                // ADR-0011: returns the full list of slugs that cannot be used
+                // for a Custom Entity schema because they collide with a native
+                // DB table. Agents should call this BEFORE issuing
+                // POST /v1/entity/schemas so they can refuse client-side.
+                const slugs = [...RESERVED_SCHEMA_SLUGS];
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                reserved_slugs: slugs,
+                                total: slugs.length,
+                                comparison: "case-insensitive (server normalizes via .strip().lower() before comparison)",
+                                rejection_status: 400,
+                                rejection_message_template: "Schema slug '<slug>' is reserved (collides with a native table). Choose a different name.",
+                                source_of_truth: "src/tenants/services/custom_data_schema_service.py — RESERVED_SCHEMA_SLUGS. This MCP tool MUST be kept in sync; when a new native __tablename__ ships, both lists are updated in the same PR.",
+                                adr: "docs/adr/0011-namespace-collision-policy.md",
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
             case "get_request_headers": {
                 return {
                     content: [
@@ -4536,6 +4869,8 @@ async function main() {
     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(`\nCustom Entities helpers (ADR-0011):`);
+    console.error(`  - get_reserved_schema_slugs — Pre-validate schema slug before POST /v1/entity/schemas`);
     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.5.1",
+  "version": "3.6.1",
   "description": "MCP Server for GenLobe SaaS API - Provides AI assistants with comprehensive API documentation for building frontend applications",
   "main": "dist/index.js",
   "bin": {