@superglue/cli 1.1.26 → 1.1.28

package/dist/skills/superglue/SKILL.md

@@ -25,7 +25,7 @@ Read these on demand — they are authoritative for their topic and kept in sync
 | `sg skill redis`          | Redis command syntax, connection URLs, key type handling                                             |
 | `sg skill sftp-smb`       | SFTP, FTP, and SMB operations, file upload/download semantics, path handling                         |
 | `sg skill file-handling`  | File detection, parsing, `file::` reference syntax, lazy base64 access, transform-produced files     |
-| `sg skill access-rules`   | RBAC roles, tool/system permissions, mutation detection, custom rules (enterprise only)              |
+| `sg skill access-rules`   | RBAC roles, resource grants, and tool/system permissions (enterprise only)                           |
 
 ## CRITICAL RULES — READ FIRST
 
@@ -33,7 +33,7 @@ Read these on demand — they are authoritative for their topic and kept in sync
 
 1. **Check CLI exists**: Run `sg --version`. If it fails with `command not found`, install: `npm install -g @superglue/cli`.
 2. **Keep CLI and SDK up to date**: Always use the latest versions. Run `sg update` to update the CLI. For the SDK, run `npm install @superglue/client@latest` (JS) or `pip install --upgrade superglue-client` (Python).
-3. **Verify configuration**: Run `sg system list`. If it fails with `fetch failed` or auth errors, the CLI needs configuration via `sg init` (see Setup below).
+3. **Verify configuration**: Run `sg system list`. If it fails with `fetch failed` or auth errors, the CLI needs configuration via `sg init` (see Setup below). For custom/self-hosted instances, the CLI must know both the instance API endpoint and an org-scoped API key.
 
 **Calling systems and running tools**
 
@@ -103,11 +103,11 @@ Verify with `sg system list` — should return a list (possibly empty) without e
 
 Set during `sg init` or via `SUPERGLUE_CLI_PRESET` env var. Stored in `config.json` as `"preset"`.
 
-| Preset    | Description                                                        |
-| --------- | ------------------------------------------------------------------ |
-| `runner`  | Run saved tools by ID only. Read-only lookups. No building/editing |
-| `builder` | Runner + build/edit/save tools, call systems. No system CRUD       |
-| `admin`   | Full access (default)                                              |
+| Preset    | Description                                                                      |
+| --------- | -------------------------------------------------------------------------------- |
+| `runner`  | Run saved tools by ID only. Read-only lookups. No building/editing               |
+| `builder` | Runner + build/edit/save tools, call systems, manage MCP servers. No system CRUD |
+| `admin`   | Full access (default)                                                            |
 
 Blocked commands print a clear error showing the current preset and how to change it.
 
@@ -161,6 +161,30 @@ sg tool run --draft <draftId> --payload-file payload.json
 
 Streams live execution logs to the terminal. Use `--include-step-results` for raw per-step responses and `--include-config` for the full config dump.
 
+### Creating/Editing a Named MCP Server
+
+Named MCP servers expose a selected set of saved tools through an MCP endpoint. The CLI always uses the configured superglue API endpoint, so it works for Cloud and self-hosted instances when `SUPERGLUE_API_ENDPOINT` or `--endpoint` points at the right API.
+
+1. Verify CLI setup: `sg system list` or `sg mcp list`
+2. Find saved tools to expose: `sg tool list` or `sg tool find <query>`
+3. Create the server:
+   ```bash
+   sg mcp create --name sales-tools --tool get_customer --tool create_invoice
+   ```
+4. Use the returned `server.connection.endpoint` and `clientConfig` in the MCP client.
+5. Edit later with:
+   ```bash
+   sg mcp edit --id <serverId> --add-tool another_tool
+   sg mcp edit --id <serverId> --tools get_customer,create_invoice
+   ```
+
+Auth modes:
+
+- `oauth` (default): OAuth-capable MCP clients authenticate users through the MCP auth flow.
+- `creator_api_key`: private/headless clients must send `Authorization: Bearer <SUPERGLUE_API_KEY>` where the key is active and assigned to the MCP server creator.
+
+If `sg mcp ...` returns "MCP server management is not available", the target instance or plan does not support named MCP server management. The default all-tools MCP endpoint may still be usable at `<api-endpoint>/mcp`.
+
 ---
 
 ## Reference
@@ -169,22 +193,25 @@ Streams live execution logs to the terminal. Use `--include-step-results` for ra
 
 Agents familiar with the web tool names can map them directly to CLI commands:
 
