---
title: "Create or replace MCP server"
method: PUT
path: "/v1/mcp_server"
tags: ["McpServers"]
---

# Create or replace MCP server

`PUT /v1/mcp_server`

## Request

- Base URL: `https://api.braintrust.dev`
- URL: `https://api.braintrust.dev/v1/mcp_server`
- Auth: one of:
  - HTTP bearer
  - none

Create or replace MCP server. If there is an existing MCP server with the same name as the one specified in the request, will replace the existing MCP server with the provided fields

## Request body

- CreateMCPServer
  - `project_id` string, uuid, required: Unique identifier for the project that the MCP server belongs under
  - `name` string, required: Name of the MCP server. Within a project, MCP server names are unique
  - `description` string, nullable: Textual description of the MCP server
  - `url` string, required: URL of the MCP server endpoint

## Response `200`

Returns the new MCP server object

- MCPServer
  - `id` string, uuid, required: Unique identifier for the MCP server
  - `project_id` string, uuid, required: Unique identifier for the project that the MCP server belongs under
  - `user_id` string, uuid, nullable: Identifies the user who created the MCP server
  - `created` string, date-time, nullable: Date of MCP server creation
  - `deleted_at` string, date-time, nullable: Date of MCP server deletion, or null if the MCP server is still active
  - `name` string, required: Name of the MCP server. Within a project, MCP server names are unique
  - `description` string, nullable: Textual description of the MCP server
  - `url` string, required: URL of the MCP server endpoint

## Other responses

- `400`: The request was unacceptable, often due to missing a required parameter
- `401`: No valid API key provided
- `403`: The API key doesn’t have permissions to perform the request
- `429`: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
- `500`: Something went wrong on Braintrust's end. (These are rare.)

## Changes

- **2026-10-30** `8f5039399f77`: 1 breaking
  - the request property `description` became not nullable
- **2026-09-03** `ebac33c1422e`: 1 breaking
  - request body became required
- **2025-12-04** `b6967d956e2f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/braintrustdata/apis/braintrust-api/changes/v1/mcp_server/put.md)

---

[API](https://skmtc.dev/braintrustdata/apis/braintrust-api.md) - [All operations](https://skmtc.dev/braintrustdata/apis/braintrust-api/llms.txt) - [OpenAPI document](https://skmtc.dev/braintrustdata/apis/braintrust-api/revisions/19184ec94018?raw)