---
title: "Update Mcp Server Configuration"
method: PATCH
path: "/v1/convai/mcp-servers/{mcp_server_id}"
tags: ["Agents Platform"]
---

# Update Mcp Server Configuration

`PATCH /v1/convai/mcp-servers/{mcp_server_id}`

Update the configuration settings for an MCP server.

## Path parameters

- `mcp_server_id` string, required — ID of the MCP Server.

## Headers

- `xi-api-key` string, nullable — Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.

## Request body

- MCPServerConfigUpdateRequestModel — Unified request model for updating MCP Server configuration.
  - `approval_policy` 'auto_approve_all' | 'require_approval_all' | 'require_approval_per_tool' — Defines the MCP server-level approval policy for tool execution.
  - `force_pre_tool_speech` boolean, nullable — DEPRECATED: use `pre_tool_speech` instead. If set, overrides the server's force_pre_tool_speech setting for this tool.
  - `pre_tool_speech` 'auto' | 'force' | 'off'
  - `disable_interruptions` boolean, nullable — DEPRECATED: use `interruption_mode` instead. If set, overrides the server's disable_interruptions setting for this tool.
  - `interruption_mode` 'allow' | 'disable_during_tool' | 'disable_during_tool_and_turn'
  - `tool_call_sound` 'typing' | 'elevator1' | 'elevator2' | 'elevator3' | 'elevator4' — Predefined tool call sounds; ``None`` means no sound.
  - `tool_call_sound_behavior` 'auto' | 'always' — Determines how the tool call sound should be played.
  - `execution_mode` 'immediate' | 'post_tool_speech' | 'async'
  - `response_timeout_secs` integer, nullable — The maximum time in seconds to wait for each MCP tool call to complete.
  - `request_headers` object, nullable — The headers to include in requests to the MCP server
  - `request_meta` object, nullable — Entries sent in the MCP `_meta` field of tools/call requests. Values may be JSON scalars, or references to a workspace secret, dynamic variable, or environment variable resolved per call.
  - `disable_compression` boolean, nullable — Whether to disable HTTP compression for this MCP server
  - `secret_token` ConvAISecretLocator — Used to reference a secret from the agent's secret store.
    - `secret_id` string, required
  - `auth_connection` union — Optional auth connection to use for authentication with this MCP server
    - AuthConnectionLocator — Used to reference an auth connection from the workspace's auth connection store.
      - `auth_connection_id` string, required
    - EnvironmentAuthConnectionLocator — References an environment variable of type 'auth_connection' by label. At runtime, resolves to the auth connection for the current environment, falling back to the default environment.
      - `env_var_label` string, required

## Response `200`

Successful Response