-| Web agent tool                               | CLI command                                   | Notes                                                              |
-| -------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------ |
-| `build_tool`                                 | `sg tool build --config '{...}'`              | CLI is not AI-powered — you provide the full JSON config           |
-| `edit_tool`                                  | `sg tool edit --tool <id> --patches '[...]'`  | JSON Patch (RFC 6902). Use `--draft <id>` for drafts               |
-| `run_tool`                                   | `sg tool run --tool <id>` / `--draft <id>`    | Add `--include-step-results` to inspect per-step data              |
-| `save_tool`                                  | `sg tool save --draft <draftId>`              | Persists a draft to the database                                   |
-| `run_command` with `vfs` for `/org/tools/`   | `sg tool find --id <id>` / `sg tool find <q>` | Full config with `--id`, compact search with a query string        |
-| `create_system`                              | `sg system create --name "..." --url "..."`   | Use `--template <id>` when available                               |
-| `edit_system`                                | `sg system edit --id <id> ...`                | Supports `--env dev\|prod`                                         |
-| `run_command` with `vfs` for `/org/systems/` | `sg system find <query>` / `--id <id>`        | Returns `storedCredentials` and system URL                         |
-| Credentials VFS / user-owned credentials     | `sg system credentials get/set/clear`         | Manage current user's credentials for user-owned systems           |
-| `call_system`                                | `sg system call --url "..." --system-id <id>` | Authenticated ad-hoc calls for testing / schema introspection      |
-| `run_command search`                         | `sg system search-docs --system-id <id> -k`   | Targeted keyword search over ingested system docs                  |
-| `authenticate_oauth`                         | `sg system oauth --system-id <id> [--scopes]` | Opens browser flow. Supports `--grant-type client_credentials` too |
-| `run_command` with `vfs` for `/org/runs/`    | `sg run list` / `sg run get <runId>`          | Filter `list` by `--tool`, `--status`, `--source`, `--limit`       |
-| (no direct equivalent)                       | `sg init`, `sg update`, `sg skill`            | CLI-specific setup, updater, and this reference system             |
+| Web agent tool                                   | CLI command                                   | Notes                                                              |
+| ------------------------------------------------ | --------------------------------------------- | ------------------------------------------------------------------ |
+| `build_tool`                                     | `sg tool build --config '{...}'`              | CLI is not AI-powered — you provide the full JSON config           |
+| `edit_tool`                                      | `sg tool edit --tool <id> --patches '[...]'`  | JSON Patch (RFC 6902). Use `--draft <id>` for drafts               |
+| `run_tool`                                       | `sg tool run --tool <id>` / `--draft <id>`    | Add `--include-step-results` to inspect per-step data              |
+| `save_tool`                                      | `sg tool save --draft <draftId>`              | Persists a draft to the database                                   |
+| `run_command` with `vfs` for `/org/tools/`       | `sg tool find --id <id>` / `sg tool find <q>` | Full config with `--id`, compact search with a query string        |
+| `create_system`                                  | `sg system create --name "..." --url "..."`   | Use `--template <id>` when available                               |
+| `edit_system`                                    | `sg system edit --id <id> ...`                | Supports `--env dev\|prod`                                         |
+| `run_command` with `vfs` for `/org/systems/`     | `sg system find <query>` / `--id <id>`        | Returns `storedCredentials` and system URL                         |
+| Credentials VFS / user-owned credentials         | `sg system credentials get/set/clear`         | Manage current user's credentials for user-owned systems           |
+| `call_system`                                    | `sg system call --url "..." --system-id <id>` | Authenticated ad-hoc calls for testing / schema introspection      |
+| `run_command search`                             | `sg system search-docs --system-id <id> -k`   | Targeted keyword search over ingested system docs                  |
+| `authenticate_oauth`                             | `sg system oauth --system-id <id> [--scopes]` | Opens browser flow. Supports `--grant-type client_credentials` too |
+| `run_command` with `vfs` for `/org/runs/`        | `sg run list` / `sg run get <runId>`          | Filter `list` by `--tool`, `--status`, `--source`, `--limit`       |
+| `run_command` with `vfs` for `/org/mcp-servers/` | `sg mcp list` / `sg mcp find --id <id>`       | Returns endpoint, auth mode, selected tool IDs, and client config  |
+| `create_mcp_server`                              | `sg mcp create --name <n> --tool <id>`        | Creates a named MCP endpoint for selected saved tools              |
+| `edit_mcp_server`                                | `sg mcp edit --id <id> ...`                   | Edits name, auth mode, description, or selected tool IDs           |
+| (no direct equivalent)                           | `sg init`, `sg update`, `sg skill`            | CLI-specific setup, updater, and this reference system             |
 
 Web-agent-only concepts with no CLI equivalent: `run_command`'s virtual filesystem (CLI uses concrete `sg` subcommands), `create_schedule`/`edit_schedule` (manage schedules via web app or REST API), `authenticate_oauth`'s dedicated MCP `authenticate` tool (CLI uses `sg system oauth`).
 
