---
title: "Add or update an MCP server"
method: PUT
path: "/v1/mcp-servers/{name}"
tags: ["MCP"]
---

# Add or update an MCP server

`PUT /v1/mcp-servers/{name}`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/mcp-servers/{name}`
- Auth: HTTP bearer

Upserts an MCP server config. If no server with `name` exists it is
installed; otherwise it is updated and restarted. The body `name` must
match the path `name`. For `transport: stdio` the `stdio` block is
required; for `transport: http-sse` the `httpSSE` block is required.

## Path parameters

- `name` string, required

## Request body

- object
  - `id` string, uuid, required
  - `name` string, required
  - `enabled` boolean, required
  - `transport` 'stdio' | 'http-sse', required
  - `stdio` object, nullable
    - `command` string
    - `args` string[]
    - `env` object
    - `cwd` string, nullable
  - `httpSSE` object, nullable
    - `url` string
    - `headers` object
  - `auth` object, nullable
    - `type` 'oauth'
    - `provider` string
    - `scopes` string[]
  - `source` string, nullable
  - `registryID` string, nullable
  - `createdAt` string, date-time, required

## Response `200`

Server added or updated

- McpServerEntry
  - `name` string, required
  - `registryID` string, nullable
  - `transport` 'stdio' | 'http-sse', required
  - `enabled` boolean, required
  - `status` 'running' | 'starting' | 'failed' | 'stopped', required
  - `toolCount` integer, required

## Other responses

- `400`: Invalid request
- `409`: Name collision on add
- `502`: initialize or tools/list failed

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)