@celigo/api-specs 0.2.192 → 0.2.194

package/dist/mcp-server.yml

@@ -226,6 +226,118 @@ paths:
           $ref: '#/components/responses/401-unauthorized'
         '422':
           $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/mcpservers/logs/filter-options:
+    get:
+      x-internal: false
+      operationId: getMcpServerRequestLogFilterOptions
+      tags:
+        - MCP Servers
+      summary: Get MCP request log filter options
+      description: |-
+        Returns the filter values to offer for `GET /v1/mcpservers/{_id}/logs`: the JSON-RPC
+        methods to pick from and the closed set of `status` outcomes. The `method` list is not
+        an allow-list — the list operation's `method` filter also takes the underscore form
+        (`tools_call`), methods this endpoint does not list (`initialize`), and an unknown value,
+        which returns an empty page. The options are the same for every MCP server, so this
+        endpoint takes no server id.
+      parameters:
+        - name: type
+          in: query
+          required: false
+          description: Return only one option list. Omit to return both.
+          schema:
+            type: string
+            enum:
+              - method
+              - status
+            x-enumDescriptions:
+              method: Return only the `method` list.
+              status: Return only the `status` list.
+            examples:
+              - method
+      responses:
+        '200':
+          description: Filter values. A list is present when `type` is omitted or names it.
+          content:
+            application/json:
+              schema:
+                type: object
+                description: Filter values by filter name.
+                properties:
+                  method:
+                    type: array
+                    description: |-
+                      JSON-RPC methods to offer for the `method` filter; see the list operation
+                      for every value the filter takes. Present when `type` is omitted or is
+                      `method`.
+                    items:
+                      type: string
+                      enum:
+                        - tools/list
+                        - tools/call
+                        - prompts/list
+                        - prompts/get
+                        - resources/list
+                        - resources/read
+                      x-enumDescriptions:
+                        tools/list: Requests listing the server's tools.
+                        tools/call: Requests running a tool.
+                        prompts/list: Requests listing the server's prompts.
+                        prompts/get: Requests fetching a prompt.
+                        resources/list: Requests listing the server's resources.
+                        resources/read: Requests reading a resource.
+                  status:
+                    type: array
+                    description: |-
+                      Outcomes the `status` filter accepts — a closed set; any other value is
+                      rejected with 422. Present when `type` is omitted or is `status`.
+                    items:
+                      type: string
+                      enum:
+                        - success
+                        - error
+                        - blocked
+                      x-enumDescriptions:
+                        success: Requests that completed without an error.
+                        error: Requests that failed.
+                        blocked: Requests rejected before they ran by a traffic limit, an access or OAuth scope check, or the network policy.
+              examples:
+                default:
+                  value:
+                    method:
+                      - tools/list
+                      - tools/call
+                      - prompts/list
+                      - prompts/get
+                      - resources/list
+                      - resources/read
+                    status:
+                      - success
+                      - error
+                      - blocked
+                status_only:
+                  summary: type=status
+                  value:
+                    status:
+                      - success
+                      - error
+                      - blocked
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '422':
+          description: '`type` is not `method` or `status`.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_type:
+                  value:
+                    errors:
+                      - code: invalid_query_params
+                        message: type is not valid.
   /v1/mcpservers/{_id}:
     get:
       x-internal: false
@@ -1400,28 +1512,490 @@ paths:
                         capabilities:
                           - pset:6a7b8c9d0e1f2a3b4c5d6e7f
         '400':