@@ -227,6 +254,19 @@ sg system oauth --system-id gmail --scopes "https://www.googleapis.com/auth/gmai
 sg system oauth --system-id my_api --grant-type client_credentials --scopes "read write"
 ```
 
+**MCP server commands:**
+
+```bash
+sg mcp list
+sg mcp find sales
+sg mcp find --id <serverId>
+sg mcp create --name sales-tools --tool get_customer --tool create_invoice
+sg mcp create --name sales-tools --tools get_customer,create_invoice --auth-mode oauth
+sg mcp edit --id <serverId> --add-tool another_tool
+sg mcp edit --id <serverId> --remove-tool old_tool
+sg mcp edit --id <serverId> --auth-mode creator_api_key
+```
+
 **Run commands:**
 
 ```bash
@@ -354,6 +394,19 @@ sourceData = {
 }
 ```
 
+### Naming Rules — Avoiding Key Collisions
+
+Everything in `sourceData` shares ONE flat namespace, and the runtime does not detect collisions — when two sources use the same key, one silently wins and the tool misbehaves with no error. Prevent collisions at design time:
+
+Never use these as payload input keys or step ids:
+
+- `__files__`, `currentItem`, `sg_auth_email` — overwritten by the runtime
+- `page`, `offset`, `cursor`, `limit`, `pageSize` — a payload key with one of these names shadows the live pagination counters; paginated steps silently stop advancing past the first page
+- the tool's own step ids — the step result overwrites a same-named payload key for all subsequent steps
+- credential keys available to a step (`<systemId>_<credKey>`, `<systemId>_url`, and any runtime-supplied credential names) — the credential value silently replaces the payload value
+
+Safe naming: payload inputs get specific, domain-flavored names (`customerId`, `reportMonth`, `maxResults` — never `page`, `limit`, `cursor`, `data`); step ids are verb-prefixed camelCase (`fetchUsers`) and distinct from every payload key. If the user asks for an input named like a reserved key, use a safe alternative and explain why.
+
 ### Step Result Envelopes
 
 **Every** step result is wrapped in `{ currentItem, data, success }`. You MUST account for this when writing data selectors or transforms.
@@ -548,6 +601,7 @@ curl -X POST "https://api.superglue.cloud/v1/hooks/{toolId}?token=$SUPERGLUE_API
 - **POST for read-only ops** — GraphQL queries via POST should have `modify: false`. Don't rely on HTTP method alone
 - **Saving without approval** — always present `sg tool run` results and ask before `sg tool save`
 - **`sg_auth_email` in scheduled runs** — not available in scheduler-triggered executions. Tools using `<<sg_auth_email>>` will fail
+- **Reserved key collisions** — payload inputs or step ids named after reserved/injected keys (see Naming Rules) fail silently with wrong values, never with an error
 
 ---
 
@@ -587,6 +641,7 @@ For protocol-specific error recovery (HTTP, Postgres, MSSQL, Redis, GraphQL, SFT
 2. Re-run with `--include-step-results` to see the exact envelope shape
 3. Paginated steps merge into a single `.data` field — do not `.map()` over them
 4. Verify `sourceData.currentItem` is only referenced inside looping steps (set by the step's own `dataSelector`, not upstream)
+5. If a step silently received the wrong value (no error thrown) or pagination stopped after one page, check for a key collision between payload inputs, step ids, credential keys, and reserved runtime keys — see Naming Rules. Fix by renaming the input, not by working around it
 
 ### Persistent failures
 

package/dist/skills/superglue/references/access-rules.md

@@ -1,147 +1,111 @@
 # Access Rules (RBAC)
 
-On superglue, roles define tool-level and system-level allowlists. Users can have multiple roles. Roles and access rules are only available on enterprise organizations. Non-enterprise orgs do not have RBAC — all users have admin access on personal organizations.
+On superglue, roles define active resource grants for tools and systems. Users can have multiple roles. Roles and access rules are only available on enterprise organizations.
 
 ## Data Model
 
-### Role
-
 ```typescript
