Skip to content
Try for free
On this page

MCP servers

Update MCP server

Update an external MCP server. Omitted fields remain unchanged unless a field specifies otherwise. Authentication changes revoke its stored OAuth grant and reset connection metadata; use List MCP server tools to reconnect. The endpoint URL is immutable. Requires workspace write access. OAuth scope: `api:write`.

PATCH/api/v2/mcp-servers/{mcpServerId}

Update an external MCP server. Omitted fields remain unchanged unless a field specifies otherwise. Authentication changes revoke its stored OAuth grant and reset connection metadata; use List MCP server tools to reconnect. The endpoint URL is immutable. Requires workspace write access.

OAuth scope: api:write.

Authentication

Send a personal or workspace API key in X-API-Key. See key types and access; operations that reject workspace keys say so in their description.

Send X-API-Key in the request header.

Alternatively

Send a Sim OAuth access token in Authorization: Bearer. See OAuth authentication and scopes.

Authorization: Bearer YOUR_ACCESS_TOKEN

Required scopes: api:write

OAuth flows
json
{
  "authorizationCode": {
    "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize",
    "tokenUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "refreshUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "scopes": {
      "api:read": "Read your workspaces, workflows, files, tables, and logs",
      "api:write": "Read, create, change, run, and delete resources in your workspaces",
      "offline_access": "Stay signed in without asking again"
    }
  }
}

OAuth scope: api:write.

Path parameters

mcpServerIdstringRequired

Unique MCP server identifier.

minLength
1

Request body

Required

MCP server fields to change; omitted fields retain their stored values.

object

MCP server fields to change; omitted fields retain their stored values.

12 fields
workspaceIdstringRequired

Workspace that owns the MCP server.

minLength
1
maxLength
128
namestring

Server display name.

minLength
1
maxLength
255
descriptionstring

Optional server description.

maxLength
2000
transportstring

Transport protocol. Defaults to streamable-http on creation.

default
streamable-http
enum
["streamable-http"]
urlstring

Immutable server URL. When provided, it must equal the current URL; use delete and create to change endpoints.

minLength
1
maxLength
2048
authTypestring

Authentication method. On creation, omission without headers probes once: an OAuth challenge selects oauth, an unauthenticated success selects none, and other outcomes fall back to headers. An OAuth client ID selects oauth when the method is omitted. Set explicitly to use headers with a server advertising OAuth; adding headers later does not change the saved method.

enum
["none","headers","oauth"]
headersobject

Write-only request headers sent to the server. Replaced wholesale rather than merged on update: sending this field drops every stored header it does not repeat.

writeOnly
true
Schema details
Additional propertiesstring

Header value sent to the MCP server.

timeoutinteger

Per-request timeout in milliseconds. Defaults to 30000 on creation.

default
30000
minimum
1000
maximum
300000
retriesinteger

Number of retries per request. Defaults to 3 on creation.

default
3
minimum
0
maximum
10
enabledboolean

Whether workflows can use the server's tools. Defaults to true on creation.

default
true
oauthClientIdvalue

Pre-registered OAuth client identifier. Changing it on update revokes the stored OAuth grant and forces reauthorization.

Schema details

Any of

Option 1string
maxLength
512
Option 2null
oauthClientSecretvalue

Write-only pre-registered OAuth client secret. Sending it on update as null or a new value revokes the stored OAuth grant and forces reauthorization, as does switching away from OAuth authentication.

writeOnly
true
Schema details

Any of

Option 1string
maxLength
2048
Option 2null

Additional properties are not allowed.

Request example 1

json
{
  "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
  "enabled": false
}

Responses

200

The updated MCP server.

object

The updated MCP server.

1 field
dataobjectRequired

Response data.

20 fields
idstringRequired

Unique server identifier derived from the workspace and endpoint URL.

namestringRequired

Server display name.

descriptionstring

Optional server description.

transportstringRequired

Transport used to communicate with the server.

default
streamable-http
enum
["streamable-http"]
authTypestring

Authentication method used by the server.

enum
["none","headers","oauth"]
urlstring

Server endpoint URL.

timeoutnumber

Per-request timeout in milliseconds.

retriesnumber

Number of retries attempted per request.

enabledbooleanRequired

Whether the server tools are available to workflows.

connectionStatusstring

Result of the most recent tool connection attempt. New registrations start disconnected; re-registration resets this state only when connection inputs change. Authentication probes do not establish a tool connection. Tool discovery updates this state.

enum
["connected","disconnected","error"]
lastErrorvalue

Message from the most recent failed tool connection, or null when absent. Successful discovery or re-registration with changed connection inputs clears it.

Schema details

Any of

Option 1string
Option 2null
toolCountnumber

Number of tools discovered on the server.

lastToolsRefreshstring

ISO 8601 timestamp of the most recent tool-list refresh.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
lastConnectedstring

ISO 8601 timestamp of the most recent successful tool connection. Absent until one succeeds, or after re-registration changes connection inputs.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
createdAtstringRequired

ISO 8601 timestamp when the server was registered.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
updatedAtstringRequired

ISO 8601 timestamp when the server was last updated.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
oauthClientIdstring

Pre-registered OAuth client identifier, when configured.

hasHeadersbooleanRequired

Whether any request headers are configured.

headerNamesarrayRequired

Names of configured request headers. Header values are never returned.

Schema details
Array itemstring

Configured header name.

hasOauthClientSecretbooleanRequired

Whether an OAuth client secret is stored. The value is never returned.

Additional properties are not allowed.

Additional properties are not allowed.

Response example 1

json
{
  "data": {
    "id": "mcp-3f7a9c21",
    "name": "Docs server",
    "description": "Internal documentation tools",
    "transport": "streamable-http",
    "authType": "headers",
    "url": "https://mcp.example.com/sse",
    "timeout": 30000,
    "retries": 3,
    "enabled": false,
    "connectionStatus": "connected",
    "lastError": null,
    "toolCount": 7,
    "lastToolsRefresh": "2026-06-20T14:02:11.000Z",
    "lastConnected": "2026-06-20T14:02:11.000Z",
    "createdAt": "2026-06-01T09:14:00.000Z",
    "updatedAt": "2026-06-20T14:02:11.000Z",
    "hasHeaders": true,
    "headerNames": [
      "Authorization"
    ],
    "hasOauthClientSecret": false
  }
}

Response headers

X-RateLimit-Limitinteger

Maximum requests allowed in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Remaininginteger

Requests remaining in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Resetstring

ISO 8601 timestamp when the current rate-limit window resets.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Was this helpful?
Suggest an edit