-          description: |-
-            Validation failed. Pre-flight failures (invalid MCP server id,
-            invalid request body, more than 100 or duplicate `_groupIds`, unknown
-            group ids, capabilities that do not resolve on this server) return a
-            bare `errors` array; a mid-batch failure returns the result body with
-            partial progress plus `errors`.
+          description: |-
+            Validation failed. Pre-flight failures (invalid MCP server id,
+            invalid request body, more than 100 or duplicate `_groupIds`, unknown
+            group ids, capabilities that do not resolve on this server) return a
+            bare `errors` array; a mid-batch failure returns the result body with
+            partial progress plus `errors`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                too_many:
+                  value:
+                    errors:
+                      - code: validation_failed
+                        message: Validation failed. _groupIds cannot exceed 100 entries per request.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          description: MCP server not found in this account.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                server_not_found:
+                  value:
+                    errors:
+                      - code: not_found
+                        message: MCP server not found in this account.
+  /v1/mcpservers/{_id}/logs:
+    get:
+      x-internal: false
+      operationId: listMcpServerRequestLogs
+      tags:
+        - MCP Servers
+      summary: List MCP server request logs
+      description: |-
+        Lists the MCP JSON-RPC requests this server handled, newest first, 50 per page. Follow
+        `nextPageURL` for the next page. Entries are summaries; when `hasPayload` is true, read
+        the stored request and response with `GET /v1/mcpservers/{_id}/logs/{key}`. Requires
+        MCP operations access on the account.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: MCP server ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: mcpservers
+            examples:
+              - 69eb9fb5b4fc023618e490b8
+        - name: time_gt
+          in: query
+          required: false
+          description: Only return requests recorded after this time (exclusive), as epoch milliseconds.
+          schema:
+            type: integer
+            format: int64
+            examples:
+              - 1792700000000
+        - name: time_lte
+          in: query
+          required: false
+          description: Only return requests recorded at or before this time (inclusive), as epoch milliseconds.
+          schema:
+            type: integer
+            format: int64
+            examples:
+              - 1792786400000
+        - name: method
+          in: query
+          required: false
+          description: |-
+            Only return requests with these JSON-RPC methods. Repeat the parameter for several
+            values. Get the values from `GET /v1/mcpservers/logs/filter-options`; the
+            underscore form the listing returns (`tools_call`) is accepted too, and so is a
+            method filter-options does not list but rows carry, such as `initialize`. A value
+            no request carries is not rejected: the page is empty.
+          style: form
+          explode: true
+          schema:
+            type: array
+            items:
+              type: string
+            examples:
+              - - tools/call
+        - name: status
+          in: query
+          required: false
+          description: Only return requests with these outcomes. Repeat the parameter for several values.
+          style: form
+          explode: true
+          schema:
+            type: array
+            items:
+              type: string
+              enum:
+                - success
+                - error
+                - blocked
+              x-enumDescriptions:
+                success: Requests that completed without an error.
+                error: Requests that failed.
+                blocked: Requests rejected before they ran by a traffic limit, an access or OAuth scope check, or the network policy.
+            examples:
+              - - error
+                - blocked
+        - name: entityName
+          in: query
+          required: false
+          description: |-
+            Only return requests that targeted this tool or prompt name, or resource URI.
+            Exact match after trimming whitespace; pass it once.
+          schema:
+            type: string
+            examples:
+              - get_customer
+        - name: nextPageToken
+          in: query
+          required: false
+          description: Continuation token. Follow the `nextPageURL` of the previous page instead of constructing it.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: One page of request summaries.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MCPServerRequestLogsResponse'
+              examples:
+                populated:
+                  value:
+                    requests:
+                      - time: 1792745012345
+                        method: tools_call
+                        status: success
+                        invocationId: a1b2c3d4e5f60718293a4b5c
+                        hasPayload: true
+                        key: 5465373387655-3f2a9c0d1e4b4c6f8a7b9d0e1f2a3b4c-tools_call-S
+                        entityName: get_customer
+                        assetType: IO Tool
+                        entityId: 65a98d1ef2b40000098c3a4d
+                        opStartedAt: 1792745012100
+                        opEndedAt: 1792745012340
+                        authType: apiToken
+                        accessToken:
+                          _id: 66b0c1d2e3f4a5b6c7d8e9f0
+                          name: MCP client token
+                          deleted: false
+                    nextPageURL: /v1/mcpservers/69eb9fb5b4fc023618e490b8/logs?nextPageToken=eyJ0IjoxNzkyNzQ1MDEyMzQ1LCJoIjoiMTIzNDU2Nzg5In0
+                empty:
+                  value:
+                    requests: []
+        '400':
+          description: The MCP server ID is not a valid ObjectId.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_id:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _mcpServerId.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          description: No MCP server with this ID is visible to the caller. Checked before the query parameters.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_found:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: McpServer not found.
+        '422':
+          description: |-
+            A query parameter is invalid — `time_gt` or `time_lte` is not epoch milliseconds,
+            `status` has an unknown value, `entityName` is repeated, or `nextPageToken` is not a
+            token from `nextPageURL`. The message names the parameter.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_status:
+                  value:
+                    errors:
+                      - code: invalid_query_params
+                        message: status is not valid.
+        '500':
+          description: The request log store could not be queried.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                query_failed:
+                  value:
+                    errors:
+                      - code: clickhouse_error
+                        message: Unable to retrieve the request logs.
+                store_unavailable:
+                  value:
+                    errors:
+                      - code: clickhouse_connection_not_established
+                        message: ClickHouse connection is not established
+  /v1/mcpservers/{_id}/logs/purge:
+    post:
+      x-internal: false
+      operationId: purgeMcpServerRequestLogs
+      tags:
+        - MCP Servers
+      summary: Purge MCP server request log payloads
+      description: |-
+        Permanently deletes the stored request/response payloads of this server's requests
+        recorded between `time_gte` and `time_lte`, both inclusive. The listing rows stay in
+        `GET /v1/mcpservers/{_id}/logs` with `hasPayload` false. Also queues deletion of the run
+        logs of each enabled Tool on the server for the same window; a Tool whose deletion
+        could not be queued is reported in `errors[]` without failing the call. Writes a
+        `purgelogs` audit entry. The window is passed as query parameters; a request body is
+        ignored. Up to 10,000 payloads per call — narrow the window when the range holds more.
+        Requires MCP operations access on the account.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: MCP server ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: mcpservers
+            examples:
+              - 69eb9fb5b4fc023618e490b8
+        - name: time_gte
+          in: query
+          required: true
+          description: Start of the window (inclusive), as an ISO 8601 date-time. Epoch milliseconds are rejected.
+          schema:
+            type: string
+            format: date-time
+            examples:
+              - '2026-10-01T00:00:00Z'
+        - name: time_lte
+          in: query
+          required: true
+          description: End of the window (inclusive), as an ISO 8601 date-time. Must not be before `time_gte` or in the future.
+          schema:
+            type: string
+            format: date-time
+            examples:
+              - '2026-10-22T23:59:59Z'
+      responses:
+        '200':
+          description: Purge outcome. `purged` is empty when the window held no stored payloads.
+          content:
+            application/json:
+              schema:
+                type: object
+                description: Purge result envelope.
+                required:
+                  - purged
+                  - errors
+                properties:
+                  purged:
+                    type: array
+                    description: Log keys whose payloads were deleted.
+                    items:
+                      type: string
+                  errors:
+                    type: array
+                    description: Tools whose run-log deletion could not be queued. Empty when every Tool was queued.
+                    items:
+                      type: object
+                      required:
+                        - code
+                        - message
+                        - _toolId
+                      properties:
+                        code:
+                          type: string
+                          description: Always `tool_log_purge_failed`.
+                          examples:
+                            - tool_log_purge_failed
+                        message:
+                          type: string
+                          description: Human-readable description of the failure.
+                          examples:
+                            - Unable to queue Tool Builder log deletion for the selected range.
+                        _toolId:
+                          type: string
+                          format: objectId
+                          x-celigo-refModel: tools
+                          description: Tool whose run logs were not queued for deletion. Retrying the purge with the same window queues it again.
+                          examples:
+                            - 65a98d1ef2b40000098c3a4d
+              examples:
+                default:
+                  value:
+                    purged:
+                      - 5465373387655-3f2a9c0d1e4b4c6f8a7b9d0e1f2a3b4c-tools_call-S
+                    errors: []
+                tool_cascade_failed:
+                  summary: Payloads purged, one Tool not queued
+                  value:
+                    purged:
+                      - 5465373387655-3f2a9c0d1e4b4c6f8a7b9d0e1f2a3b4c-tools_call-S
+                    errors:
+                      - code: tool_log_purge_failed
+                        message: Unable to queue Tool Builder log deletion for the selected range.
+                        _toolId: 65a98d1ef2b40000098c3a4d
+        '400':
+          description: |-
+            Invalid request, checked in this order — the MCP server ID is not a valid ObjectId;
+            `time_gte` or `time_lte` is missing or not a date-time (the message names the
+            parameter); the window is reversed or ends in the future;
+            or, after the server is found, the window holds more than 10,000 payloads.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_id:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _mcpServerId.
+                missing_time_gte:
+                  value:
+                    errors:
+                      - code: invalid_query_params
+                        message: time_gte is not valid.
+                invalid_range:
+                  value:
+                    errors:
+                      - code: invalid_query_params
+                        message: time_gte and time_lte must be valid ISO datetimes, a non-future window, with time_gte <= time_lte.
+                range_too_large:
+                  value:
+                    errors:
+                      - code: invalid_request
+                        message: The selected range contains too many request logs to purge in one call. Narrow the date range.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          description: No MCP server with this ID is visible to the caller. Checked after the time window.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_found:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: McpServer not found.
+        '500':
+          description: |-
+            The request log store could not be queried, or payload deletion failed partway.
+            Payloads deleted before the failure stay deleted; retry the same window.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                purge_failed:
+                  value:
+                    errors:
+                      - code: log_purge_failed
+                        message: Unable to purge the request log.
+                query_failed:
+                  value:
+                    errors:
+                      - code: clickhouse_error
+                        message: Unable to retrieve the request logs.
+  /v1/mcpservers/{_id}/logs/{key}:
+    get:
+      x-internal: false
+      operationId: getMcpServerRequestLog
+      tags:
+        - MCP Servers
+      summary: Get an MCP server request log
+      description: |-
+        Returns the stored request and response for one MCP request, looked up by a `key` from
+        `GET /v1/mcpservers/{_id}/logs`. Only entries with `hasPayload` true have a key. A key
+        whose payload was purged, a key that names no stored payload, and a malformed key all
+        answer `422` `log_file_unavailable`. The stored `Authorization` request header is
+        masked. Requires MCP operations access on the account.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: MCP server ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: mcpservers
+            examples:
+              - 69eb9fb5b4fc023618e490b8
+        - name: key
+          in: path
+          required: true
+          description: Log key from the `GET /v1/mcpservers/{_id}/logs` listing, used exactly as returned.
+          schema:
+            type: string
+            examples:
+              - 5465373387655-3f2a9c0d1e4b4c6f8a7b9d0e1f2a3b4c-tools_call-S
+      responses:
+        '200':
+          description: The stored record with the fields decoded from `key` added.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MCPServerRequestLogDetail'
+              examples:
+                default:
+                  value:
+                    key: 5465373387655-3f2a9c0d1e4b4c6f8a7b9d0e1f2a3b4c-tools_call-S
+                    id: 3f2a9c0d1e4b4c6f8a7b9d0e1f2a3b4c
+                    time: 1792745012345
+                    method: tools_call
+                    status: success
+                    request:
+                      headers:
+                        content-type: application/json
+                        authorization: Bearer ********
+                      body: '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"get_customer","arguments":{"customerId":"C-1042"}}}'
+                      httpVersion: '1.1'
+                      url: /customer-integration
+                      clientAddress: 203.0.113.7
+                      size: 234
+                    response:
+                      body: '{"jsonrpc":"2.0","id":7,"result":{"content":[{"type":"text","text":"{\"customerId\":\"C-1042\"}"}]}}'
+                      headers:
+                        content-type: application/json
+                      size: 196
+                    entityName: get_customer
+                    assetType: IO Tool
+                    _byUserId: 624774a6a7574d3ed9f9a5cc
+                    _accessTokenId: 66b0c1d2e3f4a5b6c7d8e9f0
+                    _agentId: null
+                    clientName: null
+                    clientVersion: null
+                    sourceType: celigo
+                    upstreamHost: null
+                    _connectionId: null
+                    authMode: null
+                    upstreamMs: null
+                    errorCategory: null
+                    traceId: 7f9c2e1a4b3d4c5e
+                    purgeAt: 1795337012345
+        '400':
+          description: The MCP server ID is not a valid ObjectId.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
               examples:
-                too_many:
+                invalid_id:
                   value:
                     errors:
-                      - code: validation_failed
-                        message: Validation failed. _groupIds cannot exceed 100 entries per request.
+                      - code: invalid_ref
+                        message: Please provide a valid _mcpServerId.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
           $ref: '#/components/responses/403-forbidden'
         '404':
-          description: MCP server not found in this account.
+          description: |-
+            No MCP server with this ID is visible to the caller. A key with no stored payload is a
+            `422`, not a `404`.
           content:
             application/json:
               schema:
@@ -1430,8 +2004,40 @@ paths:
                 server_not_found:
                   value:
                     errors:
-                      - code: not_found
-                        message: MCP server not found in this account.
+                      - code: invalid_ref
+                        message: McpServer not found.
+        '422':
+          description: |-
+            The stored payload could not be read (`log_file_unavailable` — the answer for a purged
+            key, a key that names no stored payload, and a malformed key), or could not be parsed
+            (`invalid_log_file`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                unavailable:
+                  value:
+                    errors:
+                      - code: log_file_unavailable
+                        message: Unable to retrieve the log file.
+                unparseable:
+                  value:
+                    errors:
+                      - code: invalid_log_file
+                        message: Unable to parse. Masked secret keys can cause parsing errors, update the access token or private field to view the data.
+        '500':
+          description: The request log store could not be queried while locating the payload.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                query_failed:
+                  value:
+                    errors:
+                      - code: clickhouse_error
+                        message: Unable to retrieve the request logs.
 components:
   securitySchemes:
     bearerAuth:
@@ -6466,23 +7072,51 @@ components:
             googleProjectId:
               type: string
               description: |-
-                Google Cloud project id for Google Cloud Storage connections
-                (assistant `googlecloudstorage`, or a `baseURI` pointing at
-                `storage.googleapis.com`).
+                Default project ID of a Google Cloud Storage connection (assistant
+                `googlecloudstorage`, or a `baseURI` pointing at
+                `storage.googleapis.com`): the Google Cloud project whose buckets the
+                export and import forms list. It does not limit access — the
+                connection reaches any bucket the authorized Google account or
+                service account may use. Set by the caller on the OAuth 2.0 auth type
+                (Celigo's published Google Cloud Storage iClient or an account-owned
+                `custom_oauth2` iClient). On the Google service account auth type the
+                server stores the key's `project_id` on create and on any save that
+                changes or omits `http.unencrypted`; a save that re-sends the stored
+                `http.unencrypted` unchanged keeps the stored value, even though the
+                response body can echo the key's — read the connection back. Trimmed
+                on save; no format is enforced (the connection form warns on a value
+                outside Google's project-id format and still saves it).
               examples:
                 - my-gcs-project
               x-celigo-ai-guidance:
                 - |-
                   Required when the GCS connection authenticates through an OAuth
-                  iClient (provider custom_oauth2). Omitting it fails the save
-                  with 422 project_id_missing on http.unencrypted.googleProjectId
-                  — "Default project ID is required on OAuth Google Cloud Storage
-                  connections (http.unencrypted.googleProjectId)." With a
-                  googleserviceaccount iClient the server fills this from the
-                  key's project_id. Any other provider fails with 422
-                  invalid_field on http._iClientId — "IClient provider must be
+                  iClient — Celigo's published Google Cloud Storage iClient (the id
+                  the connector pre-configures on `http._iClientId` when
+                  `http.auth.type` is `oauth`) or an account-owned iClient with
+                  provider custom_oauth2. Omitting it, or sending only whitespace,
+                  fails the save with 422 project_id_missing on
+                  http.unencrypted.googleProjectId — "Default project ID is
+                  required on OAuth Google Cloud Storage connections
+                  (http.unencrypted.googleProjectId)." — on create and on every
+                  later PUT. With a googleserviceaccount iClient the server stores
+                  the key's project_id on create (a value sent on create is
+                  replaced by it) and on any later save that changes or omits
+                  `http.unencrypted` — the next bullet has the PUT that does not
+                  re-fill it. Any other provider fails with 422 invalid_field
+                  on http._iClientId — "IClient provider must be
                   googleserviceaccount or custom_oauth2 for Google Cloud Storage
                   connections."
