---
title: "Replace MCP server"
method: PUT
path: "/api/v1/mcp-servers/{id}"
tags: ["MCP Servers"]
---

# Replace MCP server

`PUT /api/v1/mcp-servers/{id}`

Replaces an MCP server definition when `If-Match` matches the current MCP server revision.

## Path parameters

- `id` string, required

## Headers

- `If-Match` string, required

## Request body

- ReplaceMcpServerRequest — Request body for replacing an MCP server definition. The path id is authoritative.
  - `display_name` string, required — Human-readable label for display in management UIs.
  - `description` string, nullable
  - `transport` union, required — MCP server transport configuration. The `type` field selects stdio, HTTP, or sandbox transport. Unknown `type` discriminator values are reported as domain validation errors with HTTP 422.
    - McpTransportStdio — Stdio transport that launches a local MCP server subprocess.
      - `type` 'stdio', required
      - `command` string[], required — Command and arguments used to launch the MCP server.
      - `env` StringMap, required
    - McpTransportHttp — HTTP transport that connects to a remote MCP server URL.
      - `type` 'http', required
      - `protocol` 'streamable_http' | 'sse' — Wire protocol used by HTTP and sandbox MCP transports.
      - `url` string, uri, required
      - `headers` StringMap, required
    - McpTransportSandbox — Sandbox transport that launches the MCP server inside the run sandbox and connects over HTTP.
      - `type` 'sandbox', required
      - `protocol` 'streamable_http' | 'sse' — Wire protocol used by HTTP and sandbox MCP transports.
      - `command` string[], required — Command and arguments used to launch the in-sandbox MCP server.
      - `port` integer, required
      - `env` StringMap, required
  - `startup_timeout_secs` integer, required
  - `tool_timeout_secs` integer, required

## Response `200`

MCP server replaced

- McpServer — Public server-managed MCP server definition. Transport env/header values are never returned.
  - `id` string, required — Stable MCP server identifier, used as the runtime MCP server name in qualified tool names.
  - `revision` string, required — Stable revision used with `If-Match` for optimistic concurrency.
  - `display_name` string, required — Human-readable label for display in management UIs.
  - `description` string, nullable, required
  - `transport` union, required — MCP server transport configuration returned by catalog read APIs.
    - McpTransportViewStdio — Stdio transport view. Environment variable values are omitted.
      - `type` 'stdio', required
      - `command` string[], required — Command and arguments used to launch the MCP server.
      - `env_keys` string[], required — Environment variable names configured for this transport.
    - McpTransportViewHttp — HTTP transport view. Header values are omitted.
      - `type` 'http', required
      - `protocol` 'streamable_http' | 'sse' — Wire protocol used by HTTP and sandbox MCP transports.
      - `url` string, uri, required
      - `header_keys` string[], required — HTTP header names configured for this transport.
    - McpTransportViewSandbox — Sandbox transport view. Environment variable values are omitted.
      - `type` 'sandbox', required
      - `protocol` 'streamable_http' | 'sse' — Wire protocol used by HTTP and sandbox MCP transports.
      - `command` string[], required — Command and arguments used to launch the in-sandbox MCP server.
      - `port` integer, required
      - `env_keys` string[], required — Environment variable names configured for this transport.
  - `startup_timeout_secs` integer, required — Seconds to wait for the MCP server to become ready at connect time.
  - `tool_timeout_secs` integer, required — Seconds to allow each MCP tool call before timing out.

## Other responses

- `400` — Malformed JSON request body, invalid MCP server id, or invalid revision header
- `404` — MCP server not found
- `409` — MCP server revision mismatch
- `422` — MCP server failed domain validation
- `428` — Missing required `If-Match` header
- `500` — MCP server store operation failed

---

[API](https://skmtc.net/fabro-sh/apis/fabro-run-api.md) · [All operations](https://skmtc.net/fabro-sh/apis/fabro-run-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fabro-sh/fabro-run-api/versions/bee030053823/schema)