> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slng.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update MCP Server

> Apply a partial update. The fields you send are merged over the stored configuration, then the merged url_template, auth, headers, and Vault secret references are re-validated. Changing connection behavior resets discovered capabilities and reschedules a probe.



## OpenAPI

````yaml /api-reference/agents/shared-resources.oas.yaml patch /v1/agents/mcp-servers/{server_id}
openapi: 3.1.0
info:
  title: SLNG Agent Resources API
  version: 1.0.0
  description: >-
    Public control-plane API for agent resources: tools, MCP servers, Vault
    secrets and variables, and client models.
servers:
  - url: https://api.agents.slng.ai
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Tools
    description: Create, test, publish, version, and attach agent tools.
    x-page-icon: wrench
  - name: MCP servers
    description: Configure MCP servers and refresh their live capabilities.
    x-page-icon: plug
  - name: Vault
    description: >-
      Store organisation secrets and readable variables without exposing secret
      values.
    x-page-icon: key
  - name: Client models
    description: Manage bring-your-own LLM provider credentials.
    x-page-icon: brain
paths:
  /v1/agents/mcp-servers/{server_id}:
    patch:
      tags:
        - MCP servers
      summary: Update MCP Server
      description: >-
        Apply a partial update. The fields you send are merged over the stored
        configuration, then the merged url_template, auth, headers, and Vault
        secret references are re-validated. Changing connection behavior resets
        discovered capabilities and reschedules a probe.
      operationId: updateMcp
      parameters:
        - name: server_id
          in: path
          required: true
          description: >-
            UUID of the MCP server to update. A server in another organisation
            or one that is soft-deleted returns 404.
          schema:
            type: string
            format: uuid
            title: Server Id
      requestBody:
        required: true
        description: Fields to change on the MCP server.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpServerUpdate'
            examples:
              Rename:
                summary: Rename the MCP server
                value:
                  name: crawler-prod
              Change authentication:
                summary: Switch to bearer auth with a rotated Vault secret
                value:
                  auth:
                    type: bearer
                    secret_name: MCP_TOKEN
                  credentials:
                    - mode: create
                      secret_name: MCP_TOKEN
                      value: rotated-secret-789
      responses:
        '200':
          description: The updated MCP server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServer'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    McpServerUpdate:
      description: >-
        Partial update for an MCP server. Only the fields you supply change;
        omitted fields keep their stored values.
      properties:
        name:
          anyOf:
            - type: string
              maxLength: 200
              minLength: 1
            - type: 'null'
          title: Name
        url_template:
          anyOf:
            - type: string
              maxLength: 2000
              minLength: 1
            - type: 'null'
          description: >-
            New endpoint URL for the MCP server. Supports {{$NAME}} Vault secret
            placeholders.
          title: Url Template
        transport:
          anyOf:
            - type: string
              enum:
                - streamable_http
                - sse
            - type: 'null'
          description: New transport for the MCP server, either `streamable_http` or `sse`.
          title: Transport
        description:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          description: >-
            Optional human-readable description of the MCP server. Omit to keep
            the current value.
          title: Description
        auth:
          anyOf:
            - oneOf:
                - $ref: '#/components/schemas/McpNoAuth'
                - $ref: '#/components/schemas/McpBearerAuth'
                - $ref: '#/components/schemas/McpHeaderAuth'
              discriminator:
                propertyName: type
                mapping:
                  bearer:
                    $ref: '#/components/schemas/McpBearerAuth'
                  header:
                    $ref: '#/components/schemas/McpHeaderAuth'
                  none:
                    $ref: '#/components/schemas/McpNoAuth'
            - type: 'null'
          title: Auth
        headers:
          anyOf:
            - items:
                oneOf:
                  - $ref: '#/components/schemas/McpLiteralHeader'
                  - $ref: '#/components/schemas/McpVaultHeader'
                discriminator:
                  propertyName: type
                  mapping:
                    literal:
                      $ref: '#/components/schemas/McpLiteralHeader'
                    vault:
                      $ref: '#/components/schemas/McpVaultHeader'
              type: array
              maxItems: 64
            - type: 'null'
          description: >-
            Replacement set of request headers. Each header is a literal value
            or a Vault secret reference.
          title: Headers
        credentials:
          anyOf:
            - items:
                oneOf:
                  - $ref: '#/components/schemas/McpExistingCredential'
                  - $ref: '#/components/schemas/McpCreateCredential'
                discriminator:
                  propertyName: mode
                  mapping:
                    create:
                      $ref: '#/components/schemas/McpCreateCredential'
                    existing:
                      $ref: '#/components/schemas/McpExistingCredential'
              type: array
              maxItems: 64
            - type: 'null'
          description: >-
            Vault secrets to create or reference for the updated configuration.
            Every supplied credential name must be referenced.
          title: Credentials
      additionalProperties: false
      type: object
      title: McpServerUpdate
      example:
        description: Web crawler tools (staging)
        auth:
          type: none
    McpServer:
      description: >-
        Stored MCP server record with its configuration and the latest
        discovered capability state. Secret values and transient credential
        input never appear here.
      properties:
        id:
          type: string
          format: uuid
          title: Id
        organisation_id:
          type: string
          format: uuid
          title: Organisation Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        transport:
          type: string
          enum:
            - streamable_http
            - sse
          description: >-
            Transport used to reach the MCP server: `streamable_http` for
            streamable HTTP, or `sse` for Server-Sent Events.
          title: Transport
        url_template:
          type: string
          description: >-
            Stored endpoint URL for the MCP server. Any {{$NAME}} Vault secret
            placeholders are kept verbatim and resolved at connection time.
          title: Url Template
        auth:
          oneOf:
            - $ref: '#/components/schemas/McpNoAuth'
            - $ref: '#/components/schemas/McpBearerAuth'
            - $ref: '#/components/schemas/McpHeaderAuth'
          title: Auth
          discriminator:
            propertyName: type
            mapping:
              bearer:
                $ref: '#/components/schemas/McpBearerAuth'
              header:
                $ref: '#/components/schemas/McpHeaderAuth'
              none:
                $ref: '#/components/schemas/McpNoAuth'
        headers:
          items:
            oneOf:
              - $ref: '#/components/schemas/McpLiteralHeader'
              - $ref: '#/components/schemas/McpVaultHeader'
            discriminator:
              propertyName: type
              mapping:
                literal:
                  $ref: '#/components/schemas/McpLiteralHeader'
                vault:
                  $ref: '#/components/schemas/McpVaultHeader'
          type: array
          description: >-
            Stored request headers for the MCP server; each value is inline or
            resolved from a Vault secret.
          title: Headers
        revision:
          type: integer
          title: Revision
        capability_status:
          type: string
          enum:
            - unknown
            - healthy
            - unavailable
            - invalid
            - circuit_open
          description: >-
            Health of the MCP server capabilities: `unknown` (not probed yet),
            `healthy` (reachable and tools discovered), `unavailable` (probe
            failed or unreachable), `invalid` (reachable but returned an
            unsupported contract), or `circuit_open` (temporarily disabled after
            repeated failures and retried after a cooldown).
          title: Capability Status
        capability_revision:
          type: integer
          title: Capability Revision
        capability_observed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Capability Observed At
        capability_attempted_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Capability Attempted At
        capabilities_hash:
          anyOf:
            - type: string
            - type: 'null'
          title: Capabilities Hash
        capabilities:
          anyOf:
            - $ref: '#/components/schemas/McpCapabilities'
            - type: 'null'
        capability_error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Capability Error Code
        capability_error_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Capability Error Message
        capability_tool_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Capability Tool Count
        next_refresh_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Next Refresh At
      type: object
      required:
        - id
        - organisation_id
        - name
        - transport
        - url_template
        - auth
        - revision
        - capability_status
        - capability_revision
      title: McpServer
    McpNoAuth:
      properties:
        type:
          type: string
          const: none
          title: Type
          default: none
      additionalProperties: false
      type: object
      title: No authentication
      description: Send requests to the MCP server without an Authorization header.
    McpBearerAuth:
      properties:
        type:
          type: string
          const: bearer
          title: Type
        secret_name:
          type: string
          maxLength: 64
          minLength: 1
          title: Secret Name
      additionalProperties: false
      type: object
      required:
        - type
        - secret_name
      title: Bearer token
      description: >-
        Send `Authorization: Bearer <token>`, where the token is a Vault secret
        referenced by `secret_name`.
    McpHeaderAuth:
      properties:
        type:
          type: string
          const: header
          title: Type
        name:
          type: string
          maxLength: 200
          minLength: 1
          title: Name
        secret_name:
          type: string
          maxLength: 64
          minLength: 1
          title: Secret Name
      additionalProperties: false
      type: object
      required:
        - type
        - name
        - secret_name
      title: Custom auth header
      description: >-
        Send a named header whose value is a Vault secret referenced by
        `secret_name`.
    McpLiteralHeader:
      properties:
        type:
          type: string
          const: literal
          title: Type
        name:
          type: string
          maxLength: 200
          minLength: 1
          title: Name
        value:
          type: string
          maxLength: 4000
          title: Value
      additionalProperties: false
      type: object
      required:
        - type
        - name
        - value
      title: Literal header
      description: A request header with a fixed, inline value.
    McpVaultHeader:
      properties:
        type:
          type: string
          const: vault
          title: Type
        name:
          type: string
          maxLength: 200
          minLength: 1
          title: Name
        secret_name:
          type: string
          maxLength: 64
          minLength: 1
          title: Secret Name
      additionalProperties: false
      type: object
      required:
        - type
        - name
        - secret_name
      title: Vault-backed header
      description: >-
        A request header whose value is resolved from a Vault secret referenced
        by `secret_name`.
    McpExistingCredential:
      properties:
        mode:
          type: string
          const: existing
          title: Mode
        secret_name:
          type: string
          maxLength: 64
          minLength: 1
          title: Secret Name
      additionalProperties: false
      type: object
      required:
        - mode
        - secret_name
      title: Use an existing Vault secret
      description: Reference a secret already stored in Vault by `secret_name`.
    McpCreateCredential:
      properties:
        mode:
          type: string
          const: create
          title: Mode
        secret_name:
          type: string
          maxLength: 64
          minLength: 1
          title: Secret Name
        value:
          type: string
          maxLength: 32768
          minLength: 1
          title: Value
          writeOnly: true
      additionalProperties: false
      type: object
      required:
        - mode
        - secret_name
        - value
      title: Create a new Vault secret
      description: >-
        Store a new secret value in Vault under `secret_name`. The value is
        write-only and never returned.
    McpCapabilities:
      description: >-
        Tools discovered from the MCP server, with flags for whether discovery
        was truncated and how many pages were fetched.
      properties:
        tools:
          items:
            $ref: '#/components/schemas/McpTool'
          type: array
          title: Tools
        truncated:
          type: boolean
          title: Truncated
          default: false
        pages_fetched:
          type: integer
          minimum: 0
          title: Pages Fetched
          default: 0
      additionalProperties: false
      type: object
      title: McpCapabilities
    ApiErrorResponse:
      type: object
      description: Standard error envelope returned for failed requests.
      required:
        - detail
        - error
      properties:
        detail:
          type: string
          description: Short human-readable summary of the error.
        error:
          $ref: '#/components/schemas/ApiErrorDetail'
      example:
        detail: A shared secret or variable named 'STRIPE_KEY' already exists
        error:
          code: RESOURCE_CONFLICT
          message: A shared secret or variable named 'STRIPE_KEY' already exists
          request_id: 018f9b2c-7e4a-7c3d-9a1b-2c3d4e5f6a7b
    McpTool:
      description: >-
        A tool exposed by the MCP server, with its input and output JSON schemas
        and a hash used to detect schema drift.
      properties:
        name:
          type: string
          maxLength: 200
          minLength: 1
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        input_schema:
          additionalProperties: true
          type: object
          title: Input Schema
        output_schema:
          anyOf:
            - type: object
              additionalProperties: true
            - type: 'null'
          title: Output Schema
        schema_hash:
          type: string
          pattern: ^[0-9a-f]{64}$
          title: Schema Hash
      additionalProperties: false
      type: object
      required:
        - name
        - schema_hash
      title: McpTool
    ApiErrorDetail:
      type: object
      description: Structured error detail carried inside an error response.
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Stable machine-readable error code.
          example: RESOURCE_CONFLICT
        message:
          type: string
          description: Human-readable explanation of the error.
          example: A shared secret or variable named STRIPE_KEY already exists
        request_id:
          type:
            - string
            - 'null'
          description: Identifier for this request, useful when contacting support.
          example: req_01H8XY7Z9QEXAMPLE
        retryable:
          type: boolean
          description: Whether retrying the same request may succeed.
          example: false
        fields:
          type: array
          description: >-
            Per-field validation problems, when the error relates to specific
            request fields.
          items:
            type: object
            additionalProperties: true
          example: []
      example:
        code: PUBLIC_SHARED_RESOURCES_DISABLED
        message: Public shared resources are disabled for this organisation
        request_id: req_01H8XY7Z9QEXAMPLE
        retryable: false
  responses:
    UnauthorizedError:
      description: The API key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            detail: Invalid API key
            error:
              code: AUTH_REQUIRED
              message: Invalid API key
              request_id: 018f9b2c-7e4a-7c3d-9a1b-2c3d4e5f6a7b
              retryable: false
    ForbiddenError:
      description: >-
        The caller lacks permission, or the public shared-resource API is
        disabled for the organisation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          examples:
            permission_denied:
              summary: Owner or admin access required
              value:
                detail: Organisation owner or admin access required
                error:
                  code: PERMISSION_DENIED
                  message: Organisation owner or admin access required
                  request_id: 018f9b2c-7e4a-7c3d-9a1b-2c3d4e5f6a7b
                  retryable: false
            api_disabled:
              summary: Public shared-resource API disabled for the organisation
              value:
                detail: >-
                  Public shared-resource API access is disabled for this
                  organisation
                error:
                  code: PUBLIC_SHARED_RESOURCES_DISABLED
                  message: >-
                    Public shared-resource API access is disabled for this
                    organisation
                  request_id: 018f9b2c-7e4a-7c3d-9a1b-2c3d4e5f6a7b
                  retryable: false
    NotFoundError:
      description: The requested resource does not exist for this organisation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            detail: The requested resource was not found.
            error:
              code: RESOURCE_NOT_FOUND
              message: The requested resource was not found.
              request_id: 018f9b2c-7e4a-7c3d-9a1b-2c3d4e5f6a7b
    ConflictError:
      description: The request conflicts with the current state of the resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            detail: The request conflicts with the current state of the resource.
            error:
              code: RESOURCE_CONFLICT
              message: The request conflicts with the current state of the resource.
              request_id: 018f9b2c-7e4a-7c3d-9a1b-2c3d4e5f6a7b
    ValidationError:
      description: Request validation failed. See error.fields for the offending fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            detail: >-
              Request validation failed. Fix the highlighted fields and try
              again.
            error:
              code: VALIDATION_FAILED
              message: >-
                Request validation failed. Fix the highlighted fields and try
                again.
              request_id: 018f9b2c-7e4a-7c3d-9a1b-2c3d4e5f6a7b
              retryable: false
              fields:
                - path: name
                  message: >-
                    Name must be SCREAMING_SNAKE_CASE: start with a letter, then
                    letters, digits, or underscores (e.g. STRIPE_API_KEY)
    RateLimitError:
      description: >-
        The organisation exceeded its request rate limit. Retry after the window
        resets.
      headers:
        Retry-After:
          schema:
            type: integer
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            detail: Rate limit exceeded. Maximum 60 requests per 60 seconds.
            error:
              code: INTERNAL_ERROR
              message: Rate limit exceeded. Maximum 60 requests per 60 seconds.
              request_id: 018f9b2c-7e4a-7c3d-9a1b-2c3d4e5f6a7b
              retryable: false
    InternalServerError:
      description: The request failed unexpectedly. Secret values are never exposed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            detail: An unexpected error occurred.
            error:
              code: INTERNAL_ERROR
              message: An unexpected error occurred.
              request_id: 018f9b2c-7e4a-7c3d-9a1b-2c3d4e5f6a7b
              retryable: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: SLNG API key
      description: Your SLNG consumer API key.

````