> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-chore-regenerate-agent-sdk-openapi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Patch Mcp Server

> Sparsely update one existing named MCP server.



## OpenAPI

````yaml /openapi/agent-sdk.json patch /api/settings/mcp/{settings_key}
openapi: 3.1.0
info:
  description: OpenHands Agent Server - REST/WebSocket interface for OpenHands AI Agent
  title: OpenHands Agent Server
  version: 1.52.0
servers: []
security: []
paths:
  /api/settings/mcp/{settings_key}:
    patch:
      tags:
        - Settings
      summary: Patch Mcp Server
      description: Sparsely update one existing named MCP server.
      operationId: patch_mcp_server_api_settings_mcp__settings_key__patch
      parameters:
        - in: path
          name: settings_key
          required: true
          schema:
            title: Settings Key
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MCPServerPatch'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettingsResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
        - APIKeyHeader: []
components:
  schemas:
    MCPServerPatch:
      additionalProperties: false
      description: Sparse RFC 7386 merge patch for one persisted MCP server.
      properties:
        args:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Args
        auth:
          anyOf:
            - discriminator:
                mapping:
                  api_key: '#/components/schemas/MCPApiKeyAuthCredential-Input'
                  basic: '#/components/schemas/MCPBasicAuthCredential-Input'
                  bearer: '#/components/schemas/MCPBearerAuthCredential-Input'
                  header: '#/components/schemas/MCPHeaderAuthCredential-Input'
                  none: '#/components/schemas/MCPNoneAuthCredential'
                  oauth2: '#/components/schemas/MCPOAuthAuthCredential-Input'
                propertyName: strategy
              oneOf:
                - $ref: '#/components/schemas/MCPNoneAuthCredential'
                - $ref: '#/components/schemas/MCPApiKeyAuthCredential-Input'
                - $ref: '#/components/schemas/MCPBearerAuthCredential-Input'
                - $ref: '#/components/schemas/MCPBasicAuthCredential-Input'
                - $ref: '#/components/schemas/MCPHeaderAuthCredential-Input'
                - $ref: '#/components/schemas/MCPOAuthAuthCredential-Input'
            - type: 'null'
          title: Auth
        command:
          anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          title: Command
        cwd:
          anyOf:
            - type: string
            - type: 'null'
          title: Cwd
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          description: >-
            Switch the server off (false) or back on (true) without touching the
            rest of its configuration. A null clears the override, which
            restores the canonical default (enabled).
          title: Enabled
        env:
          anyOf:
            - additionalProperties:
                anyOf:
                  - format: password
                    type: string
                    writeOnly: true
                  - type: 'null'
              type: object
            - type: 'null'
          title: Env
        headers:
          anyOf:
            - additionalProperties:
                anyOf:
                  - format: password
                    type: string
                    writeOnly: true
                  - type: 'null'
              type: object
            - type: 'null'
          title: Headers
        icon:
          anyOf:
            - type: string
            - type: 'null'
          title: Icon
        keep_alive:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Keep Alive
        sse_read_timeout:
          anyOf:
            - type: number
            - type: 'null'
          title: Sse Read Timeout
        timeout:
          anyOf:
            - type: number
            - type: 'null'
          title: Timeout
        transport:
          anyOf:
            - enum:
                - stdio
                - http
                - sse
                - streamable-http
              type: string
            - type: 'null'
          title: Transport
        url:
          anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          title: Url
      title: MCPServerPatch
      type: object
    SettingsResponse:
      description: >-
        Response model for GET /api/settings.


        Contains the full settings payload including agent configuration,

        conversation settings, active LLM profile, miscellaneous frontend-owned

        settings, and a flag indicating whether an LLM API key is set.


        The ``agent_settings`` and ``conversation_settings`` fields are raw
        dicts

        because the server controls secret serialization via context. Use the

        typed accessor methods for validation:


        Example::

            response = SettingsResponse.model_validate(api_response.json())
            agent = response.get_agent_settings()  # Returns AgentSettingsConfig
            conv = response.get_conversation_settings()  # Returns ConversationSettings

        ``misc_settings`` is an opaque container for frontend-owned data that
        the

        agent-server persists but does not interpret — see the docstring of

        :class:`PersistedSettings.misc_settings`.
      properties:
        active_agent_profile_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Stable id of the currently active AgentProfile, if one is set.
          title: Active Agent Profile Id
        active_meta_profile:
          anyOf:
            - type: string
            - type: 'null'
          description: Name of the currently active meta-profile, if one is selected.
          title: Active Meta Profile
        active_profile:
          anyOf:
            - type: string
            - type: 'null'
          description: Name of the currently active LLM profile, if one is selected.
          title: Active Profile
        agent_settings:
          additionalProperties: true
          properties:
            agent_kind:
              anyOf:
                - enum:
                    - openhands
                    - acp
                  type: string
                - type: 'null'
              title: Agent Kind
            mcp_config:
              $ref: '#/components/schemas/MCPConfig'
            schema_version:
              anyOf:
                - minimum: 1
                  type: integer
                - type: 'null'
              title: Schema Version
          required:
            - mcp_config
          title: _AgentSettingsContract
          type: object
        conversation_settings:
          additionalProperties: true
          title: Conversation Settings
          type: object
        llm_api_key_is_set:
          title: Llm Api Key Is Set
          type: boolean
        misc_settings:
          additionalProperties: true
          title: Misc Settings
          type: object
      required:
        - agent_settings
        - conversation_settings
        - llm_api_key_is_set
      title: SettingsResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    MCPApiKeyAuthCredential-Input:
      properties:
        header_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Header Name
        strategy:
          const: api_key
          title: Strategy
          type: string
        value:
          anyOf:
            - format: password
              type: string
              writeOnly: true
            - type: 'null'
          title: Value
      required:
        - strategy
      title: MCPApiKeyAuthCredential
      type: object
    MCPBasicAuthCredential-Input:
      properties:
        password:
          anyOf:
            - format: password
              type: string
              writeOnly: true
            - type: 'null'
          title: Password
        strategy:
          const: basic
          title: Strategy
          type: string
        username:
          title: Username
          type: string
      required:
        - strategy
        - username
      title: MCPBasicAuthCredential
      type: object
    MCPBearerAuthCredential-Input:
      properties:
        strategy:
          const: bearer
          title: Strategy
          type: string
        value:
          anyOf:
            - format: password
              type: string
              writeOnly: true
            - type: 'null'
          title: Value
      required:
        - strategy
      title: MCPBearerAuthCredential
      type: object
    MCPHeaderAuthCredential-Input:
      properties:
        headers:
          additionalProperties:
            format: password
            type: string
            writeOnly: true
          title: Headers
          type: object
        strategy:
          const: header
          title: Strategy
          type: string
      required:
        - strategy
      title: MCPHeaderAuthCredential
      type: object
    MCPNoneAuthCredential:
      properties:
        strategy:
          const: none
          title: Strategy
          type: string
      required:
        - strategy
      title: MCPNoneAuthCredential
      type: object
    MCPOAuthAuthCredential-Input:
      properties:
        authentication:
          anyOf:
            - $ref: '#/components/schemas/MCPOAuthAuthentication-Input'
            - type: 'null'
        state:
          anyOf:
            - $ref: '#/components/schemas/MCPOAuthState-Input'
            - type: 'null'
        strategy:
          const: oauth2
          title: Strategy
          type: string
      required:
        - strategy
      title: MCPOAuthAuthCredential
      type: object
    MCPConfig:
      additionalProperties:
        $ref: '#/components/schemas/MCPServer-Output'
      description: Canonical persisted MCP server map keyed by stable server name.
      title: MCPConfig
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
    MCPOAuthAuthentication-Input:
      additionalProperties: false
      properties:
        additional_client_metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Additional Client Metadata
        client_auth_method:
          anyOf:
            - enum:
                - none
                - client_secret_post
                - client_secret_basic
                - private_key_jwt
              type: string
            - type: 'null'
          title: Client Auth Method
        client_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Id
        client_metadata_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Metadata Url
        client_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Name
        client_secret:
          anyOf:
            - format: password
              type: string
              writeOnly: true
            - type: 'null'
          title: Client Secret
        scopes:
          anyOf:
            - type: string
            - items:
                type: string
              type: array
            - type: 'null'
          title: Scopes
        type:
          const: oauth
          title: Type
          type: string
      required:
        - type
      title: MCPOAuthAuthentication
      type: object
    MCPOAuthState-Input:
      properties:
        client_info:
          anyOf:
            - $ref: '#/components/schemas/MCPOAuthClientInfoState-Input'
            - type: 'null'
        token_expires_at:
          anyOf:
            - type: number
            - type: 'null'
          title: Token Expires At
        tokens:
          anyOf:
            - $ref: '#/components/schemas/MCPOAuthTokenState-Input'
            - type: 'null'
      title: MCPOAuthState
      type: object
    MCPServer-Output:
      additionalProperties: false
      description: One MCP server in the settings DataModel.
      properties:
        args:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Args
        auth:
          anyOf:
            - discriminator:
                mapping:
                  api_key: '#/components/schemas/MCPApiKeyAuthCredential-Output'
                  basic: '#/components/schemas/MCPBasicAuthCredential-Output'
                  bearer: '#/components/schemas/MCPBearerAuthCredential-Output'
                  header: '#/components/schemas/MCPHeaderAuthCredential-Output'
                  none: '#/components/schemas/MCPNoneAuthCredential'
                  oauth2: '#/components/schemas/MCPOAuthAuthCredential-Output'
                propertyName: strategy
              oneOf:
                - $ref: '#/components/schemas/MCPNoneAuthCredential'
                - $ref: '#/components/schemas/MCPApiKeyAuthCredential-Output'
                - $ref: '#/components/schemas/MCPBearerAuthCredential-Output'
                - $ref: '#/components/schemas/MCPBasicAuthCredential-Output'
                - $ref: '#/components/schemas/MCPHeaderAuthCredential-Output'
                - $ref: '#/components/schemas/MCPOAuthAuthCredential-Output'
            - type: 'null'
          title: Auth
        command:
          anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          title: Command
        cwd:
          anyOf:
            - type: string
            - type: 'null'
          title: Cwd
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        enabled:
          default: true
          description: >-
            Whether this server is exposed to the agent. A disabled server stays
            fully configured -- including its secrets -- but is skipped when MCP
            tools are created and when servers are forwarded to an ACP
            subprocess.
          title: Enabled
          type: boolean
        env:
          anyOf:
            - additionalProperties:
                anyOf:
                  - type: string
                  - type: 'null'
              type: object
            - type: 'null'
          title: Env
        headers:
          anyOf:
            - additionalProperties:
                anyOf:
                  - type: string
                  - type: 'null'
              type: object
            - type: 'null'
          title: Headers
        icon:
          anyOf:
            - type: string
            - type: 'null'
          title: Icon
        keep_alive:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Keep Alive
        sse_read_timeout:
          anyOf:
            - type: number
            - type: 'null'
          title: Sse Read Timeout
        timeout:
          anyOf:
            - type: number
            - type: 'null'
          title: Timeout
        transport:
          anyOf:
            - enum:
                - stdio
                - http
                - sse
                - streamable-http
              type: string
            - type: 'null'
          title: Transport
        url:
          anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          title: Url
      title: MCPServer
      type: object
    MCPOAuthClientInfoState-Input:
      additionalProperties: true
      properties:
        client_secret:
          anyOf:
            - format: password
              type: string
              writeOnly: true
            - type: 'null'
          title: Client Secret
      title: MCPOAuthClientInfoState
      type: object
    MCPOAuthTokenState-Input:
      additionalProperties: true
      properties:
        access_token:
          anyOf:
            - format: password
              type: string
              writeOnly: true
            - type: 'null'
          title: Access Token
        refresh_token:
          anyOf:
            - format: password
              type: string
              writeOnly: true
            - type: 'null'
          title: Refresh Token
      title: MCPOAuthTokenState
      type: object
    MCPApiKeyAuthCredential-Output:
      properties:
        header_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Header Name
        strategy:
          const: api_key
          title: Strategy
          type: string
        value:
          anyOf:
            - type: string
            - type: 'null'
          title: Value
      required:
        - strategy
      title: MCPApiKeyAuthCredential
      type: object
    MCPBasicAuthCredential-Output:
      properties:
        password:
          anyOf:
            - type: string
            - type: 'null'
          title: Password
        strategy:
          const: basic
          title: Strategy
          type: string
        username:
          title: Username
          type: string
      required:
        - strategy
        - username
      title: MCPBasicAuthCredential
      type: object
    MCPBearerAuthCredential-Output:
      properties:
        strategy:
          const: bearer
          title: Strategy
          type: string
        value:
          anyOf:
            - type: string
            - type: 'null'
          title: Value
      required:
        - strategy
      title: MCPBearerAuthCredential
      type: object
    MCPHeaderAuthCredential-Output:
      properties:
        headers:
          additionalProperties:
            anyOf:
              - type: string
              - type: 'null'
          title: Headers
          type: object
        strategy:
          const: header
          title: Strategy
          type: string
      required:
        - strategy
      title: MCPHeaderAuthCredential
      type: object
    MCPOAuthAuthCredential-Output:
      properties:
        authentication:
          anyOf:
            - $ref: '#/components/schemas/MCPOAuthAuthentication-Output'
            - type: 'null'
        state:
          anyOf:
            - $ref: '#/components/schemas/MCPOAuthState-Output'
            - type: 'null'
        strategy:
          const: oauth2
          title: Strategy
          type: string
      required:
        - strategy
      title: MCPOAuthAuthCredential
      type: object
    MCPOAuthAuthentication-Output:
      additionalProperties: false
      properties:
        additional_client_metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Additional Client Metadata
        client_auth_method:
          anyOf:
            - enum:
                - none
                - client_secret_post
                - client_secret_basic
                - private_key_jwt
              type: string
            - type: 'null'
          title: Client Auth Method
        client_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Id
        client_metadata_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Metadata Url
        client_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Name
        client_secret:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Secret
        scopes:
          anyOf:
            - type: string
            - items:
                type: string
              type: array
            - type: 'null'
          title: Scopes
        type:
          const: oauth
          title: Type
          type: string
      required:
        - type
      title: MCPOAuthAuthentication
      type: object
    MCPOAuthState-Output:
      properties:
        client_info:
          anyOf:
            - $ref: '#/components/schemas/MCPOAuthClientInfoState-Output'
            - type: 'null'
        token_expires_at:
          anyOf:
            - type: number
            - type: 'null'
          title: Token Expires At
        tokens:
          anyOf:
            - $ref: '#/components/schemas/MCPOAuthTokenState-Output'
            - type: 'null'
      title: MCPOAuthState
      type: object
    MCPOAuthClientInfoState-Output:
      additionalProperties: true
      properties:
        client_secret:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Secret
      title: MCPOAuthClientInfoState
      type: object
    MCPOAuthTokenState-Output:
      additionalProperties: true
      properties:
        access_token:
          anyOf:
            - type: string
            - type: 'null'
          title: Access Token
        refresh_token:
          anyOf:
            - type: string
            - type: 'null'
          title: Refresh Token
      title: MCPOAuthTokenState
      type: object
  securitySchemes:
    APIKeyHeader:
      in: header
      name: X-Session-API-Key
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.