-interface Role {
-  id: string;
-  name: string;
-  description?: string;
-  tools: "ALL" | string[]; // tool allowlist
-  systems: "ALL" | Record<string, SystemPermission>; // system allowlist
-  isBaseRole?: boolean; // true for admin, member, enduser
+interface ResourceGrant {
+  roleId: string;
+  resourceRef: "tool:<encodedId>" | "system:<encodedId>" | "tool:*" | "system:*";
+  permissions: Array<"viewer" | "editor">;
+  source: "access_rule" | "ownership" | "share";
+  grantedByUserId?: string;
+  revokedAt?: Date;
+  revokedByUserId?: string;
 }
-```
-
-### SystemPermission
-
-Each system entry is either a predefined access level or a custom rule:
 
-```typescript
-type SystemPermission = SystemAccessLevel | { rules: CustomRule[] };
-```
-
-| Type               | Meaning                                          |
-| ------------------ | ------------------------------------------------ |
-| `"read-write"`     | All HTTP methods allowed                         |
-| `"read-only"`      | Only GET and HEAD; POST/PUT/PATCH/DELETE blocked |
-| `{ rules: [...] }` | Custom JS expressions that gate access           |
-
-Systems not listed in the role's `systems` map are DENIED, unless the system access is set to `"ALL"`.
-
-### CustomRule
-
-```typescript
-interface CustomRule {
+interface Role {
   id: string;
   name: string;
-  expression?: string; // JS expression, receives stepConfig
-  isActive: boolean;
+  description?: string;
+  resourceGrants: ResourceGrant[];
+  isBaseRole?: boolean;
 }
 ```
 
-Custom rules are inline in the systems map. A system either has a standard access level OR a custom rule, never both. Custom rules must return truthy to **allow** the request. If it returns falsy, throws, or has no expression, the request is blocked (fail-closed).
-
-## Tool Permissions
-
-- `tools: "ALL"` — every tool is allowed, including tools created in the future
-- `tools: ["tool-id-1", "tool-id-2"]` — only these specific tools are allowed; new tools are NOT auto-included (but see Auto-Append below)
-
-## System Permissions
+Only active grants where `revokedAt` is empty contribute to access. `editor` implies `viewer`.
 
-- `systems: "ALL"` — every system allowed at READ_WRITE level, including future systems. Custom rules are not possible in this mode.
-- `systems: { "gmail": "read-write", "stripe": "read-only" }` — SPECIFIC mode: per-system access levels; unlisted systems are denied.
-- `systems: { "gmail": { rules: [{ name: "block-deletes", expression: "stepConfig.method !== 'DELETE'", isActive: true }] } }` — custom rule on a specific system
+## Resource Refs
 
-## Mutation Detection by Protocol
+- `tool:<encodedToolId>` — one specific tool.
+- `system:<encodedSystemId>` — one specific system.
+- `tool:*` — every current and future tool.
+- `system:*` — every current and future system.
 
-Read-only mode blocks mutating requests. How "mutating" is determined per protocol:
+Resource ids are URL-encoded inside `resourceRef`; use shared helpers rather than hand-building refs.
 
-- **HTTP** — POST, PUT, PATCH, DELETE are mutating; GET and HEAD are read-only
-- **Postgres** — SQL statements starting with or containing INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE, etc. are mutating; everything else (SELECT) is read-only
-- **FTP / SMB** — operations other than `list`, `get`, `exists`, `stat` are mutating
-- **Redis** — commands not in the read-only set (GET, MGET, EXISTS, KEYS, SCAN, TTL, TYPE, HGET, HGETALL, LRANGE, SMEMBERS, SCARD, etc.) are mutating
-- **Transform** — never mutating (pure data transformation, no external system)
+## Permissions
 
-On parse failure, all protocols default to **mutating** (fail-closed).
+- `viewer` — can see and execute/use the resource.
+- `editor` — can mutate/delete/share the resource and includes `viewer`.
 
-## Custom Rule Expressions
+Current configured role access and ownership grants are generally stored as `editor`.
 
-Custom rules only apply in SPECIFIC mode. If systems is `"ALL"`, no custom rules exist.
+## Grant Sources
 
-Expressions receive a **resolved** `stepConfig` object — all template variables (`<<variable>>` and `<<(sourceData) => ...>>` expressions) are substituted with their actual runtime values before the rule evaluates. This means rules see the real URL, headers, body, and query params, not raw templates.
-
-```typescript
-interface StepConfig {
-  url: string;
-  method: string;
-  headers: Record<string, string>;
-  queryParams: Record<string, string>;
-  body: unknown;
-  systemId: string;
-}
-```
+- `access_rule` — explicit admin/Access Rules edit.
+- `ownership` — authorization projection from the resource creator.
+- `share` — explicit user-to-user sharing through the app/agent sharing flow.
 
-Example expressions:
+Ownership source of truth remains the tool/system row. Ownership grants are a permission projection and should be preserved by ordinary role edits.
 
-```javascript
-// Block all POST requests to a specific endpoint
-stepConfig.method !== "POST" || !stepConfig.url.includes("/admin");
+## Visibility and Execution Surfaces
 
-// Only allow GET requests to /api/v1/read endpoints
-stepConfig.method === "GET" && stepConfig.url.includes("/api/v1/read");
-
-// Block requests with certain headers
-!stepConfig.headers["x-dangerous-header"];
-
-// Block a specific datasource ID in the resolved body
-!(typeof stepConfig.body === "object" && stepConfig.body?.datasource?.id === "blocked-id");
-```
+- **Tools** — list/detail, agent views, VFS, REST detail, and tool history use tool `viewer`.
+- **Systems** — list/detail, agent views, VFS, docs, credentials, and `sg system call` use system `viewer`.
+- **Execution** — running a tool requires tool `viewer` plus system `viewer` for every referenced system.
+- **Editing** — updating tools/systems requires `editor`.
+- **Runs** — visible only when the user has tool `viewer` and system `viewer` for every captured system.
+- **Schedules** — visibility follows current tool behavior; editing requires tool `editor`.
+- **MCP** — config shows configured tools; runtime registration uses tool `viewer`, and execution still checks referenced systems.
 
 ## Multi-Role Semantics
 
-Users can have multiple roles. Resolution is **union (most permissive wins) everywhere**:
-
-| Layer        | Semantics                      | Example                                                                     |
-| ------------ | ------------------------------ | --------------------------------------------------------------------------- |
-| Tools        | Union (most permissive wins)   | If role A allows tool X and role B doesn't, tool X is allowed               |
-| Systems      | Union (most permissive wins)   | If role A gives READ_ONLY and role B gives READ_WRITE, result is READ_WRITE |
-| Custom rules | Per-role union (any role wins) | If any role's complete rule set allows the request, it goes through         |
+Users can have multiple roles. Resolution is union:
 
-Custom rule detail:
+| Layer   | Semantics                                                                  |
+| ------- | -------------------------------------------------------------------------- |
+| Tools   | If any active grant targets a tool, that grant's permission is effective   |
+| Systems | If any active grant targets a system, that grant's permission is effective |
 
-- **Within a single role**, all custom rules for that system must pass (AND logic)
-- **Across roles**, evaluation is per-role: if any role fully allows the request (all its rules pass, or it has no custom rule for that system), the request is allowed (OR logic)
+Assigned roles can add access but cannot remove access granted by another role.
 
 ## Base Roles
 
-Every user has exactly **one** base role. There are three:
+Every user has exactly one base role:
 
-- **`admin`** — Full access to everything. Bypasses all RBAC checks. The admin role is **immutable** — it cannot be edited at all, nor can it be re-assigned.
-- **`member`** — Default for org team members. Starts with `tools: "ALL"`, `systems: "ALL"`. Tool and system allowlists can be narrowed to restrict access. Name and description cannot be changed. Cannot be deleted.
-- **`enduser`** — Default for end users with Credentials-only access. Starts with `tools: []`, `systems: {}` (no access). Tool and system allowlists must be explicitly populated to grant access. Name and description cannot be changed. Cannot be deleted.
+- **`admin`** — full access to everything. The admin role is immutable and has wildcard `editor` grants.
+- **`member`** — default for org team members. New organizations seed it with wildcard `editor` grants for tools and systems. Access-rule grants can be narrowed. Name and description cannot be changed. Cannot be deleted.
 
-Base roles define the starting permissions that custom roles can extend or build on top of. Users can also have additional **custom roles** on top of their base role. Custom roles are fully editable (name, description, tools, systems) and can be created and deleted.
+Users can also have additional custom roles on top of their base role. Custom roles are fully editable and can be created/deleted.
 
 ## Personal Roles
 
-Admins can create a **personal role** for a specific user. A personal role is a per-user override that scopes which tools and systems that individual can access — independent of their base role and shared custom roles.
+Personal roles are per-user containers for ownership, share, and explicit access-rule grants.
+
+- Each user can have at most one personal role.
+- Ownership grants are added automatically when a user creates a tool or system.
+- Personal role grants are unioned with the user's other roles.
+- Managed via the Personal Roles tab in Access Rules and backend role APIs.
+
+## Sharing Semantics
+
+V1 sharing targets organization users only. It does not share directly to base roles or custom roles.
 
-- Each user can have at most one personal role
-- Personal roles follow the same structure as custom roles (tools allowlist, systems map, custom rules)
-- Resolution: personal role permissions are unioned with the user's other roles (most permissive wins)
-- Use case: giving a single team member access to a sensitive system without creating a shared role
-- Managed via the **Personal Roles** tab in Access Rules (web app) or the REST API (`POST /v1/users/:userId/personal-role`)
+- Sharing writes `source: "share"` grants into the target user's personal role.
+- A user can grant only permissions up to their own effective access: viewer can grant viewer, editor can grant viewer or editor.
+- If the target already has the requested permission or stronger from any active grant, sharing is redundant and should be blocked.
+- If the target has viewer access and the acting user can grant editor, sharing can promote the user to editor through the personal `source: "share"` grant.
+- Sharing a tool also grants viewer access to required systems when the recipient lacks system access.
+- Tool sharing is atomic. If any selected user or required system grant cannot be applied, nothing is shared.
+- Normal users cannot unshare in V1. Admin cleanup should use Access Rules/admin grant management.
 
-### Auto-append on resource creation
+## Auto-Grant On Resource Creation
 
-When a user creates a new tool or system, the backend automatically adds it to the **creator's personal role**:
+When a user creates a new tool or system, the backend automatically grants ownership access to the creator's personal role:
 
-- New tool created → appended to the creator's personal role's `tools` list
-- New system created → appended to the creator's personal role's `systems` map with `read-write` access
+- New tool created -> `ownership` grant on `tool:<toolId>` with `editor`.
+- New system created -> `ownership` grant on `system:<systemId>` with `editor`.
 
-This only affects the creator's personal role, not base roles or additional custom roles. It ensures that a user on a restricted allowlist automatically gets access to resources they create without granting those resources to everyone with the same base role.
+This only affects the creator's personal role, not base roles or additional custom roles.

package/dist/skills/superglue/references/superglue-info.md

@@ -54,7 +54,7 @@ The persistent left sidebar contains these top-level items:
 - **Landscape** (`/landscape`) — graph overview of tools, systems, and their connections.
 - **Tools** (`/tools`, detail at `/tools/{toolId}`) — saved tools; opens the tool playground for editing, testing, and running.
 - **Systems** (`/systems`, detail at `/systems/{systemId}`) — connected external systems with credentials and documentation.
-- **My Credentials** (`/credentials`) — credential management. The **My Credentials** section is for personal user-owned system credentials; the **superglue API keys** section is for API keys. Admins and members open it inside the normal app shell from the sidebar; end users only see this standalone credentials surface.
+- **My Credentials** (`/credentials`) — credential management. The **My Credentials** section is for personal user-owned system credentials; the **superglue API keys** section is for API keys. Admins and members open it inside the normal app shell from the sidebar.
 - **Runs** (`/runs`, detail at `/runs/{runId}`) — execution history for full, draft, and single-step tool runs. Runs is a top-level sidebar item, not a Control Panel sub-item.
 - **Control Panel** (`/admin`) — expandable group for organization and account administration:
   - **Overview** (`/admin`) — dashboard summary, including failed-run and schedule summaries.
@@ -81,7 +81,6 @@ Below the navigation, the sidebar shows the organization switcher and Sign Out.
    e. Wrap result: `{ currentItem, data, success }`
    f. On failure: abort if `failureBehavior !== "continue"`
 3. **Output transform** (if present): run JS function, validate against outputSchema
-4. **Response filters** (if present): remove/mask/fail on pattern matches
 
 ### Strategy Routing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superglue/cli",
-  "version": "1.1.26",
+  "version": "1.1.28",
   "bin": {
     "sg": "./dist/cli.js"
   },

package/skills/superglue/SKILL.md

@@ -25,7 +25,7 @@ Read these on demand — they are authoritative for their topic and kept in sync
 | `sg skill redis`          | Redis command syntax, connection URLs, key type handling                                             |
 | `sg skill sftp-smb`       | SFTP, FTP, and SMB operations, file upload/download semantics, path handling                         |
 | `sg skill file-handling`  | File detection, parsing, `file::` reference syntax, lazy base64 access, transform-produced files     |
-| `sg skill access-rules`   | RBAC roles, tool/system permissions, mutation detection, custom rules (enterprise only)              |
+| `sg skill access-rules`   | RBAC roles, resource grants, and tool/system permissions (enterprise only)                           |
 
 ## CRITICAL RULES — READ FIRST
 
@@ -33,7 +33,7 @@ Read these on demand — they are authoritative for their topic and kept in sync
 
 1. **Check CLI exists**: Run `sg --version`. If it fails with `command not found`, install: `npm install -g @superglue/cli`.
 2. **Keep CLI and SDK up to date**: Always use the latest versions. Run `sg update` to update the CLI. For the SDK, run `npm install @superglue/client@latest` (JS) or `pip install --upgrade superglue-client` (Python).
-3. **Verify configuration**: Run `sg system list`. If it fails with `fetch failed` or auth errors, the CLI needs configuration via `sg init` (see Setup below).
+3. **Verify configuration**: Run `sg system list`. If it fails with `fetch failed` or auth errors, the CLI needs configuration via `sg init` (see Setup below). For custom/self-hosted instances, the CLI must know both the instance API endpoint and an org-scoped API key.
 
 **Calling systems and running tools**
 
@@ -103,11 +103,11 @@ Verify with `sg system list` — should return a list (possibly empty) without e
 
 Set during `sg init` or via `SUPERGLUE_CLI_PRESET` env var. Stored in `config.json` as `"preset"`.
 
-| Preset    | Description                                                        |
-| --------- | ------------------------------------------------------------------ |
-| `runner`  | Run saved tools by ID only. Read-only lookups. No building/editing |
-| `builder` | Runner + build/edit/save tools, call systems. No system CRUD       |
-| `admin`   | Full access (default)                                              |
+| Preset    | Description                                                                      |
+| --------- | -------------------------------------------------------------------------------- |
+| `runner`  | Run saved tools by ID only. Read-only lookups. No building/editing               |
+| `builder` | Runner + build/edit/save tools, call systems, manage MCP servers. No system CRUD |
+| `admin`   | Full access (default)                                                            |
 
 Blocked commands print a clear error showing the current preset and how to change it.
 
@@ -161,6 +161,30 @@ sg tool run --draft <draftId> --payload-file payload.json
 
 Streams live execution logs to the terminal. Use `--include-step-results` for raw per-step responses and `--include-config` for the full config dump.
 
+### Creating/Editing a Named MCP Server
+
+Named MCP servers expose a selected set of saved tools through an MCP endpoint. The CLI always uses the configured superglue API endpoint, so it works for Cloud and self-hosted instances when `SUPERGLUE_API_ENDPOINT` or `--endpoint` points at the right API.
+
+1. Verify CLI setup: `sg system list` or `sg mcp list`
+2. Find saved tools to expose: `sg tool list` or `sg tool find <query>`
+3. Create the server:
+   ```bash
+   sg mcp create --name sales-tools --tool get_customer --tool create_invoice
+   ```
+4. Use the returned `server.connection.endpoint` and `clientConfig` in the MCP client.
+5. Edit later with:
+   ```bash
+   sg mcp edit --id <serverId> --add-tool another_tool
+   sg mcp edit --id <serverId> --tools get_customer,create_invoice
+   ```
+
+Auth modes:
+
+- `oauth` (default): OAuth-capable MCP clients authenticate users through the MCP auth flow.
+- `creator_api_key`: private/headless clients must send `Authorization: Bearer <SUPERGLUE_API_KEY>` where the key is active and assigned to the MCP server creator.
+
+If `sg mcp ...` returns "MCP server management is not available", the target instance or plan does not support named MCP server management. The default all-tools MCP endpoint may still be usable at `<api-endpoint>/mcp`.
+
 ---
 
 ## Reference
@@ -169,22 +193,25 @@ Streams live execution logs to the terminal. Use `--include-step-results` for ra
 
 Agents familiar with the web tool names can map them directly to CLI commands:
 
-| Web agent tool                               | CLI command                                   | Notes                                                              |
-| -------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------ |
-| `build_tool`                                 | `sg tool build --config '{...}'`              | CLI is not AI-powered — you provide the full JSON config           |
-| `edit_tool`                                  | `sg tool edit --tool <id> --patches '[...]'`  | JSON Patch (RFC 6902). Use `--draft <id>` for drafts               |
-| `run_tool`                                   | `sg tool run --tool <id>` / `--draft <id>`    | Add `--include-step-results` to inspect per-step data              |
-| `save_tool`                                  | `sg tool save --draft <draftId>`              | Persists a draft to the database                                   |
-| `run_command` with `vfs` for `/org/tools/`   | `sg tool find --id <id>` / `sg tool find <q>` | Full config with `--id`, compact search with a query string        |
-| `create_system`                              | `sg system create --name "..." --url "..."`   | Use `--template <id>` when available                               |
-| `edit_system`                                | `sg system edit --id <id> ...`                | Supports `--env dev\|prod`                                         |
-| `run_command` with `vfs` for `/org/systems/` | `sg system find <query>` / `--id <id>`        | Returns `storedCredentials` and system URL                         |
-| Credentials VFS / user-owned credentials     | `sg system credentials get/set/clear`         | Manage current user's credentials for user-owned systems           |
-| `call_system`                                | `sg system call --url "..." --system-id <id>` | Authenticated ad-hoc calls for testing / schema introspection      |
-| `run_command search`                         | `sg system search-docs --system-id <id> -k`   | Targeted keyword search over ingested system docs                  |
-| `authenticate_oauth`                         | `sg system oauth --system-id <id> [--scopes]` | Opens browser flow. Supports `--grant-type client_credentials` too |
-| `run_command` with `vfs` for `/org/runs/`    | `sg run list` / `sg run get <runId>`          | Filter `list` by `--tool`, `--status`, `--source`, `--limit`       |
-| (no direct equivalent)                       | `sg init`, `sg update`, `sg skill`            | CLI-specific setup, updater, and this reference system             |
+| Web agent tool                                   | CLI command                                   | Notes                                                              |
+| ------------------------------------------------ | --------------------------------------------- | ------------------------------------------------------------------ |
+| `build_tool`                                     | `sg tool build --config '{...}'`              | CLI is not AI-powered — you provide the full JSON config           |
+| `edit_tool`                                      | `sg tool edit --tool <id> --patches '[...]'`  | JSON Patch (RFC 6902). Use `--draft <id>` for drafts               |
+| `run_tool`                                       | `sg tool run --tool <id>` / `--draft <id>`    | Add `--include-step-results` to inspect per-step data              |
+| `save_tool`                                      | `sg tool save --draft <draftId>`              | Persists a draft to the database                                   |
+| `run_command` with `vfs` for `/org/tools/`       | `sg tool find --id <id>` / `sg tool find <q>` | Full config with `--id`, compact search with a query string        |
+| `create_system`                                  | `sg system create --name "..." --url "..."`   | Use `--template <id>` when available                               |
+| `edit_system`                                    | `sg system edit --id <id> ...`                | Supports `--env dev\|prod`                                         |
+| `run_command` with `vfs` for `/org/systems/`     | `sg system find <query>` / `--id <id>`        | Returns `storedCredentials` and system URL                         |
+| Credentials VFS / user-owned credentials         | `sg system credentials get/set/clear`         | Manage current user's credentials for user-owned systems           |
+| `call_system`                                    | `sg system call --url "..." --system-id <id>` | Authenticated ad-hoc calls for testing / schema introspection      |
+| `run_command search`                             | `sg system search-docs --system-id <id> -k`   | Targeted keyword search over ingested system docs                  |
+| `authenticate_oauth`                             | `sg system oauth --system-id <id> [--scopes]` | Opens browser flow. Supports `--grant-type client_credentials` too |
+| `run_command` with `vfs` for `/org/runs/`        | `sg run list` / `sg run get <runId>`          | Filter `list` by `--tool`, `--status`, `--source`, `--limit`       |
+| `run_command` with `vfs` for `/org/mcp-servers/` | `sg mcp list` / `sg mcp find --id <id>`       | Returns endpoint, auth mode, selected tool IDs, and client config  |
+| `create_mcp_server`                              | `sg mcp create --name <n> --tool <id>`        | Creates a named MCP endpoint for selected saved tools              |
+| `edit_mcp_server`                                | `sg mcp edit --id <id> ...`                   | Edits name, auth mode, description, or selected tool IDs           |
+| (no direct equivalent)                           | `sg init`, `sg update`, `sg skill`            | CLI-specific setup, updater, and this reference system             |
 
 Web-agent-only concepts with no CLI equivalent: `run_command`'s virtual filesystem (CLI uses concrete `sg` subcommands), `create_schedule`/`edit_schedule` (manage schedules via web app or REST API), `authenticate_oauth`'s dedicated MCP `authenticate` tool (CLI uses `sg system oauth`).
 
@@ -227,6 +254,19 @@ sg system oauth --system-id gmail --scopes "https://www.googleapis.com/auth/gmai
 sg system oauth --system-id my_api --grant-type client_credentials --scopes "read write"
 ```
 
+**MCP server commands:**
+
+```bash
+sg mcp list
+sg mcp find sales
+sg mcp find --id <serverId>
+sg mcp create --name sales-tools --tool get_customer --tool create_invoice
+sg mcp create --name sales-tools --tools get_customer,create_invoice --auth-mode oauth
+sg mcp edit --id <serverId> --add-tool another_tool
+sg mcp edit --id <serverId> --remove-tool old_tool
+sg mcp edit --id <serverId> --auth-mode creator_api_key
+```
+
 **Run commands:**
 
 ```bash
@@ -354,6 +394,19 @@ sourceData = {
 }
 ```
 
+### Naming Rules — Avoiding Key Collisions
+
+Everything in `sourceData` shares ONE flat namespace, and the runtime does not detect collisions — when two sources use the same key, one silently wins and the tool misbehaves with no error. Prevent collisions at design time:
+
+Never use these as payload input keys or step ids:
+
+- `__files__`, `currentItem`, `sg_auth_email` — overwritten by the runtime
+- `page`, `offset`, `cursor`, `limit`, `pageSize` — a payload key with one of these names shadows the live pagination counters; paginated steps silently stop advancing past the first page
+- the tool's own step ids — the step result overwrites a same-named payload key for all subsequent steps
+- credential keys available to a step (`<systemId>_<credKey>`, `<systemId>_url`, and any runtime-supplied credential names) — the credential value silently replaces the payload value
+
+Safe naming: payload inputs get specific, domain-flavored names (`customerId`, `reportMonth`, `maxResults` — never `page`, `limit`, `cursor`, `data`); step ids are verb-prefixed camelCase (`fetchUsers`) and distinct from every payload key. If the user asks for an input named like a reserved key, use a safe alternative and explain why.
+
 ### Step Result Envelopes
 
 **Every** step result is wrapped in `{ currentItem, data, success }`. You MUST account for this when writing data selectors or transforms.
@@ -548,6 +601,7 @@ curl -X POST "https://api.superglue.cloud/v1/hooks/{toolId}?token=$SUPERGLUE_API
 - **POST for read-only ops** — GraphQL queries via POST should have `modify: false`. Don't rely on HTTP method alone
 - **Saving without approval** — always present `sg tool run` results and ask before `sg tool save`
 - **`sg_auth_email` in scheduled runs** — not available in scheduler-triggered executions. Tools using `<<sg_auth_email>>` will fail
+- **Reserved key collisions** — payload inputs or step ids named after reserved/injected keys (see Naming Rules) fail silently with wrong values, never with an error
 
 ---
 
@@ -587,6 +641,7 @@ For protocol-specific error recovery (HTTP, Postgres, MSSQL, Redis, GraphQL, SFT
 2. Re-run with `--include-step-results` to see the exact envelope shape
 3. Paginated steps merge into a single `.data` field — do not `.map()` over them
 4. Verify `sourceData.currentItem` is only referenced inside looping steps (set by the step's own `dataSelector`, not upstream)
+5. If a step silently received the wrong value (no error thrown) or pagination stopped after one page, check for a key collision between payload inputs, step ids, credential keys, and reserved runtime keys — see Naming Rules. Fix by renaming the input, not by working around it
 
 ### Persistent failures