- MCPServerResponseModel — Response model representing an MCP Server configuration.
  - `id` string, required
  - `config` MCPServerConfigOutput, required
    - `approval_policy` 'auto_approve_all' | 'require_approval_all' | 'require_approval_per_tool' — Defines the MCP server-level approval policy for tool execution.
    - `tool_approval_hashes` MCPToolApprovalHash[] — List of tool approval hashes for per-tool approval when approval_policy is REQUIRE_APPROVAL_PER_TOOL
      - `tool_name` string, required — The name of the MCP tool
      - `tool_hash` string, required — SHA256 hash of the tool's parameters and description
      - `approval_policy` 'auto_approved' | 'requires_approval' — Defines the tool-level approval policy.
    - `transport` 'SSE' | 'STREAMABLE_HTTP' — Supported MCP server transport types.
    - `url` union, required — The URL of the MCP server, if this contains a secret please store as a workspace secret, otherwise store as a plain string. Must use https
      - string
      - ConvAISecretLocator — Used to reference a secret from the agent's secret store.
        - `secret_id` string, required
    - `secret_token` union — The secret token (Authorization header) stored as a workspace secret or in-place secret
      - ConvAISecretLocator — Used to reference a secret from the agent's secret store.
        - `secret_id` string, required
      - ConvAIUserSecretDBModel — User-specific secret model that are not shared with other users in a workspace.
        - `name` string, required
        - `encrypted_value` string, required
        - `nonce` string, required
        - `id` string, required
    - `request_headers` object — The headers included in the request
    - `request_meta` object — Entries sent in the MCP `_meta` field of tools/call requests. Values may be JSON scalars, or references to a workspace secret, dynamic variable, or environment variable resolved per call.
    - `auth_connection` union — Optional auth connection to use for authentication with this MCP server
      - AuthConnectionLocator — Used to reference an auth connection from the workspace's auth connection store.
        - `auth_connection_id` string, required
      - EnvironmentAuthConnectionLocator — References an environment variable of type 'auth_connection' by label. At runtime, resolves to the auth connection for the current environment, falling back to the default environment.
        - `env_var_label` string, required
    - `name` string, required
    - `description` string
    - `force_pre_tool_speech` boolean — DEPRECATED: use `pre_tool_speech` instead. If true, all tools from this MCP server will require pre-tool execution speech.
    - `pre_tool_speech` 'auto' | 'force' | 'off'
    - `disable_interruptions` boolean — DEPRECATED: use `interruption_mode` instead. If true, the user will not be able to interrupt the agent while any tool from this MCP server is running.
    - `interruption_mode` 'allow' | 'disable_during_tool' | 'disable_during_tool_and_turn'
    - `tool_call_sound` 'typing' | 'elevator1' | 'elevator2' | 'elevator3' | 'elevator4' — Predefined tool call sounds; ``None`` means no sound.
    - `tool_call_sound_behavior` 'auto' | 'always' — Determines how the tool call sound should be played.
    - `execution_mode` 'immediate' | 'post_tool_speech' | 'async'
    - `response_timeout_secs` integer — The maximum time in seconds to wait for each MCP tool call to complete. Must be between 5 and 300 seconds (inclusive).
    - `tool_config_overrides` MCPToolConfigOverrideOutput[] — List of per-tool configuration overrides that override the server-level defaults for specific tools
      - `tool_name` string, required — The name of the MCP tool
      - `force_pre_tool_speech` boolean, nullable — DEPRECATED: use `pre_tool_speech` instead. If set, overrides the server's force_pre_tool_speech setting for this tool.
      - `pre_tool_speech` 'auto' | 'force' | 'off'
      - `disable_interruptions` boolean, nullable — DEPRECATED: use `interruption_mode` instead. If set, overrides the server's disable_interruptions setting for this tool.
      - `interruption_mode` 'allow' | 'disable_during_tool' | 'disable_during_tool_and_turn'
      - `tool_call_sound` union — Overrides the server's tool_call_sound setting for this tool. A sound name plays that sound; 'off' overrides to no sound (silence); null means do not override (inherit the server default).
        - 'typing' | 'elevator1' | 'elevator2' | 'elevator3' | 'elevator4' — Predefined tool call sounds; ``None`` means no sound.
        - 'off'
      - `tool_call_sound_behavior` 'auto' | 'always' — Determines how the tool call sound should be played.
      - `execution_mode` 'immediate' | 'post_tool_speech' | 'async'
      - `response_timeout_secs` integer, nullable — If set, overrides the server's response timeout for this MCP tool (seconds).
      - `assignments` DynamicVariableAssignment[] — Dynamic variable assignments for this MCP tool
        - `source` 'response' — The source to extract the value from. Currently only 'response' is supported.
        - `dynamic_variable` string, required — The name of the dynamic variable to assign the extracted value to
        - `value_path` string, required — Dot notation path to extract the value from the source (e.g., 'user.name' or 'data.0.id')
        - `sanitize` boolean — If true, this assignment's value will be removed from the tool response before sending to the LLM and transcript, but still processed for variable assignment.
        - `preserve_native_type` boolean — If true, non-scalar values (lists, objects) extracted from the tool response are stored as their native type instead of being stringified to JSON. Enable this to use extracted arrays directly as list dynamic variables.
      - `input_overrides` object, nullable — Mapping of json path to input override configuration
      - `response_mocks` ToolResponseMockConfigOutput[], nullable — Mock responses with optional parameter conditions. Evaluated top-to-bottom; first match wins.
        - `parameter_conditions` UnitTestToolCallParameter[] — If the list is empty, the mock will always activate.
          - `eval` union, required
            - LLMParameterEvaluationStrategy
              - …
            - RegexParameterEvaluationStrategy
              - …
            - ExactParameterEvaluationStrategy
              - …
            - MatchAnythingParameterEvaluationStrategy
              - …
          - `path` string, required
        - `mock_result` string, required — The return value the LLM sees when this mock is active.
        - `is_error` boolean — If true, the mock result is surfaced to the LLM as a tool error rather than a successful result.
    - `disable_compression` boolean — Whether to disable HTTP compression for this MCP server. Enable this if the server does not support compressed responses.
  - `access_info` ResourceAccessInfo
    - `is_creator` boolean, required — Whether the user making the request is the creator of the agent
    - `creator_name` string, required — Name of the agent's creator
    - `creator_email` string, required — Email of the agent's creator
    - `role` 'admin' | 'editor' | 'commenter' | 'viewer', required — The role of the user making the request
    - `anonymous_access_level_override` 'admin' | 'editor' | 'commenter' | 'viewer', nullable — The access level for anonymous users. If None, the resource is not shared publicly.
    - `access_source` 'creator' | 'explicit' | 'workspace_admin' | 'workspace_default', nullable — Why the requesting user has access to this resource. 'creator' = caller is the owner. 'explicit' = caller (or one of their workspace groups) is listed in role_to_group_ids beyond the workspace-wide everyone group. 'workspace_default' = the workspace-wide everyone group is listed in role_to_group_ids (every non-anon workspace member, including admins, sees this resource). 'workspace_admin' = caller is a workspace admin and the admin seat is the *only* path to access; reserved for docs nobody else can see. Lets the UI disclose why an admin-bypass viewer sees a doc that wasn't explicitly shared with them.
  - `dependent_agents` union[] — List of agents that depend on this MCP Server.
    - union
      - DependentAvailableAgentIdentifier
        - `referenced_resource_ids` string[] — If the agent is a transitive dependent, contains IDs of the resources that the agent depends on directly.
        - `id` string, required
        - `name` string, required
        - `type` 'available'
        - `created_at_unix_secs` integer, required
        - `access_level` 'admin' | 'editor' | 'commenter' | 'viewer', required
      - DependentUnknownAgentIdentifier — A model that represents an agent dependent on a knowledge base/tools to which the user has no direct access.
        - `referenced_resource_ids` string[] — If the agent is a transitive dependent, contains IDs of the resources that the agent depends on directly.
        - `id` string, required
        - `type` 'unknown'
  - `metadata` MCPServerMetadataResponseModel, required
    - `created_at` integer, required
    - `owner_user_id` string, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/elevenlabs/apis/elevenlabs-api-documentation.md) · [All operations](https://skmtc.net/elevenlabs/apis/elevenlabs-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/elevenlabs/elevenlabs-api-documentation/versions/57d56f34628a/schema)