+                - |-
+                  When a PUT moves the connection from an OAuth iClient to a
+                  googleserviceaccount iClient, drop `http.unencrypted` (or change
+                  it) in the same PUT: the server's fill from the key is written
+                  only when `http.unencrypted` is absent or changed, so a PUT that
+                  re-sends the stored object unchanged keeps the OAuth-era project
+                  id beside the service account (the 200 body still echoes the
+                  key's — only a GET shows what persisted). Moving the other way
+                  (service account → OAuth) needs the project id in the PUT, or it
+                  is the 422 above.
         unencryptedFields:
           type: array
           description: |
@@ -6527,13 +7161,20 @@ components:
           description: |-
             iClient that holds the credentials this connection signs with: the OAuth 2.0 client for
             `auth.type` `oauth` (including the `azureserviceprincipal` service principal an Azure
-            Data Lake Storage Gen2 connection authenticates with and the `googleserviceaccount` key
-            a Google Cloud Storage connection uses), or the `awsIam` role for `auth.type` `awsiam`.
+            Data Lake Storage Gen2 connection authenticates with and, on a Google Cloud Storage
+            connection, either the `googleserviceaccount` key of its Google service account auth
+            type or — its OAuth 2.0 auth type — Celigo's published Google Cloud Storage iClient,
+            which the connector pre-configures, or an account-owned `custom_oauth2` iClient), or
+            the `awsIam` role for `auth.type` `awsiam`.
             Must belong to the same account as the connection — or be the iClient Celigo publishes
             with a pre-built OAuth HTTP connector (pre-configured by the connector; from the
-            connecting account `GET /v1/iclients/{_id}` on it is 404 resource_not_found and
-            `GET /v1/iclients` does not list it, yet the connection saves with it). Omit for every
-            other auth type. On a Shopify connection `settings.appType` says which of the two it
+            connecting account `GET /v1/iclients/{_id}` on it is 404 — resource_not_found or
+            invalid_ref "IClient not found." — and `GET /v1/iclients` does not list it, yet the
+            connection saves with it). Omit for every other auth type. A Google Cloud Storage
+            connection stores `auth.type` `oauth` under both of its auth types; the referenced
+            iClient's provider tells them apart, and switching is a PUT that changes `_iClientId`
+            (see `unencrypted.googleProjectId` for what travels with it). On a Shopify connection
+            `settings.appType` says which of the two it
             is: `public` rides Celigo's published Shopify app (installed from the Shopify App
             Store), `custom` rides the account's own iClient — the Shopify app the customer created
             in the Shopify dev dashboard — with `auth.oauth.scope` chosen on the connection. A
@@ -6548,7 +7189,7 @@ components:
             published app and carry no `settings.appType`.
           examples:
             - 6203a7e4f321d800129a1b8e
-          x-celigo-ui-override: 'Required by the connection form for oauth (subForms/httpOAuth.js: required true, iClient filter provider custom_oauth2, or googleserviceaccount / azureserviceprincipal for the GCS and ADLS Gen2 variants) and for awsIam (subForms/httpAwsIam.js: required true, filter provider awsIam). For oauth the API creates the connection without it and the authorization is completed afterward; for awsiam the API also rejects its absence (see the if/then rule on this schema).'
+          x-celigo-ui-override: 'Required by the connection form for oauth (subForms/httpOAuth.js: required true, iClient filter provider custom_oauth2 — on a Google Cloud Storage connection''s OAuth 2.0 auth type too, where Simple view pre-selects Celigo''s published iClient and hides the picker — or googleserviceaccount / azureserviceprincipal for the GCS Google service account and ADLS Gen2 variants) and for awsIam (subForms/httpAwsIam.js: required true, filter provider awsIam). For oauth the API creates the connection without it and the authorization is completed afterward; for awsiam the API also rejects its absence (see the if/then rule on this schema).'
           x-celigo-ai-guidance:
             - |-
               For auth.type "awsiam" the referenced iClient must have provider "awsIam" (any other
@@ -6567,10 +7208,30 @@ components:
               The iClient must belong to the same account as the connection — an iClient id from
               another account fails with 422 invalid_ref "The referenced IClient must belong to the
               same user." The one exception is the iClient a pre-built OAuth HTTP connector
-              pre-configures (Celigo's published app — the Shopify Public App's, for one): the
-              connection saves with that id from the connecting account even though
-              `GET /v1/iclients/{_id}` on it is 404 there, so do not refuse a `public` Shopify
-              connection on this rule.
+              pre-configures (Celigo's published app — the Shopify Public App's and the Google Cloud
+              Storage OAuth 2.0 iClient, for two): the connection saves with that id from the
+              connecting account even though `GET /v1/iclients/{_id}` on it is 404 there, so do not
+              refuse a `public` Shopify connection or an OAuth 2.0 Google Cloud Storage connection on
+              this rule. Read the id from the connector's metadata
+              (`GET /v1/httpconnectors/{_id}?returnEverything=true`,
+              `supportedBy.connection.preConfiguredFields` entry for `http._iClientId`), never from
+              a hard-coded value.
+            - |-
+              A Google Cloud Storage connection (assistant "googlecloudstorage", or any http.baseURI
+              containing "storage.googleapis.com") references either a googleserviceaccount iClient
+              of the same account (its Google service account auth type — no authorization step; the
+              server stores the key's project_id in `unencrypted.googleProjectId` on create and
+              whenever `http.unencrypted` changes or is omitted — see that field) or an OAuth iClient
+              with `unencrypted.googleProjectId` set (its OAuth 2.0 auth type — Celigo's published
+              iClient, or an account-owned custom_oauth2 one — authorized afterwards in a browser;
+              until then `POST /v1/connections/{_id}/ping` answers `missing_token`). The server
+              checks the provider only — a custom_oauth2 iClient registered for a different HTTP
+              connector (`_httpConnectorId`) also saves on a GCS connection — so bind an iClient
+              with no connector or the Google Cloud Storage connector's. The connection document
+              keeps `auth.oauth.scope` as sent (a GCS connection saved without it stores none), so
+              send the Cloud Storage scopes on the OAuth 2.0 auth type
+              (https://www.googleapis.com/auth/devstorage.read_write, …read_only or
+              …full_control); a service account connection carries none.
             - |-
               On a Shopify connection keep `settings.appType` and `_iClientId` in step the way the
               form does — `public` with the connector's published iClient, `custom` with an
@@ -9676,6 +10337,435 @@ components:
               message:
                 type: string
                 description: Human-readable error message.
+    MCPServerRequestLogEntry:
+      type: object
+      description: |-
+        Summary row in the `GET /v1/mcpservers/{_id}/logs` listing — one MCP JSON-RPC request
+        the server handled. The stored request/response payload is only on
+        `GET /v1/mcpservers/{_id}/logs/{key}`, and only when `hasPayload` is true.
+      required:
+        - time
+        - method
+        - status
+        - invocationId
+        - hasPayload
+        - entityName
+        - assetType
+        - entityId
+        - opStartedAt
+        - opEndedAt
+        - authType
+      properties:
+        time:
+          type: integer
+          format: int64
+          description: Epoch milliseconds when the request was recorded. The listing is sorted on this value, newest first.
+          examples:
+            - 1792745012345
+        method:
+          type:
+            - string
+            - 'null'
+          description: |-
+            JSON-RPC method of the request, with `/` replaced by `_` (`tools_call`,
+            `resources_read`). A JSON-RPC batch is recorded as one row with method `batch`.
+          examples:
+            - tools_call
+        status:
+          type: string
+          enum:
+            - success
+            - error
+            - blocked
+          x-enumDescriptions:
+            success: The request completed without an error.
+            error: The request failed.
+            blocked: The request was rejected before it ran by a traffic limit, an access or OAuth scope check, or the network policy.
+          description: Outcome of the request. Filter on it with the `status` query parameter.
+          examples:
+            - success
+        invocationId:
+          type: string
+          description: |-
+            Invocation id of the downstream tool run that served a `tools/call`. Empty string
+            when the request produced no downstream invocation.
+          examples:
+            - ''
+            - a1b2c3d4e5f60718293a4b5c
+        hasPayload:
+          type: boolean
+          description: |-
+            When true, the request/response payload is stored and `key` is set; read it with
+            `GET /v1/mcpservers/{_id}/logs/{key}`. False when the payload was never stored (the
+            server's logging mode skipped it) or has been purged.
+          examples:
+            - true
+        key:
+          type: string
+          description: |-
+            Opaque log key. Pass it to `GET /v1/mcpservers/{_id}/logs/{key}`; use it exactly as
+            returned. Present when `hasPayload` is true.
+          examples:
+            - 5465373387655-3f2a9c0d1e4b4c6f8a7b9d0e1f2a3b4c-tools_call-S
+        entityName:
+          type:
+            - string
+            - 'null'
+          description: |-
+            Capability the request targeted — the tool or prompt name for `tools/call` and
+            `prompts/get`, or the resource URI for `resources/read`. Null for list methods.
+          examples:
+            - get_customer
+        assetType:
+          type:
+            - string
+            - 'null'
+          enum:
+            - IO Tool
+            - API
+            - Prompt
+            - Resource
+            - null
+          x-enumDescriptions:
+            IO Tool: A `tools/call` served by a Celigo Tool.
+            API: A `tools/call` served by a builder-mode API.
+            Prompt: A `prompts/get` request.
+            Resource: A `resources/read` request.
+          description: |-
+            Kind of capability the request reached. Null for list methods and for tools
+            proxied from an upstream MCP server.
+          examples:
+            - IO Tool
+        entityId:
+          type:
+            - string
+            - 'null'
+          description: |-
+            Identifies the Tool (`assetType` `IO Tool`) or builder-mode API (`assetType` `API`)
+            that served a `tools/call`. Null otherwise.
+          examples:
+            - 65a98d1ef2b40000098c3a4d
+        opStartedAt:
+          type:
+            - integer
+            - 'null'
+          format: int64
+          description: Epoch milliseconds when the operation started. Null when not recorded.
+          examples:
+            - 1792745012100
+        opEndedAt:
+          type:
+            - integer
+            - 'null'
+          format: int64
+          description: Epoch milliseconds when the operation ended. Null when not recorded.
+          examples:
+            - 1792745012340
+        authType:
+          type:
+            - string
+            - 'null'
+          enum:
+            - oauth
+            - apiToken
+            - null
+          x-enumDescriptions:
+            oauth: The caller authenticated with an MCP OAuth token.
+            apiToken: The caller authenticated with an API token.
+          description: How the MCP client authenticated. Null when neither applies.
+          examples:
+            - apiToken
+        byUser:
+          type: object
+          description: User who made the request. Present when set.
+          required:
+            - _id
+            - name
+            - email
+            - deleted
+          properties:
+            _id:
+              type: string
+              format: objectId
+              x-celigo-refModel: users
+              description: User who made the request.
+              examples:
+                - 624774a6a7574d3ed9f9a5cc
+            name:
+              type:
+                - string
+                - 'null'
+              description: Display name of the user. Null when the user record is gone or has no name.
+              examples:
+                - Jane Doe
+            email:
+              type:
+                - string
+                - 'null'
+              description: Email of the user. Null when the user record is gone.
+              examples:
+                - jane.doe@example.com
+            deleted:
+              type: boolean
+              description: When true, the user has been deleted or could not be found.
+              examples:
+                - false
+        accessToken:
+          type: object
+          description: API token the request authenticated with. Present when set.
+          required:
+            - _id
+            - name
+            - deleted
+          properties:
+            _id:
+              type: string
+              format: objectId
+              x-celigo-refModel: accesstokens
+              description: API token the request authenticated with.
+              examples:
+                - 66b0c1d2e3f4a5b6c7d8e9f0
+            name:
+              type:
+                - string
+                - 'null'
+              description: Name of the token. Null when the token record is gone or has no name.
+              examples:
+                - MCP client token
+            deleted:
+              type: boolean
+              description: When true, the token has been deleted or could not be found.
+              examples:
+                - false
+    MCPServerRequestLogsResponse:
+      type: object
+      description: |-
+        Envelope returned by `GET /v1/mcpservers/{_id}/logs`. Each page holds at most 50
+        entries; `requests[]` is empty when no request matches.
+      required:
+        - requests
+      properties:
+        requests:
+          type: array
+          description: Request summaries, newest first.
+          items:
+            $ref: '#/components/schemas/MCPServerRequestLogEntry'
+        nextPageURL:
+          type: string
+          description: |-
+            Relative URL of the next page, repeating the current filters with a continuation
+            token. Present when more entries remain. Follow it as returned; do not construct it.
+          examples:
+            - /v1/mcpservers/69eb9fb5b4fc023618e490b8/logs?status=error&nextPageToken=eyJ0IjoxNzkyNzQ1MDEyMzQ1LCJoIjoiMTIzNDU2Nzg5In0
+    MCPServerRequestLogDetail:
+      type: object
+      description: |-
+        Stored request/response payload for one MCP request, returned by
+        `GET /v1/mcpservers/{_id}/logs/{key}`. The stored record is returned as-is with `key`,
+        `id`, `time`, `method`, and `status` decoded from the log key. Records written by older
+        releases may lack some of the other fields.
+      required:
+        - key
+        - id
+        - time
+        - method
+        - status
+      properties:
+        key:
+          type: string
+          description: Echoes the `key` path parameter.
+          examples:
+            - 5465373387655-3f2a9c0d1e4b4c6f8a7b9d0e1f2a3b4c-tools_call-S
+        id:
+          type: string
+          description: Storage id of this record — the second segment of `key`.
+          examples:
+            - 3f2a9c0d1e4b4c6f8a7b9d0e1f2a3b4c
+        time:
+          type: integer
+          format: int64
+          description: Epoch milliseconds when the request was recorded, decoded from `key`.
+          examples:
+            - 1792745012345
+        method:
+          type: string
+          description: JSON-RPC method with `/` replaced by `_`, decoded from `key`.
+          examples:
+            - tools_call
+        status:
+          type: string
+          enum:
+            - success
+            - error
+            - blocked
+          x-enumDescriptions:
+            success: The request completed without an error.
+            error: The request failed.
+            blocked: The request was rejected before it ran by a traffic limit, an access or OAuth scope check, or the network policy.
+          description: Outcome of the request, decoded from `key`. Same values as the listing's `status`.
+          examples:
+            - success
+        request:
+          type: object
+          description: |-
+            Inbound HTTP request as stored — `headers` (the `Authorization` value masked), `body`
+            (the JSON-RPC body as a string), `httpVersion`, `url`, `clientAddress`, and `size`.
+          additionalProperties: true
+        response:
+          type: object
+          description: Response the MCP server sent as stored — `body` (a string), `headers`, and `size`.
+          additionalProperties: true
+        entityName:
+          type:
+            - string
+            - 'null'
+          description: Tool or prompt name, or resource URI, the request targeted. Null for list methods.
+          examples:
+            - get_customer
+        assetType:
+          type:
+            - string
+            - 'null'
+          enum:
+            - IO Tool
+            - API
+            - Prompt
+            - Resource
+            - null
+          x-enumDescriptions:
+            IO Tool: A `tools/call` served by a Celigo Tool.
+            API: A `tools/call` served by a builder-mode API.
+            Prompt: A `prompts/get` request.
+            Resource: A `resources/read` request.
+          description: Kind of capability the request reached. Same values as the listing's `assetType`.
+          examples:
+            - IO Tool
+        _byUserId:
+          type:
+            - string
+            - 'null'
+          format: objectId
+          x-celigo-refModel: users
+          description: |-
+            User who made the request. Unlike the listing, the detail returns the raw id
+            without name or email.
+          examples:
+            - 624774a6a7574d3ed9f9a5cc
+        _accessTokenId:
+          type:
+            - string
+            - 'null'
+          format: objectId
+          x-celigo-refModel: accesstokens
+          description: API token the request authenticated with. Null for other authentication types.
+          examples:
+            - 66b0c1d2e3f4a5b6c7d8e9f0
+        _agentId:
+          type:
+            - string
+            - 'null'
+          description: |-
+            Celigo agent the MCP client identified itself as with the `x-celigo-agent-id` request
+            header. Null when the request carried none.
+          examples:
+            - null
+        clientName:
+          type:
+            - string
+            - 'null'
+          description: Name the MCP client reported in an `initialize` request. Null for other methods.
+          examples:
+            - claude-desktop
+        clientVersion:
+          type:
+            - string
+            - 'null'
+          description: Version the MCP client reported in an `initialize` request. Null for other methods.
+          examples:
+            - 1.4.2
+        sourceType:
+          type:
+            - string
+            - 'null'
+          enum:
+            - celigo
+            - upstream
+            - null
+          x-enumDescriptions:
+            celigo: The capability is served by Celigo.
+            upstream: The capability is proxied from an upstream MCP server.
+          description: Where the targeted capability is served from. Null when it could not be determined.
+          examples:
+            - celigo
+        upstreamHost:
+          type:
+            - string
+            - 'null'
+          description: Host of the upstream MCP server the request was proxied to. Null when the request was not proxied.
+          examples:
+            - null
+        _connectionId:
+          type:
+            - string
+            - 'null'
+          format: objectId
+          x-celigo-refModel: connections
+          description: |-
+            `mcp`-type connection the request was proxied through. Null when the request was not
+            proxied.
+          examples:
+            - null
+        authMode:
+          type:
+            - string
+            - 'null'
+          enum:
+            - parent
+            - null
+          x-enumDescriptions:
+            parent: The request was proxied to the upstream MCP server with the server's own connection credentials.
+          description: How a proxied request authenticated upstream. Null when the request was not proxied.
+          examples:
+            - null
+        upstreamMs:
+          type:
+            - integer
+            - 'null'
+          description: Latency of the hop to the upstream MCP server, in milliseconds. Null when the request was not proxied.
+          examples:
+            - null
+        errorCategory:
+          type:
+            - string
+            - 'null'
+          description: Category of the failure. Null when the request succeeded or was blocked.
+          examples:
+            - null
+        traceId:
+          type:
+            - string
+            - 'null'
+          description: Trace id of the request for cross-service correlation.
+          examples:
+            - 7f9c2e1a4b3d4c5e
+        purgeAt:
+          type:
+            - integer
+            - 'null'
+          format: int64
+          description: Epoch milliseconds when this record expires under the account's data retention period.
+          examples:
+            - 1795337012345
+        limitType:
+          type:
+            - string
+            - 'null'
+          description: Traffic limit that rejected the request. Present when a traffic limit blocked it.
+        denial:
+          type: object
+          description: Details of the access check that rejected the request. Present when an access check blocked it.
+          additionalProperties: true
+      additionalProperties: true
   responses:
     401-unauthorized:
       description: |-
@@ -9737,9 +10827,9 @@ components:
                 errors:
                   - code: unprocessable_entity
                     message: The request could not be processed due to a semantic error.
-    404-not-found:
+    403-forbidden:
       description: |
-        Not found. The requested resource does not exist or is not visible to the caller.
+        Forbidden. The authenticated caller does not have permission to perform this operation.
       content:
         application/json:
           schema:
@@ -9748,11 +10838,11 @@ components:
             default:
               value:
                 errors:
-                  - code: not_found
-                    message: The requested resource was not found.
-    403-forbidden:
+                  - code: forbidden
+                    message: You do not have permission to access this resource.
+    404-not-found:
       description: |
-        Forbidden. The authenticated caller does not have permission to perform this operation.
+        Not found. The requested resource does not exist or is not visible to the caller.
       content:
         application/json:
           schema:
@@ -9761,7 +10851,7 @@ components:
             default:
               value:
                 errors:
-                  - code: forbidden
-                    message: You do not have permission to access this resource.
+                  - code: not_found
+                    message: The requested resource was not found.
 x-enable-proxy: true
 x-internal: false